Multiplayer

How rooms work

Your Game still cannot open network connections. The play page owns the Realtime connection, presence, message storage, and sender identity, and passes events to your Game through window.MiraDock. Messages are stored before they are broadcast, and the host checks for missed messages every 5 seconds, so every member sees the same ordered stream.

Signed-in Players can create rooms. Guests can join with a code and appear as Guest Player with an id that changes on every page load. When the host Player leaves, the earliest remaining member becomes host, including guests. A room closes as soon as it is empty.

Create a room

Register handlers right after the room resolves. The host buffers initial membership and catch-up messages until your handler is registered.

const ctx = await MiraDock.ready();
if (MiraDock.capabilities.multiplayer) {
  const room = await MiraDock.multiplayer.create({ maxPlayers: 2 });
  if (room.status === "signin_required") {
    // Guests cannot create rooms. The host has already offered sign-in.
  } else {
    showCode(room.joinCode); // Six characters, e.g. "K7P2QX"
    await room.on("players", (players) => renderLobby(players));
    await room.on("message", ({ from, seq, payload }) => apply(from, payload));
    await room.on("closed", ({ reason }) => backToMenu(reason));
    await room.send({ type: "hello" });
  }
}

Join by code and invite links

The play page shows a lobby outside your Game with the code, an invite link, the current Players with a host marker, capacity, and a Leave button. Opening /play/your-game?room=CODE joins that room once after MiraDock.ready(). If the invite is invalid, full, or closed, the host shows a message and your Game continues in its single-Player state.

// A friend types the code shown by the room creator.
const room = await MiraDock.multiplayer.join(codeFromInput);

// Invite links (/play/your-game?room=CODE) are joined by the host after ready().
await MiraDock.on("joined", async ({ joinCode }) => {
  const invited = await MiraDock.multiplayer.join(joinCode); // no second server join
  await invited.on("players", renderLobby);
  await invited.on("message", ({ from, payload }) => apply(from, payload));
});

Room API

Room events

Realtime multiplayer

The room host's browser simulates the game. It opens a WebRTC pair to each member; members connect only to the host. The play page owns all connections and signaling, so the Game iframe keeps its network sandbox. A host can cheat; paid rewards must never depend on realtime outcomes. Check MiraDock.capabilities.multiplayer.realtime.

const rt = await room.realtime();
rt.on("data", ({ from, payload, fast }) => applyPeerData(from, payload));
rt.on("peers", peers => showQuality(peers));
rt.on("host", ({ hostId, reason }) => restoreLatestSnapshot(hostId));
// A peer sends input to the host. The host sends snapshots to all peers.
await rt.send({ type: "input", dx: 1 }, { to: rt.hostId, fast: true });
console.log(rt.stats()); // peer RTT, transport, relay availability

Each pair has ordered reliable and unordered fast channels. Send JSON or ArrayBuffer payloads up to 16 KiB. Each peer may send 60 fast or 20 reliable packets per second; extra sends reject with rate_limited. Non-hosts may send only to the host. At join and right after a host migration, a send to a player whose connection is not up yet does not reject: a fast send is skipped and its id listed in the resolved dropped array; a reliable send waits up to 20 seconds, then delivers or rejects with timeout. The host that left counts as such a player until your host handler switches targets. rt.on("data") receives sender-stamped data; peers and host events report connection quality and host migration. The game must carry its own state to a new host. Signaling stays private and ephemeral. Public STUN is the default; optional TURN credentials are minted server-side. If a pair cannot connect within 10 seconds, it falls back to the room relay and reports transport: "relay". Connections start when a Player joins, so call room.realtime() on every client right after joining; send must-arrive events on the reliable channel and treat relay data the same as WebRTC data.

Simulate on the host at 30 Hz, send snapshots at 20 Hz on fast, send peer inputs on fast, and use reliable for round events. Interpolate snapshots on peers. See Arena Dash for a 2–6 Player reference.

Limits

Sends and membership changes count as room activity; presence and reading do not. When a room expires, its messages are deleted. If a Player needs history older than the last 200 messages, ask a peer for the current state.

Reference Game

Two-player Tap Duel shows room creation, joining by code, guest guidance, solo practice, and invite auto-join. The full contract, including error codes, is in the Game SDK specification.