Multiplayer contract

turn-duel — the chess pattern (host vs joiner, alternating turns)

Side mapping is anchored on connection.getMyRole() (room creator = side A; joiner = side B) with an index-fallback for legacy/standalone paths. Use B3MP.pickByRole so the SDK does the role→side map for you.

// Define your two sides as constants.
const SIDE_A = 0  // chess: GOLD, X-O: X, etc.
const SIDE_B = 1  // chess: SILVER, X-O: O

window.B3Multiplayer = {
  init({ players, myId }) {
    // CR.14 E2.1 — single source of truth for mySide.
    // Role-first; index-fallback only when role is unavailable.
    const role = connection.getMyRole?.()  // requires mp-client.js
    const indexFallback = (players.findIndex(p => p.id === myId) === 0) ? SIDE_A : SIDE_B
    state.mySide = B3MP.pickByRole(role, {
      host:    SIDE_A,
      joiner:  SIDE_B,
      fallback: indexFallback,
    })
    state.turn = SIDE_A  // first move always belongs to side A
    state.myId = myId
  },
  // ...
}

Click handler gates on TWO conditions: my piece, my turn. Both must be true. Then broadcast via ctx.emit AND apply locally — the server doesn't echo your own input back to you (memory of pain: this is a real footgun if you skip the local apply).

function onPieceClick(piece) {
  if (piece.side !== state.mySide) return       // not my piece
  if (state.turn !== state.mySide) return       // not my turn
  // ... show legal-move highlights ...
}

function onSquareClick(targetGx, targetGz) {
  const move = { from: state.selected, to: { gx: targetGx, gz: targetGz } }

  // 1. Broadcast to the other client.
  B3.ctx.emit('input', { t: 'move', from: move.from, to: move.to, fromSide: state.mySide })

  // 2. Apply LOCALLY (server fan-out skips sender).
  applyMove(move, /*fromNet*/ false)
}

Tick drain processes remote inputs. Each client buffers incoming inputs in a b3Intent map keyed by playerId; tick drains and applies them via the same apply function (with a from-net flag to suppress re-broadcast).

onInput(playerId, input) {
  // Don't apply immediately — buffer for tick to drain in deterministic order.
  if (!b3Intent[playerId]) b3Intent[playerId] = {}
  b3Intent[playerId].pendingMove = input
},

tick(dtMs) {
  // Process queued remote moves in playerId-sorted order (deterministic).
  for (const playerId of Object.keys(b3Intent).sort()) {
    const pending = b3Intent[playerId].pendingMove
    if (!pending) continue
    delete b3Intent[playerId].pendingMove
    applyMove(pending, /*fromNet*/ true)  // _fromNet=true suppresses echo
  }
},

Anti-patterns to avoid:

• Don't re-derive mySide in init from member-index alone. If host bounces and reconnects, joinedAt sort puts joiner first → side flips mid-game. Always anchor on getMyRole() first.
• Don't bypass your apply function (e.g., ctx.emit without local-apply). The server uses broadcastExcept(sender); you won't see your own input echoed back. The local state stays stale and subsequent peer inputs get rejected by your turn gate.
• Don't forget the from-net flag. Without it, the apply triggers another ctx.emit → infinite loop.

realtime-duel — the pong pattern (2 players, every-tick input)

Side mapping uses the same role-anchor pattern as turn-duel — but there's no turn gate. Both players send input every tick (paddle position, fighter movement, ship thrust). The server fans inputs each tick; both clients apply ALL inputs in deterministic order.

const SIDE_LEFT = 0
const SIDE_RIGHT = 1

window.B3Multiplayer = {
  init({ players, myId }) {
    const role = connection.getMyRole?.()
    state.mySide = B3MP.pickByRole(role, {
      host:    SIDE_LEFT,
      joiner:  SIDE_RIGHT,
      fallback: (players.findIndex(p => p.id === myId) === 0) ? SIDE_LEFT : SIDE_RIGHT,
    })
    state.paddles = { [SIDE_LEFT]: { y: 0 }, [SIDE_RIGHT]: { y: 0 } }
    state.myId = myId
  },
  // ...
}

Input is captured on every keydown/keyup and broadcast via ctx.emit. There's NO gate on whose turn it is — both players always control their own paddle.

document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowUp')   B3.ctx.emit('input', { dir: 'up',   phase: 'down' })
  if (e.key === 'ArrowDown') B3.ctx.emit('input', { dir: 'down', phase: 'down' })
})
document.addEventListener('keyup', (e) => {
  if (e.key === 'ArrowUp')   B3.ctx.emit('input', { dir: 'up',   phase: 'up' })
  if (e.key === 'ArrowDown') B3.ctx.emit('input', { dir: 'down', phase: 'up' })
})

Tick + onInput apply EACH player's input to THEIR OWN side. Use the playerId in onInput to look up that player's side (members[].role tells you who is host vs joiner; or just compare playerId to members[0].id for the host).

onInput(playerId, input) {
  const side = (playerId === hostMemberId) ? SIDE_LEFT : SIDE_RIGHT
  intentByPlayer[playerId] = { side, dir: input.dir, phase: input.phase }
},

tick(dtMs) {
  // Apply each player's intent to their paddle.
  for (const playerId of Object.keys(intentByPlayer).sort()) {
    const i = intentByPlayer[playerId]
    if (!i) continue
    const speed = i.phase === 'down' ? 200 : 0
    state.paddles[i.side].y += (i.dir === 'up' ? -speed : speed) * dtMs / 1000
  }
  // Advance ball, check collisions, etc.
}

Anti-patterns to avoid: same as turn-duel for side-derivation. Plus:

• Don't gate input on a turn variable. realtime games are concurrent; both players always have agency. The "turn" concept doesn't apply.
• Don't read live keyboard state in tick. Inputs must flow through ctx.emit so the OPPONENT receives them too. Direct keyboard reads desync.

turn-party — N-player round-robin (Mario Party, Risk)

Side mapping is by member-index, not role. 3-8 players each control a single avatar; role only tells you who CREATED the room (for "Host can start" UI). Use members[] position for fine-grained side.

window.B3Multiplayer = {
  init({ players, myId }) {
    // Index in the authoritative roster IS your seat number.
    state.mySeat = players.findIndex(p => p.id === myId)
    state.players = players.map((p, i) => ({ ...p, seat: i, score: 0 }))
    state.currentSeat = 0  // round-robin pointer; first player goes first
    state.myId = myId
  },
  // ...
}

Click handler gates on state.currentSeat === state.mySeat. After your turn ends, currentSeat = (currentSeat + 1) % players.length.

Use connection.getMyRole() ONLY for the "you are the room creator, you can kick the start button" affordance — NOT for game-mechanic side mapping.

realtime-party — N-player concurrent (Mario Kart, brawler)

Mix of realtime-duel + turn-party: side mapping by member-index (each player controls their own car/character), no turn gate (everyone plays simultaneously). N can grow to 8.

Full skeleton — covers init, tick, onInput, AND the input-emit side. Movement uses the same held-key dedupe pattern as realtime-duel; each player's input applies to their own avatar via playerId match.

// Layer 3 — gameplay state-machine for realtime-party
window.B3Multiplayer = {
  init({ players, myId, seed }) {
    const palette = ['#fb7185', '#60a5fa', '#34d399', '#facc15', '#a78bfa', '#fb923c']
    const playersById = {}
    players.forEach((p, i) => {
      const startX = 60 + (i % 4) * 100
      const startY = 60 + Math.floor(i / 4) * 100
      playersById[p.id] = { id: p.id, seat: i, name: p.name,
        color: palette[i % palette.length], x: startX, y: startY }
    })
    state = { tick: 0, players: playersById, myId, gameOver: false, finishTick: 30 * 60 }
  },
  tick(dtMs) {
    if (state.gameOver) return
    state.tick++
    const dt = dtMs / 1000
    // Iterate id-sorted (Pattern P8) for deterministic update order.
    for (const id of Object.keys(state.players).sort()) {
      const p = state.players[id]
      const i = intent[id] || {}
      let vx = 0, vy = 0
      if (i.left) vx -= SPEED
      if (i.right) vx += SPEED
      if (i.up) vy -= SPEED
      if (i.down) vy += SPEED
      p.x = clamp(p.x + vx * dt, RADIUS, ARENA.w - RADIUS)
      p.y = clamp(p.y + vy * dt, RADIUS, ARENA.h - RADIUS)
    }
    // Time-based end (deterministic via tick count, NOT Date.now):
    if (state.tick >= state.finishTick && !state.gameOver) {
      state.gameOver = true
      const scores = scoreByCellOwnership(state)  // see Color Splatter
      ctx.gameOver(scores)
    }
  },
  onInput(playerId, input) {
    if (!input || typeof input !== 'object') return
    if (typeof input.dir !== 'string') return
    setIntent(playerId, input.dir, input.phase !== 'up')
    // No turn gate — every player's input applies on every tick.
  },
  getState() { return state ? JSON.parse(JSON.stringify(state)) : null },
  setState(s) {
    state = s ? JSON.parse(JSON.stringify(s)) : null
    for (const k in intent) delete intent[k]
  },
}

// Input emit side (in your render layer / DOM handlers) — held-key dedupe
// keeps the rate under the 60 msg/sec server cap:
const heldKeys = new Set()
document.addEventListener('keydown', (e) => {
  const dir = KEY_MAP[e.key]; if (!dir || heldKeys.has(e.key)) return
  heldKeys.add(e.key)
  window.B3.ctx.emit('input', { dir, phase: 'down' })
})
document.addEventListener('keyup', (e) => {
  const dir = KEY_MAP[e.key]; if (!dir) return
  heldKeys.delete(e.key)
  window.B3.ctx.emit('input', { dir, phase: 'up' })
})

Win condition patterns: tick-count-based timer (above) is most common; also valid is "first to N" (e.g., first player to reach score >= 10) checked at end of tick.

Anti-patterns: (1) gating input on a turn pointer (locks everyone out in FFA); (2) Date.now() for the finish time (drifts across clients — use state.tick); (3) using DOM event order to disambiguate simultaneous events (browsers diverge — sort by playerId on collision).

coop — players cooperate against AI / scenario (drawing, escape room)

Side mapping doesn't apply in the adversarial sense — all human players are on the SAME team. The "opponent" is the game itself (puzzle state, AI, timer, etc.). Use member-index for affordances like "who's drawing now?" or "who answered the prompt last".

Full skeleton — covers concurrent-input handling (2+ players can submit simultaneously) with deterministic ordering, plus a shared timer.

window.B3Multiplayer = {
  init({ players, myId, seed }) {
    const playersById = {}
    players.forEach((p, i) => {
      playersById[p.id] = { id: p.id, name: p.name, seat: i, contribution: 0 }
    })
    // Seed shared puzzle deterministically using ctx.random() (NOT Math.random).
    state = {
      tick: 0, myId, players: playersById,
      pendingSubmits: [],
      timeRemainingTicks: 60 * 30,    // 60 sec at 30 Hz
      sharedScore: 0,
      gameOver: false, won: false,
      // Example shared puzzle: word chain
      chain: [pickStarterWord()],
      used: new Set([state?.chain?.[0]]),
    }
  },
  tick(dtMs) {
    if (state.gameOver) return
    state.tick++
    state.timeRemainingTicks--

    // CR.16 P0.3 — drain queued submits in DETERMINISTIC ORDER.
    // Sort by [serializedInput, playerId] so identical-tick concurrent
    // submits resolve identically on every client.
    state.pendingSubmits.sort((a, b) =>
      a.key.localeCompare(b.key) || a.playerId.localeCompare(b.playerId))
    for (const { playerId, payload } of state.pendingSubmits) {
      tryApplySubmit(state, playerId, payload)
    }
    state.pendingSubmits = []

    if (state.sharedScore >= GOAL && !state.gameOver) {
      state.gameOver = true; state.won = true
      ctx.gameOver(buildLeaderboard(state))
    } else if (state.timeRemainingTicks <= 0 && !state.gameOver) {
      state.gameOver = true; state.won = false
      ctx.gameOver(buildLeaderboard(state))
    }
  },
  onInput(playerId, input) {
    if (state.gameOver) return
    if (!input || typeof input !== 'object') return
    if (input.t !== 'submit') return
    // QUEUE — don't apply directly. tick() drains in deterministic order.
    const payload = String(input.value || '').toLowerCase().trim()
    if (!payload) return
    state.pendingSubmits.push({ playerId, payload, key: payload })
  },
  getState() {
    if (!state) return null
    // Sets aren't JSON-serializable; convert to array.
    const out = JSON.parse(JSON.stringify({ ...state, used: undefined }))
    out.used = Array.from(state.used)
    return out
  },
  setState(s) {
    if (!s) { state = null; return }
    state = JSON.parse(JSON.stringify(s))
    state.used = new Set(s.used || [])
  },
}

Concurrent-submit handling: the contract layer guarantees that inputs from the same tick arrive in the same frame on every client. Buffer them in state.pendingSubmits (which IS part of state, so getState captures it) and sort BEFORE applying in the next tick. This makes the tiebreak explicit and frame-order-independent.

Anti-patterns: (1) gating input on state.turn === mySide — locks everyone out (coop is free-for-all by design); (2) applying submits inline in onInput without sorting — non-deterministic across clients if frame ordering varies; (3) using a Set in state without an array conversion in getState — JSON.stringify drops Sets silently.

spectator-friendly — 1 to N watchers + a shared sim

Special mode for games with a SINGLE "active" player (or AI-driven sim) and N spectators. Set min-players=1 + max-players=high (e.g., 100 for a stream watch-party). Spectators receive frame broadcasts but can't emit input — gate input on connection.getMyRole() === 'host' (only the room creator plays).

init({ players, myId }) {
  const role = connection.getMyRole?.()
  state.canPlay = role === 'host'  // joiners are spectators
  state.myId = myId
}

document.addEventListener('keydown', (e) => {
  if (!state.canPlay) return  // spectators can't act
  B3.ctx.emit('input', { key: e.key })
})

Note: spectator-friendly is the only mode where min-players=1 makes sense. The host enters alone, plays, and shares the link for spectators to join.

turn-team — N-vs-N adversarial team turn-based (team Risk, team Connect Four)

Two side-mapping levels: each player has a TEAM (red vs blue) and a SEAT WITHIN their team (red-1, red-2, blue-1, blue-2). Team is derived from member-index modulo team_count; within-team seat is the floor-divide. Turn order rotates teams first, then within-team seat — like a standard card-game seating order.

Required meta: <meta name="b3-mp-teams" content="2"> in addition to the standard mode/min/max meta tags. Validator (mp-teams-required-for-team-modes) hard-fails without it.

window.B3Multiplayer = {
  init({ players, myId, teamCount }) {  // teamCount comes from start_game
    state.players = players.map((p, i) => ({
      ...p,
      team: i % teamCount,            // 0=red, 1=blue (or 0=red, 1=blue, 2=green for 3 teams)
      teamSeat: Math.floor(i / teamCount),
    }))
    state.me = state.players.find(p => p.id === myId)
    state.currentTurn = 0  // global pointer; rotates through ALL players
    state.teamScore = Array(teamCount).fill(0)
    state.myId = myId
  },
}

Click handler gates on state.players[state.currentTurn].id === state.myId. After your move, currentTurn = (currentTurn + 1) % players.length.

Win condition is per-team: typically you watch state.teamScore[k] for a target, or check team-wide control of objectives. UI should highlight teammates (same color) distinctly from opponents (different color).

Anti-pattern: don't derive team from connection.getMyRole(). Role is host vs joiner, NOT a team assignment. Roles tell you who allocated the room; team membership is index-based and symmetric across all players.

realtime-team — N-vs-N adversarial team realtime (CTF, MOBA, team-deathmatch)

Combination of realtime-party + team derivation: every player controls their own avatar continuously (no turn gate), but team membership defines spawn points, scoring, and friendly-fire rules. Same i % teamCount derivation as turn-team.

init({ players, myId, teamCount }) {
  state.avatars = players.map((p, i) => ({
    id: p.id,
    team: i % teamCount,
    teamSeat: Math.floor(i / teamCount),
    spawn: SPAWN_POINTS[i % teamCount][Math.floor(i / teamCount) % 4],
    pos: { ...SPAWN_POINTS[i % teamCount][0] },
    hp: 100,
  }))
  state.teamScore = Array(teamCount).fill(0)
  state.myId = myId
}

onInput(playerId, input) {
  // No turn gate — every player's input applies on every tick.
  const me = state.avatars.find(a => a.id === playerId)
  if (!me || me.hp <= 0) return
  if (input.t === 'move') me.pos = clamp(me.pos.x + input.dx, me.pos.y + input.dy)
  if (input.t === 'shoot') spawnBullet(state, me, input.dir)  // friendly-fire check uses me.team
  if (input.t === 'capture') tryCapture(state, me)            // increments state.teamScore[me.team]
}

Fire-and-forget data sync for discrete user-initiated actions (shoot, throw, click-to-place, ability-cast): flow through ctx.emit('input', { t: 'shoot', dir, weapon }). The server fans the input out as a frame, every client's onInput deterministically spawns the bullet. Don't try to communicate via postMessage between iframes — there's no out-of-band channel; discrete actions ride the input frame.

BUT: position-derived events (CR.16 P0.3) — pickup, collision, zone-entry — DO NOT emit as input. They resolve inside tick from the players' current positions. Movement is already an input; deriving the collision in tick is deterministic across clients (same positions + id-sorted iteration → same outcome). Emitting a separate { t: 'pickup' } input would race with the position updates from the same tick and produce desyncs.

Decision rule:

• User pressed a button / clicked / typed? → ctx.emit('input', ...). Examples: shoot, throw, place-marker, submit-word.
• It happens because two positions overlap? → resolve in tick from state.players[i].x/y. Examples: pickup-by-walking-over, hit-by-projectile, zone-entry, collision.
• It happens at a fixed time? → check state.tick in tick. Examples: respawn-after-death-timer, item-spawn-every-N-ticks, round-end.

The reference fixture mp-game-template-team demonstrates pattern 2 (coin pickup is a tick-collision, not an emit).

Death + respawn: in deterministic sim, dead-state is just hp <= 0 on the avatar. Reuse the spawn timer in tick(dtMs): when now - me.deathTime > RESPAWN_MS, reset hp + pos. No input needed — purely time-based on the deterministic clock.

Anti-patterns: (1) deriving team from role; (2) using Math.random for spawn jitter (use ctx.random()); (3) sending shoot events faster than your tick rate — the server batches per-tick, and inputs from the same client arrive in order.

Layered structure

URL hints — autoRouteFromUrl IIFE

On iframe load, your game checks the URL for two hints from the platform shell:

;(function autoRouteFromUrl() {
  const url = new URL(location.href)
  const code = url.searchParams.get('room')
  const action = url.searchParams.get('action')

  if (code) {
    // Joiner path: skip Layer 0/1, pre-fill Layer 2 input, submit.
    setMode('lobby')
    showJoinInput(code.trim().toUpperCase())
    submitJoin()
    return
  }

  if (action === 'host') {
    // Host path: skip Layer 0/1, run host flow directly.
    setMode('lobby')
    beginHost()
  }
})()

?room= wins precedence over ?action=host (joiner takes precedence; if a room exists, don't allocate a new one).

Anti-patterns (DO NOT do these)

• Don't use prompt()/alert()/confirm(). The platform iframe sandbox is allow-scripts allow-same-origin allow-pointer-lock — modals are silently blocked. Click a button using prompt() → nothing happens → user stuck. Use an in-frame <input> field instead.
• Don't mint or allocate at the platform shell layer. The shell navigates to ?action=host as intent only; your iframe owns ALL identity. Mint guest, allocate room, connect — all inside the iframe, all in ONE identity. Cross-context minting (shell + iframe both minting) produces two-identity bugs (both browser tabs end up tagged "joiner" because neither matches the recorded host).
• Don't pass tokens via URL. URL ?token= leaks to browser history + server logs and creates the dual-identity hazard above. Iframe mints its own token; that's the only token in the room's lifecycle.
• Don't gate predicates on hardcoded "GOLD"/"SILVER" (or any specific side). Use B3MP.pickByRole(connection.getMyRole(), {host: SIDE_A, joiner: SIDE_B}) with an index fallback. Solo→MP migration left footguns like function playerCanAct() { return state.turn === GOLD } that silently lock out Silver players.

Connection methods (CR.11) — what every host/joiner can call

Quick reference for the Connection object returned by B3MP.connect(). Cycle-7 fresh-agent feedback: agents miss methods buried in prose tables, so this section lists every method explicitly. If a method isn't here, it isn't on Connection.

That's the entire surface. No sendInput (use ctx.emit('input', value) from Layer 3). No leave alias (use close()). No disconnect. If the contract didn't list it above, the SDK doesn't have it.

Connection events (10 total) — payloads from /mp-client.js

The Connection object returned by B3MP.connect() emits 10 events. Wire whichever your UX needs. The lobby connection STAYS OPEN during gameplay — disconnect events on it are still fired in Layer 3, even though gameplay state transports via the platform's separate postMessage channel.

The lobby connection stays open during gameplay. Don't close it on transition to Layer 3 — gameplay's input transport is separate (parent ↔ iframe postMessage), but member-join/leave events keep firing on the lobby connection. Close it when the user navigates away.

Pattern A — B3Multiplayer.onPlayerLeave (recommended, CR.17 O.1)

// In Layer 3 init — add as a 6th function next to the required 5:
window.B3Multiplayer = {
  init({ seed, players, myId }) { /* ... */ },
  tick(dtMs)                    { /* ... */ },
  onInput(playerId, input)      { /* ... */ },
  getState()                    { /* ... */ },
  setState(s)                   { /* ... */ },

  // Optional 6th — called when ANOTHER player's WS closes.
  // Self-leave is NOT dispatched (your iframe is closing).
  onPlayerLeave(playerId) {
    // Set a flag; resolve in next tick. Don't call ctx.gameOver here
    // (callback runs outside tick — racing with in-flight ticks).
    state.leftIds = state.leftIds || []
    if (!state.leftIds.includes(playerId)) state.leftIds.push(playerId)
  },
}

Backward-compat: the validator does NOT require onPlayerLeave. Games that don't define it remain valid — the runtime checks typeof before dispatching.

Pattern B — lobbyConnection.on('member_left', ...) (CR.16, also fine)

The original CR.16 pattern: install one listener in lobby setup that mutates a closure-held flag; gameplay reads it inside tick. All canonical fixtures use this approach.

// In Layer 2, right after connection opens:
const leftIds = new Set()  // gameplay can read this on every tick

lobbyConnection.on('member_left', ({ wsId }) => {
  leftIds.add(wsId)
  // Optional: also update Layer 3 HUD for "Opponent disconnected" surface.
})

// In Layer 3 init:
window.B3Multiplayer = {
  init({ players, myId }) {
    state.players = players.map(p => ({ ...p, alive: true }))
    state.myId = myId
  },
  tick(dtMs) {
    if (state.gameOver) return
    state.tick++
    // CR.16 P0.1 — read leftIds at top of tick, mutate state deterministically.
    for (const p of state.players) {
      if (!p.alive) continue
      if (leftIds.has(p.id)) p.alive = false
    }
    handleLeavesPerMode(state)  // ← mode-specific, see table below
  },
}

Sending: connection.sendChat(msg)

// In Layer 2 lobby setup (or anywhere after connection opens):
const ok = connection.sendChat('hello world')  // returns false if empty/too long/socket closed

// Server validates server-side too:
//   - length 1..200 chars (after trim)
//   - profanity filter (same banlist as guest names)
//   - sub-bucket rate limit: 2 msgs / sec / socket
// Validation failures arrive as 'server_error' events with codes
// 'rate_limit', 'chat_invalid', or 'chat_profane' — show a toast,
// don't disconnect the user.

Receiving: connection.on('chat', ...)

connection.on('chat', ({ wsId, name, msg, ts }) => {
  // wsId   — sender's wsId (matches a member.id in the roster)
  // name   — denormalised from the server's member roster — render directly
  // msg    — server-validated, ≤200 chars, profanity-screened, trimmed
  // ts     — server-stamped Date.now() — for ordering only, NOT deterministic

  // Append to your chat panel UI. Sender sees their OWN message via
  // this same event (server broadcastAlls including sender), so don't
  // local-echo before sendChat returns — you'll get duplicates.
  appendChatLine({ wsId, name, msg, ts })

  // Errors land on 'server_error' with code 'chat_invalid' /
  // 'chat_profane' / 'rate_limit' — handle separately:
})

connection.on('server_error', ({ code }) => {
  if (code === 'chat_profane') showToast('Try different words')
  else if (code === 'chat_invalid') showToast('Message too long or empty')
  else if (code === 'rate_limit') showToast('Slow down a bit')
})

Anti-patterns

• Don't put chat in state. Chat is shell-scope. Including it in getState would taint the desync hash on every message — every chat would look like a multiplayer divergence.
• Don't local-echo before send returns. The server broadcasts your own message back to you for consistency. Local-echoing produces duplicates.
• Don't trust the client's length / profanity filter alone. The server validates and is the source of truth. Client-side checks are immediate UX feedback, not security.
• Don't share the input rate-limit bucket. They're separate by design. Don't try to "save credits" by routing chat through ctx.emit('input', ...) — chat is not gameplay input, and conflating them defeats both the chat spam-protection and gameplay smoothness.

Positional (mp-moving-rect, racing, top-down)

// Positional (avatars on a 2D plane — moving-rect, racing, top-down shooter).
// State carries {x, y, vx, vy} per player. Inputs are direction toggles.
state = {
  tick: 0,
  players: { 'A': { x: 100, y: 100, vx: 0, vy: 0 }, /* ... */ },
}

tick(dtMs) {
  state.tick++
  const dt = dtMs / 1000
  for (const id in state.players) {
    const p = state.players[id]
    const i = intent[id] || {}
    p.vx = ((p.vx + (i.right ? 200 : 0) - (i.left ? 200 : 0)) * 0.9)
    p.vy = ((p.vy + (i.down ? 200 : 0) - (i.up ? 200 : 0)) * 0.9)
    p.x += p.vx * dt; p.y += p.vy * dt
  }
}

Turn-based (cards, dice, prompts)

// Turn-based (cards, dice, prompts). State advances only when ALL players
// have submitted this round's intent. tick is mostly idle (advances clock).
state = {
  tick: 0, round: 0, currentPlayer: 'A',
  hands: { 'A': [...], 'B': [...] },
  pendingPlays: {},   // playerId -> chosen card
}

tick(_dtMs) {
  state.tick++
  // Only advance the round when everyone has played:
  const allPlayed = Object.keys(state.hands).every(id => state.pendingPlays[id])
  if (allPlayed) {
    resolveRound(state)        // pure function — no side effects, no time
    state.pendingPlays = {}
    state.round++
  }
}

onInput(playerId, input) {
  if (input.t === 'playCard' && state.hands[playerId].includes(input.card)) {
    state.pendingPlays[playerId] = input.card
  }
}

Score-only (clickers, mash, quiz)

// Score-only (incremental clicker, button-mash, knowledge quiz scoreboard).
// No spatial state. tick is essentially a no-op or just advances tick counter.
state = {
  tick: 0,
  scores: { 'A': 0, 'B': 0 },
  taps:   { 'A': 0, 'B': 0 },   // local tap counters
}

tick(dtMs) {
  state.tick++
  // Drain accumulated taps into scores once per tick (cheap & deterministic).
  for (const id in state.taps) {
    state.scores[id] += state.taps[id]
    state.taps[id] = 0
  }
}

onInput(playerId, input) {
  if (input.t === 'tap') state.taps[playerId] = (state.taps[playerId] || 0) + 1
}

Player colors — id-hash to a small palette

players[] has no color field by design. Hash player.id to one of N palette slots; same outputs on every client because the algorithm is deterministic.

// Pattern P1: deterministic id → color hashing.
// players[] has no `color` field, so every game does this. Simplest form:
function colorForId(id) {
  const palette = ['#2dd4bf', '#facc15', '#fb7185', '#a78bfa', '#60a5fa', '#34d399']
  let h = 0
  for (let i = 0; i < id.length; i++) h = (h + id.charCodeAt(i)) | 0
  return palette[Math.abs(h) % palette.length]
}

Iteration order in tick — sort by id

JavaScript object insertion order is consistent on a single machine but can DIFFER across clients in race conditions (e.g., two players join at the same instant on different machines). For tick determinism, always iterate by sorted id.

// Pattern P8: iterate players by id-sorted order, NOT insertion order.
// JS object insertion order can DIFFER across clients (e.g., when two
// players join at the same instant on different machines). Sorted iteration
// is the only path that keeps tick deterministic.
tick(dtMs) {
  const ids = Object.keys(state.players).sort()  // ← critical
  for (const id of ids) {
    /* apply intent[id], advance state.players[id], etc. */
  }
}

Simultaneous-event tiebreaker

When two players cross a threshold on the same tick (e.g., both finish a race in tick 1234), iterate by sorted id and take the first hit. Same idea as above — sorted iteration order is the determinism rule for ALL multi-player resolution.

Per-player vs shared world resources

Default to per-player for collectibles (boost pads, power-ups). Shared = the leader stockpiles everything and grief-locks the field; per-player = everyone gets a fair shot. Track via pad.collectedBy[playerId] = true or similar object map.

Cosmetic effects live OUTSIDE state (in localUI)

Particles, screen-shake, hit-sparkles, hover highlights — none of these affect gameplay. Don't put them in state or they'll bloat snapshots and force every client to agree on coordinates that don't matter. Keep them in a module-local localUI object, driven by the render loop. Each client renders its own — same input event triggers similar-but-not-identical visual flair. Tick stays clean.

// localUI lives outside state — never serialized, never synced.
const localUI = { particles: [], shakeFrames: 0 }

// Render loop reads BOTH state (for game-truth) AND localUI (for flair)
function render() {
  drawState(state)
  for (const p of localUI.particles) drawParticle(p)
  if (localUI.shakeFrames > 0) { /* offset camera */ localUI.shakeFrames-- }
  requestAnimationFrame(render)
}

// Tick can SIGNAL render to spawn local flair, but the spawn happens in render
function tick(dtMs) {
  // ... game-truth state changes here
  if (someEvent) state.flashAt = state.tick  // clients see same tick → same render trigger
}

Co-op vs competitive — pick at architecture time

First architectural fork. Decide before you write a single line of multiplayer code.

Co-op is simpler (one state map, one set of game-truth values) and matches Coin Collector / mp-game-template. Competitive needs duplicated state per player and split-screen rendering. Reach for co-op unless competitive is the gameplay's whole point.

Toggle vs explicit-value inputs (idempotency)

When two players hit the "speed up" key at the same instant, you'll receive twoonInput calls before the next tick. A toggle-shaped input ({action:'speed-toggle'}) flips state twice → no-op. An explicit-value input ({action:'speed', value:2}) sets state to 2 twice → still 2. The second form is idempotent under duplicate-receive; use it for any shared toggle.

// ❌ Toggle desyncs under duplicate input
ctx.emit('input', { action: 'speed-toggle' })
// onInput: state.speed = state.speed === 1 ? 2 : 1
// Two players → flips twice → ends back at 1, not 2.

// ✅ Explicit-value is idempotent
ctx.emit('input', { action: 'speed', value: 2 })
// onInput: state.speed = input.value
// Two players → sets to 2 twice → 2. Same for {action:'pause', value:true}.

Spectator detection (myId not in args.players)

v0.1 fixes the player roster at init time. A late-joiner receives a setState snapshot but isn't inargs.players. Detect this in your gameplay code and render a "spectator" badge — otherwise their input emits will be ignored silently and they'll be confused why nothing responds.

init({ seed, players, myId }) {
  state = { /* ... */ }
  // Spectator detection: my id wasn't in the roster at room creation.
  state.amSpectator = !players.some(p => p.id === myId)
}

// In render, show a banner if I'm spectating
if (state.amSpectator) drawBanner('Spectator — joined after game started')

Top-level B3Multiplayer install (not IIFE-scoped)

The platform may call init / tick BEFORE the user clicks "Play Solo" — for example, on a late-join replay. Install window.B3Multiplayer = {...} at module load, NOT inside a Solo-button click handler. Otherwise the platform calls into a missing object and your game freezes.

// ❌ Don't wrap the contract in an IIFE that runs only on Solo click
document.getElementById('btn-solo').onclick = () => {
  (function() {
    window.B3Multiplayer = { init() {/*...*/}, tick() {/*...*/}, /*...*/ }
    runGame()
  })()
}
// Platform calls init BEFORE the user clicks → undefined → frozen.

// ✅ Install at module load; Solo click only switches modes
window.B3Multiplayer = { init() {/*...*/}, tick() {/*...*/}, /*...*/ }
document.getElementById('btn-solo').onclick = () => {
  setMode('playing')   // just toggle visibility; gameplay loop already wired
}