WebSocket Protocol

This page is the raw transport reference. Most apps should use MatchSession instead of writing framing code.

URL

ws://127.0.0.1:4000/ws/match_123?seat_token=seat_token_123

The SDK derives this from the HTTP baseUrl automatically when a match session connects — http becomes ws, https becomes wss. Replace match_123 and seat_token_123 with the access values returned by matches.create() or matches.join().

Outbound messages

Every client frame is a JSON envelope tagged with type. Payload shape depends on the tag.

Ready:

{ "type": "ready" }

Sync request:

{ "type": "syncRequest" }

Ping (nonce is optional):

{ "type": "ping", "payload": { "nonce": "host-latency-1" } }

Command (scalar payload):

{ "type": "command", "payload": "pass" }

Command (tagged payload):

{
  "type": "command",
  "payload": {
    "chooseOpeningResources": {
      "cardIds": [45, 939]
    }
  }
}

Here 45 and 939 are card ids from that seat's private hand. They map to Alliance X-Wing and Battlefield Marine in the example cache.

Inbound messages

Welcome:

{
  "type": "welcome",
  "payload": {
    "matchId": "match_123",
    "seat": "one"
  }
}

Snapshot:

{
  "type": "snapshot",
  "payload": {
    "status": "inProgress",
    "prompt": { "chooseInitiative": { "seat": "one" } }
  }
}

Event:

{
  "type": "event",
  "payload": { "playerReady": { "seat": "one" } }
}

Error:

{
  "type": "error",
  "payload": {
    "code": "invalid_command",
    "message": "command is not valid in the current prompt"
  }
}

Pong:

{
  "type": "pong",
  "payload": { "nonce": "host-latency-1" }
}

The nonce echoes the matching ping nonce (or null if none was sent). Use it to measure round-trip latency.

Validation

The SDK validates every inbound envelope against the server-message schema and every outbound envelope against the client-message schema. Clients that implement their own transport should do the same using the JSON schemas shipped in @my-swu/simulator-client/schema/.