Getting Started

This guide gets one app connected to a running swu-simulator server. The SDK does not start the engine; it speaks to the HTTP and WebSocket API exposed by the server.

Install

pnpm add @my-swu/simulator-client

npm install @my-swu/simulator-client

yarn add @my-swu/simulator-client

Start the simulator

From the simulator repository:

cargo run --bin swu-simulator

The examples assume the server is reachable at http://127.0.0.1:4000. They also use card ids from the simulator card cache; see card ids for the mapping used in snippets.

Create a client

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

export const simulatorClient = createSimulatorClient({
  // This is the HTTP origin of the running simulator server.
  baseUrl: 'http://127.0.0.1:4000',
})

Check connectivity:

const health = await simulatorClient.system.health()
console.log(health.status) // "ok"

Runtime requirements

• Node.js 18+ or any runtime with global fetch.
• A browser-style WebSocket global for live match sockets.
• ESM only. Use "type": "module" or dynamic import() in CommonJS projects.

Node does not provide a browser WebSocket global. Inject one when you need live match sockets:

import WebSocket from 'ws'
import { createSimulatorClient } from '@my-swu/simulator-client'
import type { WebSocketFactory } from '@my-swu/simulator-client'

// Node examples use `ws` to provide the browser-compatible socket shape.
const nodeWebSocketFactory: WebSocketFactory = url => new WebSocket(url)

const simulatorClient = createSimulatorClient({
  baseUrl: 'http://127.0.0.1:4000',
  // Required only for live match sockets in runtimes without global WebSocket.
  webSocketFactory: nodeWebSocketFactory,
})

First match

// Use card ids; these example card ids map to real cards.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
}

const hostAccess = await simulatorClient.matches.create({
  // Seeds make examples deterministic.
  seed: 7,
  format: 'premier',
  hostDeck: premierHostDeck,
})

// The session stores the returned private access and owns socket state.
const matchSession = simulatorClient.session.create(hostAccess)
await matchSession.connect()

matchSession.on('snapshot', matchSnapshot => {
  // Render from snapshots; they are the authoritative game state.
  console.log(matchSnapshot.prompt)
})

// Signal that this seat is ready to leave the lobby.
matchSession.ready()

Read next:

• Client API
• Match Lifecycle
• Driving Gameplay
• Deckbuilding & Formats
• Multiplayer
• Limited Events