External authoritative multiplayer

Bounty Board provisions one dedicated server side ticket secret per game and environment. Never ship it in a browser bundle or reuse another game's room service credentials. Registered endpoints must use wss: outside loopback development and must not contain userinfo, query parameters, or a fragment.

payloadB64 = base64url(UTF8(JSON(payload)))
signatureB64 = base64url(HMAC-SHA256(payloadB64, ticketSecret))
ticket = payloadB64 + "." + signatureB64

{
  "v": 1,
  "sub": "player:<opaque-game-scoped-value>",
  "name": "Display Name",
  "avatarUrl": null,
  "slug": "your-game-slug",
  "roomId": "ROOM-CODE",
  "guest": false,
  "iat": 1700000000000,
  "exp": 1700000060000
}

Compare the HMAC in constant time, require protocol version 1, reject expired tickets, and match both slug and roomId exactly. iat and exp are Unix milliseconds. Treat sub as an opaque game scoped identity and never try to map it to a Bounty Board account. Guests get tickets too, with guest set to true and their own opaque subject. The display name and avatar are never authorization data, and avatarUrl may be null for any player.

import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';

const room = await joinRoom({
  code: 'ROOM-CODE', // or create: true
  joinData: {
    schemaVersion: 1,
    loadout: 'starter',
    mode: 'friends',
  },
});

room.on('snapshot', ({ state }) => renderAuthoritativeState(state));
room.on('connection', ({ connected }) => setReconnecting(!connected));

if (!room.trySend({ type: 'move', x: 1, y: 0 })) {
  setReconnecting(true);
}

Script tag builds call BBArcade.multiplayer.joinRoom(). Public quick match (match: true) is not available on an external authority: your server owns its capacity, lobby, and any matchmaking, so players join with code or create: true.

wss://multiplayer.example.com/bountyboard?ticket=<encoded>&join=<encoded-json>

The SDK opens your registered endpoint with an encoded ticket and optional encoded join query; join is omitted when no joinData was supplied. joinData is untrusted JSON capped at 1 KiB. Keep the authenticated route separate from anonymous or legacy sockets, and redact request URIs from access logs because the ticket appears in the query string.

{
  "t": "welcome",
  "playerId": "room-scoped-player-id",
  "players": [
    { "id": "room-scoped-player-id", "name": "Display Name", "avatarUrl": null }
  ],
  "state": { "phase": "lobby" }
}

// Server -> client
{ "t": "snapshot", "tick": 42, "state": { "phase": "playing" } }
{ "t": "event", "data": { "type": "round_started", "round": 2 } }
{ "t": "player_leave", "playerId": "p2" }

// Client -> server: input only, never authoritative state
{ "t": "input", "seq": 7, "data": { "type": "move", "x": 1, "y": 0 } }

Send welcome within 10 seconds. The server may also send player_join, player_leave, event, error, and (only for finite games) match_end. Reject bad tickets with unauthenticated and invalid admission data with rejected, then close before welcome.

Rebind the seat from the verified (ticket.sub, ticket.roomId) pair, never from a client supplied player id or reconnect token. Clear held controls while disconnected and return the latest complete viewer safe state in the new welcome. Prediction based clients should receive the last processed input sequence so acknowledged inputs can be discarded.

{
  "t": "match_end",
  "results": [
    {
      "playerId": "p1",
      "name": "Display Name",
      "placement": 1,
      "score": 1200,
      "outcome": "win"
    }
  ]
}

Persistent Bounty Board results, when enabled, use a separately provisioned server to server reporting credential. Never expose that credential to the game or accept client authored standings. Death, respawn, a round transition, or one player leaving does not automatically end a match.