dungeoncraft/docs/MULTIPLAYER.md

Multiplayer - plan and status

Multiplayer is only available for users of a server (not in the standalone file).

Decisions

• Modes: versus (every player a master with an own heart), coop (every player an own master, together against AI masters and/or the humans) and a coop campaign of 20 missions.
• 1 to 4 players per match; free slots are empty unless the host marks them as AI with set_ai before the start.
• The match pauses while a player is missing (connection lost); a player who leaves is replaced by an AI.
• Before the start, the host manually marks a free seat as AI with {"t":"set_ai","side":n,"ai":true} and clears it again with ai:false; side 0 stays human.
• The humans (hero waves of the Order) as a third party (can be switched off), chat, alliances/teams.
• Coop is "separate but helpful": own heart, gold, mana, research and creatures; allies never fight each other, their creatures help each other, gold can be sent, allied ground can be walked; a fallen heart only knocks out that player (who may keep watching); the allies win when all enemies have fallen.
• Lobby: an open list of matches under Multiplayer in the title menu; the host chooses mode, map, AI slots, humans on/off and teams; logged-in users join; the match starts when everybody is ready.

Architecture: deterministic lockstep

Every client runs the same simulation (the same WASM module, so floating point results are identical). The server does not simulate; it relays:

1. Clients send their commands (dig, build, cast, hand, orders, ...) to the server.
2. Every 100 ms the server sends turn N: the commands of all players for that turn.
3. Each client applies turn N and simulates five fixed steps of 20 ms. Turns arrive in order; a client waits for the next turn, so a missing player stalls everybody - exactly the "pause while missing" rule.
4. Clients send a checksum of the game state every few seconds; a mismatch (desync) is reported.

Only the commands travel over the network, so bandwidth is tiny and no game state has to be serialised per turn. Fog of war, particles and the camera are local and not part of the shared state.

What is there already

• Per-master state (game.rs): every master has his own gold, mana, hand, research, payday, flag, core... Game::switch_to(side) puts one master in the active fields, the simulation walks through all masters step by step. A single player game has no stored masters and is unaffected.
• Commands (commands.rs): every order a player gives is an Act (Dig, Room, Tower, Trap, Cast, Flag, Pickup, Drop, Slap, Attack, Guard, CancelOrders, ...) wrapped in a Command { side, seq, act }. Creature targets are ids, so they mean the same on every client. The tools in main.rs only queue commands now - nothing touches the world directly.
• Steps: the simulation runs in fixed steps of STEP = 20 ms, 50 steps a second (Game::update feeds real time into them, Game::apply_turn(cmds, steps) is the lockstep entry point; one server turn of 100 ms is five steps). Commands are applied at step boundaries, so single player and a match run exactly the same path. Particles, effects and the camera keep running in real time: they are local and not part of the shared state.
• Who speaks: messages, hints and interface sounds belong to the master who is being processed (Game::speaking); what another master orders never shows up on my screen.
• Turns and checksums (netplay.rs): Game::start_match(sides, local) starts a match, Game::take_orders() hands the local orders to the server, Game::receive_turn(cmds) applies a confirmed turn (five steps) and Game::checksum() compares the worlds of the clients - a peer with a different number is reported once (net.desync). A client without the next turn stands still: that is the "pause while missing" rule, and the tests run two clients of one match side by side.
• Savegames, tests and the standalone file are unchanged: cargo test --release covers the command path (including "the same actions on both paths build the same world").

Server and client

• Relay (server/src/netplay.rs, route /api/netplay/ws, proxied by nginx): rooms with a six-letter code, seats, ready flags, a 100 ms turn clock, checksum forwarding, chat (all / team channel), pause when a player is missing (resume by side 0), abort, leave (a started human seat becomes AI-controlled), set_ai for empty seats before the start, and a ping/pong round trip. The message list is at the top of the file.
• Client bridge (src/lobby.rs, WebSocket in www/dc_plugin.js): MatchClient turns orders into JSON and turns back into commands, tracks the lobby state (rooms, seats, AI seats), chat and the relay ping (ping_ms, shown by the ping debug overlay).
• Menu: Multiplayer in the title menu with the match list, create (versus or co-op mission), join by code, seat choice, AI seat toggles for the host, ready/start, chat; the match keeps running in the background while menus are open.
• AI seats (Game::sync_ai_sides): empty seats marked by the host and seats of players who left are played by the simplified rival AI on every client, so they stay deterministic.
• Co-op (Game::coop): the master sides are allies against the heroes; allied creatures never target each other, allied ground does not block claims. Co-op campaign matches use campaign::start_coop_mission.
• Editor campaigns in co-op: on the Match page the host can switch from the built-in campaign to the campaign last opened in the editor (Menu::campaign_doc) and pick one of its missions that fits co-op (campaign::is_editor_coop_mission: map at least 72x72, a goal besides rival masters). The create message carries the whole campaign ("doc", the CampaignDoc JSON, up to MAX_WS_MESSAGE = 40 MB per WebSocket message); the relay keeps it in the room and adds it to the start message (room updates only show "editor": true). Every client builds the mission with campaign::start_editor_coop_mission(doc, i, seed) from the room's shared seed (rival masters of the map and the Rivals goal are left out, like in built-in co-op), then the usual co-op setup. Block scripts run from side 0 in the fixed step. When the mission ends, the match ends and the players go back to the lobby; there is no branching to a next mission and no progress is stored.
• Shared simulation side: the shared part of a step (waves, units, towers, rivals, dwarves) runs with the first master switched in on every client; only the end check and the fog use the local master.

Steps

#	Step	Status
A	Simulation per master: gold, mana, research, rooms, hand, flag, traps, payday... per side; up to four masters (red, green, blue, yellow)	built
B	All player actions as commands (Command + Game::apply), single player uses the same path; fixed time step	built
C	Server: lobby and match relay over WebSocket (axum), turns, pause on disconnect, AI takeover on leave, chat, ping	built
D	Client: Multiplayer menu (lobby, create, join, seats, ready), WebSocket bridge in dc_plugin.js, chat, ping	built
E	Alliances and co-op rules, AI masters for free and abandoned seats	partly built: co-op alliance and AI seats work; free teams in versus and sending gold are missing
F	Co-op campaign: 20 missions with story (EN/DE)	partly built: co-op matches reuse the single player missions that fit the master areas (coop_mission_indexes); no own co-op missions or story yet

Still open: teams/alliances in versus, sending gold to allies, own co-op campaign missions with story; still to be checked against the decisions above: a fallen heart only knocking out that player (who may keep watching), and how savegames treat a running match.

Masters and sides

A match plays on the four master sides 0, 2, 3, 4 (side 1 is the heroes'): red (side 0, Owner::Player), green (Owner::Rival1), blue (Owner::Rival2) and yellow (Owner::Rival3). Game::start_masters(sides, local) carves a 9x9 starting area and a 3x3 soul core for every master and remembers his economy in a MasterState; the places are worked out from the map size alone, so all clients agree without passing them over the network.