Interface: MatchSession

Defined in: packages/ts-sdk/src/match-session/types.ts:59

Main ergonomic SDK API for interacting with one live match.

A session wraps HTTP match creation/joining, WebSocket connection state, incoming snapshots/events, outgoing commands, and explicit reconnects for one private player seat.

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.ready()

Example

import { createSimulatorClient } from '@my-swu/simulator-client'

const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)
await matchSession.connect()
matchSession.ready()

See

Extends

MatchSessionMethods

Properties

aiStatus

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { aiStatus } = matchSession

console.log(aiStatus)

readonly aiStatus: AiStatusPayload | undefined

Defined in: packages/ts-sdk/src/match-session/types.ts:61

Latest AI attachment/pause status announced by the server.

connectionState

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { connectionState } = matchSession

console.log(connectionState)

readonly connectionState: ConnectionState

Defined in: packages/ts-sdk/src/match-session/types.ts:63

Current transport state.

errorMessages

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { errorMessages } = matchSession

console.log(errorMessages)

readonly errorMessages: readonly string[]

Defined in: packages/ts-sdk/src/match-session/types.ts:71

Human-readable error summaries.

errors

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { errors } = matchSession

console.log(errors)

readonly errors: readonly ErrorPayload[]

Defined in: packages/ts-sdk/src/match-session/types.ts:65

Recent engine or SDK errors.

events

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { events } = matchSession

console.log(events)

readonly events: readonly GameEvent[]

Defined in: packages/ts-sdk/src/match-session/types.ts:67

Recent game events.

history

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { history } = matchSession

console.log(history)

readonly history: readonly MatchHistoryFeedEntry[]

Defined in: packages/ts-sdk/src/match-session/types.ts:69

Recent match history entries supplied by the server.

matchId

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { matchId } = matchSession

console.log(matchId)

readonly matchId: string | undefined

Defined in: packages/ts-sdk/src/match-session/types.ts:73

Public match id when one is known.

reconnectState

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { reconnectState } = matchSession

console.log(reconnectState)

readonly reconnectState: MatchSessionReconnectState

Defined in: packages/ts-sdk/src/match-session/types.ts:75

Automatic reconnect progress after an abnormal socket close.

seat

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { seat: controlledSeat } = matchSession

console.log(controlledSeat)

readonly seat: Seat | undefined

Defined in: packages/ts-sdk/src/match-session/types.ts:81

Seat controlled by this session when known.

snapshot

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { snapshot: matchSnapshot } = matchSession

console.log(matchSnapshot)

readonly snapshot: GameState | undefined

Defined in: packages/ts-sdk/src/match-session/types.ts:79

Latest authoritative private snapshot for this seat.

snapshotRevision

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { snapshotRevision } = matchSession

console.log(snapshotRevision)

readonly snapshotRevision: number

Defined in: packages/ts-sdk/src/match-session/types.ts:77

Monotonic revision of the latest authoritative match snapshot.

state

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { state } = matchSession

console.log(state)

readonly state: MatchSessionState

Defined in: packages/ts-sdk/src/match-session/types.ts:83

Token-free state snapshot.

welcome

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { welcome } = matchSession

console.log(welcome)

readonly welcome: WelcomePayload | undefined

Defined in: packages/ts-sdk/src/match-session/types.ts:85

Latest welcome payload when the socket handshake has completed.

Methods

close()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.close()

close(): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:167

Closes the active socket.

Listeners stay registered, and stored access remains available for reconnect().

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function leaveView(matchSession: MatchSession) {
  matchSession.close()
}

console.log(leaveView)

See

https://simulator-sdk.my-swu.com/guide/match-session#close

Inherited from

MatchSessionMethods.close

connect()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

await matchSession.connect()

connect(access?, options?): Promise<MatchSession>

Defined in: packages/ts-sdk/src/match-session/methods.ts:45

Opens a socket using existing or supplied private access.

Call this after seeding access from matches.create(), matches.join(), matches.spectate(), createMatch(), joinMatch(), or spectateMatch(). Resolves after welcome and snapshot.

Parameters

access?

MatchSessionAccess

options?

MatchSessionConnectOptions

Returns

Promise<MatchSession>

Example

import type { MatchSession } from '@my-swu/simulator-client'

async function resumeMatch(matchSession: MatchSession) {
  await matchSession.connect({
    matchId: 'match_123',
    seatToken: 'seat_token_123',
  })
}

console.log(resumeMatch)

See

https://simulator-sdk.my-swu.com/guide/match-session#lifecycle

Inherited from

MatchSessionMethods.connect

createMatch()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

const createdHostAccess = await matchSession.createMatch({
  format: 'premier',
  // Twin Suns supports 2-4 players; every other format is exactly 2.
  playerCount: 2,
  hostName: 'Host',
  hostAuthenticated: false,
  historyIdentities: [],
  // One entry per AI-controlled seat; empty means a human opponent joins.
  aiOpponents: [],
  hostDeck: premierHostDeck,
})

createMatch(request, options?): Promise<MatchAccessResponse>

Defined in: packages/ts-sdk/src/match-session/methods.ts:81

Creates a host match, stores private access, and connects.

Use this when one UI action should create a match and start live state.

Parameters

Example

import type { MatchSession } from '@my-swu/simulator-client'

const premierHostDeck = {
  leader: 46102,
  leaders: [],
  base: 308,
  cards: Array.from({ length: 50 }, () => 45),
  sideboard: [],
}

async function hostPremier(matchSession: MatchSession) {
  return matchSession.createMatch({
    format: 'premier',
    playerCount: 2,
    hostDeck: premierHostDeck,
    hostName: 'Host',
    hostAuthenticated: false,
    historyIdentities: [],
    aiOpponents: [],
  })
}

console.log(hostPremier)

See

https://simulator-sdk.my-swu.com/guide/match-lifecycle#create

Inherited from

MatchSessionMethods.createMatch

joinMatch()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

const guestAccess = await matchSession.joinMatch({ matchId: 'match_123' }, {
  deck: premierGuestDeck,
  name: 'Guest',
  authenticated: false,
  historyIdentities: [],
})

joinMatch(match, request, options?): Promise<MatchAccessResponse>

Defined in: packages/ts-sdk/src/match-session/methods.ts:114

Joins a match, stores private access, and connects.

Use this for guest tabs or players entering through a shared match id.

Parameters

match

string | MatchReference

request

JoinMatchRequest

options?

MatchSessionConnectOptions

Returns

Promise<MatchAccessResponse>

Example

import type { MatchSession } from '@my-swu/simulator-client'

const premierGuestDeck = {
  leader: 46107,
  leaders: [],
  base: 309,
  cards: Array.from({ length: 50 }, () => 35),
  sideboard: [],
}

async function joinPremier(matchSession: MatchSession) {
  return matchSession.joinMatch('match_123', {
    deck: premierGuestDeck,
    name: 'Guest',
    authenticated: false,
    historyIdentities: [],
  })
}

console.log(joinPremier)

See

https://simulator-sdk.my-swu.com/guide/match-lifecycle#join

Inherited from

MatchSessionMethods.joinMatch

on()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

const stopListening = matchSession.on('snapshot', matchSnapshot => {
  // Snapshots are the authoritative state for UI rendering.
  console.log(matchSnapshot.phase)
})
stopListening()

on<TKey>(event, listener): () => void

Defined in: packages/ts-sdk/src/match-session/methods.ts:457

Registers one typed event listener and returns an unsubscribe function.

Event listeners stay registered across reconnects. Unsubscribe on unmount.

Type Parameters

TKey

TKey extends keyof MatchSessionEvents

Parameters

event

TKey

listener

(value) => void

Returns

() => void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function watchState(matchSession: MatchSession) {
  return matchSession.on('snapshot', actionSnapshot => {
    console.log(actionSnapshot.phase)
  })
}

console.log(watchState)

See

https://simulator-sdk.my-swu.com/guide/match-session#events

Inherited from

MatchSessionMethods.on

ping()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.ping('host-latency-1')

ping(nonce?): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:328

Sends one ping frame with an optional nonce echoed by pong.

Use the nonce to match a pong to one latency measurement.

Parameters

nonce?

string | null

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function measureLatency(matchSession: MatchSession) {
  matchSession.ping('latency-check-1')
}

console.log(measureLatency)

See

https://simulator-sdk.my-swu.com/guide/websocket#ping

Inherited from

MatchSessionMethods.ping

ready()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.ready()

ready(): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:216

Sends one ready message for the current seat.

Use this in lobby and setup phases when a seat must acknowledge readiness.

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function markSeatReady(matchSession: MatchSession) {
  matchSession.ready()
}

console.log(markSeatReady)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay#ready-and-setup

Inherited from

MatchSessionMethods.ready

reconnect()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

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

reconnect(options?): Promise<MatchSession>

Defined in: packages/ts-sdk/src/match-session/methods.ts:187

Reopens the socket using the stored private access.

Closes the old socket, opens a new one, waits for handshake, then syncs.

Parameters

options?

MatchSessionConnectOptions

Returns

Promise<MatchSession>

Example

import type { MatchSession } from '@my-swu/simulator-client'

async function restoreSocket(matchSession: MatchSession) {
  await matchSession.reconnect({ handshakeTimeoutMs: 10_000 })
}

console.log(restoreSocket)

See

https://simulator-sdk.my-swu.com/guide/reconnect

Inherited from

MatchSessionMethods.reconnect

recoverNow()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { recoverNow } = matchSession

console.log(recoverNow)

recoverNow(): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:196

Immediately starts session-owned automatic recovery using stored access.

This is intended for foreground restoration: it preserves automatic backoff after a failed dial instead of turning recovery into a one-shot manual reconnect.

Returns

void

Inherited from

MatchSessionMethods.recoverNow

respondUndo()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { respondUndo } = matchSession

console.log(respondUndo)

respondUndo(approve): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:266

Answers the pending undo approval request.

Approving as the last outstanding seat applies the undo; declining cancels it (undoDeclined). A response sent by the original requester withdraws the request regardless of approve (undoCancelled).

Parameters

approve

boolean

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function approvePendingUndo(matchSession: MatchSession) {
  matchSession.respondUndo(true)
}

console.log(approvePendingUndo)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay

Inherited from

MatchSessionMethods.respondUndo

sendAiFormatEvent()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { sendAiFormatEvent } = matchSession

console.log(sendAiFormatEvent)

sendAiFormatEvent(command): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:389

Sends one host-authorized AI Trilogy format command.

Use this only for manual Player vs AI Trilogy ban/pick flows. The server applies accepted commands to the AI seat after validating the sender.

Parameters

command

FormatEventCommand

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function chooseAiBan(matchSession: MatchSession) {
  matchSession.sendAiFormatEvent({ type: 'banTrilogyDeck', deckIndex: 1 })
}

console.log(chooseAiBan)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay#out-of-game-commands

Inherited from

MatchSessionMethods.sendAiFormatEvent

sendChat()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { sendChat } = matchSession

console.log(sendChat)

sendChat(message): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:410

Sends one in-match chat message.

The server trims and caps the message, then broadcasts it as a match history entry to connected seats.

Parameters

message

string

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function chat(matchSession: MatchSession) {
  matchSession.sendChat('ready?')
}

console.log(chat)

See

https://simulator-sdk.my-swu.com/guide/websocket

Inherited from

MatchSessionMethods.sendChat

sendCommand()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.sendCommand('pass')

sendCommand(command): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:348

Sends one typed gameplay command for the current prompt.

Invalid command shapes fail SDK validation before a socket frame is sent.

Parameters

command

GameCommand

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function passAction(matchSession: MatchSession) {
  matchSession.sendCommand('pass')
}

console.log(passAction)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay

Inherited from

MatchSessionMethods.sendCommand

sendFormatEvent()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.sendFormatEvent({ type: 'readyNextGame' })

sendFormatEvent(command): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:368

Sends one typed out-of-game format command for series flows.

Use for match-series actions such as readying for the next game.

Parameters

command

FormatEventCommand

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function readyForSeriesGame(matchSession: MatchSession) {
  matchSession.sendFormatEvent({ type: 'readyNextGame' })
}

console.log(readyForSeriesGame)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay#out-of-game-commands

Inherited from

MatchSessionMethods.sendFormatEvent

sendInteractionCue()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { sendInteractionCue } = matchSession

console.log(sendInteractionCue)

sendInteractionCue(cue): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:435

Sends one transient hand-card interaction cue.

Use this for live hover/drag presentation. The server broadcasts it to connected viewers without changing authoritative gameplay state.

Parameters

cue

CardInteractionCueRequest

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function showRemoteHover(matchSession: MatchSession) {
  matchSession.sendInteractionCue({
    kind: 'handCard',
    index: 0,
    state: 'hover',
  })
}

console.log(showRemoteHover)

See

https://simulator-sdk.my-swu.com/guide/websocket

Inherited from

MatchSessionMethods.sendInteractionCue

setAiPaused()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.setAiPaused(true)

setAiPaused(paused): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:288

Pauses or resumes an attached AI opponent.

This is session-level manual control only; it does not mutate gameplay state. Undo-created AI pauses resume automatically after the next successful human mutation.

Parameters

paused

boolean

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function resumeAi(matchSession: MatchSession) {
  matchSession.setAiPaused(false)
}

console.log(resumeAi)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay

Inherited from

MatchSessionMethods.setAiPaused

spectateMatch()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Keep seatToken private; it authenticates this seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }
const matchSession = simulatorClient.session.create(hostAccess)

const { spectateMatch } = matchSession

console.log(spectateMatch)

spectateMatch(match, request, options?): Promise<MatchSpectatorAccessResponse>

Defined in: packages/ts-sdk/src/match-session/methods.ts:142

Spectates a match, stores private read-only access, and connects.

Use this for viewers entering through a shared match id without taking a player seat.

Parameters

match

string | MatchReference

request

SpectateMatchRequest

options?

MatchSessionConnectOptions

Returns

Promise<MatchSpectatorAccessResponse>

Example

import type { MatchSession } from '@my-swu/simulator-client'

async function spectatePremier(matchSession: MatchSession) {
  return matchSession.spectateMatch('match_123', {
    name: 'Spectator',
    authenticated: false,
  })
}

console.log(spectatePremier)

See

https://simulator-sdk.my-swu.com/guide/match-lifecycle#spectate

Inherited from

MatchSessionMethods.spectateMatch

sync()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.sync()

sync(): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:308

Sends one request for the latest server snapshot.

Use after reconnects, tab restores, or missed UI updates.

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function requestFreshState(matchSession: MatchSession) {
  matchSession.sync()
}

console.log(requestFreshState)

See

https://simulator-sdk.my-swu.com/guide/websocket#sync-request

Inherited from

MatchSessionMethods.sync

undo()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

matchSession.undo()

undo(): void

Defined in: packages/ts-sdk/src/match-session/methods.ts:244

Requests rollback of the latest accepted player action.

Any valid seat token may send undo. When the undo needs no approval, the server restores the previous snapshot and emits one or more undoApplied events. In matches with other human seats, a sensitive undo (hidden information was revealed, or another player acted since) is recorded on GameState.pendingUndo with an undoRequested event instead, and only applies once every other human seat approves via respondUndo. In AI matches, one human undo also consumes any AI responses that happened after that human action, pauses the AI, then automatically resumes it after the next successful human mutation.

Returns

void

Example

import type { MatchSession } from '@my-swu/simulator-client'

function undoLastAction(matchSession: MatchSession) {
  matchSession.undo()
}

console.log(undoLastAction)

See

https://simulator-sdk.my-swu.com/guide/driving-gameplay

Inherited from

MatchSessionMethods.undo

waitForSnapshot()

Example:

import { createSimulatorClient } from '@my-swu/simulator-client'

// Point this at the simulator HTTP origin for /health and /api routes.
const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
})

// Use card ids; the server validates deck legality.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  leaders: [], // Twin Suns only; Premier uses the single `leader` above.
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
  sideboard: [],
}

// Seat two submits a separate legal deck when joining the match.
const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  leaders: [],
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
  sideboard: [],
}

// Keep seatToken private; it authenticates one player seat.
const hostAccess = { matchId: 'match_123', seatToken: 'seat_token_123' }

const matchSession = simulatorClient.session.create(hostAccess)

await matchSession.connect()

const actionSnapshot = await matchSession.waitForSnapshot(
  matchSnapshot => matchSnapshot.phase === 'action',
)

waitForSnapshot(predicate?, options?): Promise<GameState>

Defined in: packages/ts-sdk/src/match-session/methods.ts:483

Resolves with the current or next matching snapshot.

Checks current state first, then waits for future snapshots until timeout.

Parameters

predicate?

MatchSessionSnapshotPredicate

options?

MatchSessionWaitOptions

Returns

Promise<GameState>

Example

import type { MatchSession } from '@my-swu/simulator-client'

async function waitForAction(matchSession: MatchSession) {
  return matchSession.waitForSnapshot(
    matchSnapshot => matchSnapshot.phase === 'action',
    { timeoutMs: 5_000 },
  )
}

console.log(waitForAction)

See

https://simulator-sdk.my-swu.com/guide/match-session#waiting

Inherited from

MatchSessionMethods.waitForSnapshot

Interface: MatchSession ​

Example ​

See ​

Extends ​

Properties ​

aiStatus ​

connectionState ​

errorMessages ​

errors ​

events ​

history ​

matchId ​

reconnectState ​

seat ​

snapshot ​

snapshotRevision ​

state ​

welcome ​

Methods ​

close() ​

Returns ​

Example ​

See ​

Inherited from ​

connect() ​

Parameters ​

access? ​

options? ​

Returns ​

Example ​

See ​

Inherited from ​

createMatch() ​

Parameters ​

request ​

options? ​

Returns ​

Example ​

See ​

Inherited from ​

joinMatch() ​

Parameters ​

match ​

request ​

options? ​

Returns ​

Example ​

See ​

Inherited from ​

on() ​

Type Parameters ​

TKey ​

Parameters ​

event ​

listener ​

Returns ​

Example ​

See ​

Inherited from ​

ping() ​

Parameters ​

nonce? ​

Returns ​

Example ​

See ​

Inherited from ​

ready() ​

Returns ​

Example ​

See ​

Inherited from ​

reconnect() ​

Parameters ​

options? ​

Returns ​

Example ​

See ​

Inherited from ​

recoverNow() ​

Returns ​

Interface: MatchSession

Example

See

Extends

Properties

aiStatus

connectionState

errorMessages

errors

events

history

matchId

reconnectState

seat

snapshot

snapshotRevision

state

welcome

Methods

close()

Returns

Example

See

Inherited from

connect()

Parameters

access?

options?

Returns

Example

See

Inherited from

createMatch()

Parameters

request

options?

Returns

Example

See

Inherited from

joinMatch()

Parameters

match

request

options?

Returns

Example

See

Inherited from

on()

Type Parameters

TKey

Parameters

event

listener

Returns

Example

See

Inherited from

ping()

Parameters

nonce?

Returns

Example

See

Inherited from

ready()

Returns

Example

See

Inherited from

reconnect()

Parameters

options?

Returns

Example

See

Inherited from

recoverNow()

Returns