Match Session

MatchSession is the high-level live match helper returned by simulatorClient.session.create().

const matchSession = simulatorClient.session.create(hostAccess, {
  handshakeTimeoutMs: 10_000,
})
await matchSession.connect()

For the full match flow, read Match Lifecycle. This page is the class-level quick reference.

State

// These cached values update as matching server frames arrive.
matchSession.connectionState // 'idle' | 'connecting' | 'open' | 'closed'
matchSession.seat            // 'one' | 'two' | 'three' | 'four' | undefined
matchSession.snapshot        // GameState | undefined
matchSession.events          // readonly GameEvent[]
matchSession.errorMessages   // readonly string[]

The state getter returns the same renderable data without exposing seatToken.

Events

const stopSnapshotListener = matchSession.on('snapshot', matchSnapshot => {
  // Snapshot listeners are the main hook for UI state updates.
  render(matchSnapshot)
})

// Call the returned function when the UI no longer needs updates.
stopSnapshotListener()

on() returns the unsubscribe function. Listener callbacks are typed by event name.

Event	Payload
change	MatchSessionState
connectionState	ConnectionState
welcome	WelcomePayload
snapshot	GameState
event	GameEvent
error	ErrorPayload
pong	PongPayload
message	ServerMessage

Lifecycle

const premierHostDeck = {
  leader: 46102,
  base: 308,
  cards: premierMainDeck,
}
const premierGuestDeck = {
  leader: 46107,
  base: 309,
  cards: premierMainDeck,
}

await matchSession.createMatch({ hostDeck: premierHostDeck })
await matchSession.joinMatch(hostAccess, { deck: premierGuestDeck })
await matchSession.connect({ matchId: hostAccess.matchId, seatToken: hostAccess.seatToken })

createMatch() and joinMatch() store the returned private access, seed state from the HTTP snapshot, then connect the socket.

Commands

matchSession.ready()
matchSession.sync()
matchSession.ping('host-latency-1')
matchSession.sendCommand('pass')
matchSession.sendFormatEvent({ type: 'readyNextGame' })

Outbound envelopes are validated before being sent.

Waiting

await matchSession.waitForSnapshot(matchSnapshot => matchSnapshot.phase === 'action', {
  timeoutMs: 15_000,
})

The helper returns the current snapshot immediately when it already matches.

Reconnect

await matchSession.reconnect({ handshakeTimeoutMs: 5_000 })

Reconnect closes the current socket, reopens with the stored match id and seat token, waits for handshake, and requests a fresh snapshot.

Close

matchSession.close()

Close is idempotent and detaches socket listeners.