Skip to content

Seamless co-op and split screen: design draft - #701

Draft
featureJosh wants to merge 1 commit into
mainfrom
feat/seamless-coop
Draft

featureJosh wants to merge 1 commit into
mainfrom
feat/seamless-coop

Conversation

@featureJosh

Copy link
Copy Markdown
Collaborator

What it changes

Design draft, no code yet: the plan for seamless co-op and for split screen on top of it. Both features ship in the same release. This PR is where the design is discussed; the work lands in later commits or PRs, step by step (Build order below).

Why

Today's Story co-op runs one story per player inside the host's world. That is behind the reports: visitors do not learn abilities their host learned, and quests desync in the visitor's world. Two stories against one world need workarounds (held quests, per-visitor pickups, talk overrides), and each of them leaks.

Principles

  1. One story, owned by the host. For everything that matters the group counts as one player: a quest accepted is accepted for everyone, an ability learned is learned by everyone in the session.
  2. Coop saves are separate from singleplayer saves. A coop save is played only in coop mode. A player's singleplayer save is never touched by a session.
  3. The group is forced together. In coop mode connecting is not a choice: the launcher and the game connect the group on their own, and nobody plays a coop save alone or visits another island.
  4. The game's Link Play is the transport, the rules are ours. No netcode of our own: Link Play already replicates avatars, block edits, items and Pokémon. We decide when it starts, what the menus allow and what is saved.
  5. Every replacement is backed up and can be undone from the launcher.

Coop saves (launcher)

  • A coop save is a launcher profile marked as coop, with a save folder of its own. Profiles already give each player a folder (profiles.rs).
  • Launching a coop profile turns the coop settings on for that launch only, through the environment (as split screen does). Nothing is written to pkp.ini.
  • A normal launch refuses a coop save; a coop launch refuses a singleplayer one.
  • Copy between modes ("Copy to singleplayer", "Start coop from my singleplayer save") with saveimport::copy_account.
  • The coop profile records the group's members and a world version that goes up after every session.
  • A coop profile only connects to its own group's room on the relay, never the public list.

Session lifecycle

  1. Only the host starts a coop save. Visitors join by receiving the host's save and never build a story of their own.
  2. Every player makes their own character. Each visitor goes through character creation; their first save after it is caught, only their name, look and UUID are kept, and their window waits.
  3. The host plays alone to the Link Play unlock (Environment Level 2), the earliest point the game allows a session.
  4. The session starts on its own. The host invites and the visitors join without the PC menu. Link Play in the PC menu is locked, so nobody leaves or opens another session.
  5. The launcher waits for the whole group before it starts the game on a coop profile.
  6. A dropped visitor goes to a waiting screen, never back to their own copy of the island. A dropped host chooses to pause and wait, or to end the session; the host does not play on alone by default.

Save sync after a session

Every member's coop save becomes the host's save with that member's identity stamped back in.

Part Taken from Why
World (STGDAT) Host The world the group played in
Story, quests, abilities, flags (CMNDAT) Host One story for the group
Player UUID Member Two saves with one UUID are refused (error 9005)
Name and appearance Member Each player keeps the character they made
  • The host sends a snapshot whenever it saves during the session. Each visitor keeps the latest as a pending sync file, so a crash or a lost connection still leaves a usable copy.
  • The launcher applies it with the game closed (the game keeps the save in memory and writes it back), after a backup, with a Revert button.
  • The UUID stamp is pkp_save_uuid.cpp's machinery (swap_uuid in Split screen: two to four players on one PC #692). Name and appearance are more fields on the same path.
  • When the group meets, the save with the highest world version hosts and the others take its copy. Two copies that moved apart (two players hosted alone) are caught: the launcher asks which to keep and backs up the other. Nothing is merged silently.
  • Roles can change between sessions: whoever hosts next hosts the copy everyone received last time.

Split screen on the coop setup

Split screen (#692) becomes a coop group whose members share one PC. It keeps its windows, layout and controllers; its saves follow the coop rules.

Today in #692 With the coop setup
A player without a save copies player 1's and looks like player 1 Every player makes their own character, stamped into the copy of the host's save
With no save, every window starts its own new game and the stories drift apart Visitors stop after character creation and wait; only the host plays the story
The players meet by hand (PC, Link Play, invite, visit) The session starts on its own; the Link Play menu is locked
Visitor saves are ordinary profiles that can also be played alone Split screen saves are coop saves, played only in a coop launch

#692 lands first; coop builds on it.

Open questions

  • Where the character's name and look sit in CMNDAT (the fields are known; their place in the file is next).
  • Where abilities are stored, and whether they belong to the player or the world.
  • The flag that unlocks Link Play, so the session can start right after character creation.
  • How the game sends a visitor home on a disconnect, so coop mode can show a waiting screen instead.
  • Which PC menu entries to lock, through the existing menu hooks.
  • How big a full save snapshot is to send over the relay.
  • The mode's name on the wire, so older builds are refused cleanly (multiplayer stays compatible: a mismatch is refused, never desynced).
  • Who takes which step.

Build order

  1. Coop profiles in the launcher: own folder, coop settings at launch, refusal on a normal launch, copy between modes, private room, members and world version.
  2. Automatic session at the unlock; visitors wait after character creation; Link Play menu locked; disconnect goes to a waiting screen.
  3. Host owns the story: visitors run no story of their own, abilities mirrored live, story_hold and story_pickups removed.
  4. Sync after every session: host snapshots, applied by the launcher with the game closed, member identity stamped back, backup and Revert.
  5. Later: set the unlock flag at new game, so the session starts right after character creation.

Pros

  • Removes the whole class of desync bugs: one story, one world.
  • A player's singleplayer save is never at risk.
  • Reuses what exists: profiles, copy_account, the UUID swap, split screen's per-window roles, the game's own Link Play.
  • Split screen and online co-op share one model.

Cons

  • Visitors do not progress a story of their own; a coop save always follows the host's.
  • A coop group cannot start together before the Link Play unlock until step 5.
  • Hand-copied save folders can still get around the rules; they are caught and reversible, not prevented.
  • Needs reverse-engineering before steps 2 to 4 (Open questions).

For players

  • CHANGELOG.md ## Unreleased has an entry (Before / Now / Still not), or this change is not player-facing: design only, no change yet
  • Needs Set up again / Finish update: no
  • Rebuilds shaders: no

🤖 Generated with Claude Code

The plan for seamless co-op (one story owned by the host, coop saves
separate from singleplayer saves, the group connected automatically,
the host's world synced to every member after a session) and for split
screen on top of it. Design only; the work follows step by step.

Co-Authored-By: Claude <noreply@anthropic.com>
@Piktrip

Piktrip commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Findings from the split screen work (#692) that answer some of the open questions here. Addresses are for main 2.0.1 (build 76a489f3).

The session can start without the menu, and before the Link Play unlock

  • The game has one session manager ([[main+0x3561780] + 0x11f0], u32 state at +0, 0 = idle). The frame update 0x103a7e0 works on it every frame, menu open or not. The multiplayer menu (step function 0xf282a8) only makes requests of it.
  • "Local connection, no password" is three calls. Host: 0xe7d644(manager). Visitor: 0xe7d8d0(manager, 0) to search (the found count is at +0x1358 once the manager is idle again), then 0xe7ffc8(0) to join the first one.
  • The manager does the rest itself: it saves, opens or joins, and starts the visitor's trip to the host's world. The session bits (online + host, online + visitor) follow.
  • None of the three asks for Environment Level 2. With a save from before the unlock, and in a new game from the first cave, the session opens and the visitor arrives. So "the host plays alone to the unlock" and build step 5 may not be needed.

Host owns the story

  • At the mask site in pkp_linkplay.cpp (0xb1030), x20 is the builder's host flag (w2 of 0xb0f60). Keeping the story bit only while it is set gives: the host's story runs, visitors get Palette Town's permissions and no story of their own. The visitor's talk override then has to stay off for them.

Where a visitor arrives

  • Always at the PC, wherever the host is. In a new game the host is in the first cave and cannot be reached from there.
  • The local player's position is the save data's ([main+0x3561930] + 0x7419f0, while the character's mode word at +0x5a34 is 0) plus the character's copy at +0x20c0. Writing both moves the player in both games. The host's character is the player manager's second one (+0x38) in a session of two.
  • A spot the player cannot stand on sends them back to the arrival point; the host's own spot works.

What exists as code
A feature on top of #692 ([split] meet, set by the launcher for a split screen start): window 1 opens the session once its player walks, the others search and join, and an arrived visitor is put where the host stands. I can open it as a PR for build step 2, or hand over the pieces. Your call who takes which step.

Not answered by this work
Where abilities are stored, and what the game does to a visitor on a disconnect.

Related: #700 (heap damage in the renderer with two game processes on one PC) showed up three times during these runs.

@featureJosh

Copy link
Copy Markdown
Collaborator Author

Thanks, that settles the session start and the unlock: build step 5 can go, and the session can open right after character creation. Findings from the save and story side (main 2.0.1, same build):

Abilities

  • They are m_functionFlag, 256 bits at [main+0x3561930] + 0x4a26a8, the first field of the story block. In the save it is decompressed CMNDAT 0x220f04, 32 bytes (the live bytes match there and nowhere else).
  • The bits only grow with progress: 5, 19, 47, 48, 50 bits set across one player's saves, none cleared. Which bit is which move is not mapped yet.
  • Writers: event command 0x10c0d0, script command 0x12c35c, quest effect type 0x19 (0x1227fc). The quest tables use that effect only twice (quests 174 and 176, bit 99), so moves come from event scripts, not quest rewards.
  • In a session the game already sends each member's own flags: 0x535240 fills a 0xb8-byte record per player (name, an id, the flag bits at +0x59) at [main+0x3561930] + 0x14c2a40, from session start (0x534c74) and while online (0xeb1f90).
  • For the design: the host's CMNDAT carries the bits, so the sync after a session gives visitors the host's abilities. Live, the host's 32 bytes can be copied onto every visitor.

Link Play menu

  • Your step function 0xf282a8 is a state machine: state at +0xa4, entries a vector of 0x14-byte records at +0xd0 (count +0xd8). State 1 refuses while the session manager is not idle.
  • It checks three save bytes before some entries (+0x6d817b bit 2, +0x6d818b bit 0, +0x6d819b bit 0, each with its own message). They look like "explained once" flags, not unlocks.
  • Locking it in coop: refuse every Link Play entry there while coop mode is on.

Character look is the 12-byte record at decompressed CMNDAT 0x21ff84 (sex, hair, hat, bag, upper, lower, shoes, then colours). With the UUID and the name in SYDAT, that is what to stamp back into a member's copy of the host's save.

Still open: the disconnect. The session-lost event (type id 0x5393cfbd) has no direct users; subscribers go through the type registry. It needs a two-instance log, which means two PCs given #700.

On who takes which step: if you open [split] meet as the PR for build step 2, the story gating at the mask site and the menu lock fit on top of it.

@Piktrip

Piktrip commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Build step 2 is open as #705 (draft, on top of #692).

  • [split] meet: the windows open and join the session on their own, with a waiting screen for the joining window and a switch in the launcher.
  • [split] together: a visitor is taken from the PC to where the first player stands, with the game's own warp of a player. That covers the new game, where the first cave cannot be reached from the PC.
  • Not in it: the story gating at the mask site and the menu lock. They fit on top.

The functions it calls and the steps of a visitor's arrival are in the mappings repository, split/SPLIT-SESSION-RE.md (sections 2, 5 and 8).

@featureJosh

Copy link
Copy Markdown
Collaborator Author

The disconnect (main 2.0.1, same build). Checked with two instances: host killed while the visitor was in its world, visitor logged.

What the visitor gets:

  1. ~5.7 s after the last packet the link is reported down and LDN leaves the network.
  2. Error applet 3103, "Communication error. Please wait and try again".
  3. A home trip is filed in the stage-change request at [main+0x3561710] + 0x3bb600 (kind 0xE, target = own home stage [main+0x3561930] + 0xa4), runs, and the game state resets (0xb0d74). The visitor's own world reloads.
  4. Next boot: "In your last session, you did not disconnect correctly."

The Link Play session manager is not involved: its state stayed 0 the whole time. The trip comes from 0xbca8c, a check the request's per-frame step (0xbaf54) runs while no request is pending. When the session is gone (0x24347c() false) and the player is a visitor (GM+0x90 bit 2) or on someone else's stage, it files kind 0xE (a host away from its own stage gets kind 10). A host on its own stage gets a cleanup with no trip (0xbd548). The P2P library's 3 s recovery window (SessionLost, 0x1b99edc) runs before all of this.

For coop mode: the waiting screen hooks 0xbca8c where it files the home trip (wait for the host instead), and holds back the 3103 applet while waiting. The other trip filers, for reference: 0xbd45c (reason -> kind 7..0xe) and 0xbe5f0 (trips the host sends, from its message handler 0x54f1f4).

@lenase0077

Copy link
Copy Markdown

I picked up build step 1 (Co-op profiles in the launcher) and opened a draft PR in #724 on top of main.

Summary of what is included:

  • coop metadata on Profile (room_code, relay, members, world_version) with its own save folder (<save_dir>/account/<uid_key>/) and no writes to pkp.ini.
  • Launch-only environment injection (NXRT_ACCOUNT_*, NXRT_NET_*, NXRT_PKP_COOP=1, NXRT_PKP_COOP_WORLD_VERSION) via play_coop, plus strict mode separation (play / --play refuse co-op saves; play_coop refuses singleplayer saves).
  • saveimport::copy_account (matching Split screen: two to four players on one PC #692's signature so either order merges cleanly) and mode copy actions (Start coop from my singleplayer save / Copy to singleplayer).
  • Private 80-bit Crockford base32 room code (XXXX-XXXX-XXXX-XXXX), optional custom relay, member list, world_version bump after each session, and launcher UI + 9-language i18n.

Note for the runtime / next steps: runtime/src/services/ldn_native.cpp (native_node()) does not yet read [net] room_code / NXRT_NET_ROOM_CODE when relay is set, so rooms stay publicly listed until that wiring lands alongside steps 2–4.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants