Games — SDK Methods

The games modality lives in its own subpath. Import the Games client plus its publisher/subscription handles from there.

import {
  Games,
  StatePublisher,
  FromPublisher,
  GamesSubscription,
} from "@clutchcall/sdk/games";

from clutchcall.games import (
    Games,
    StatePublisher,
    FromPublisher,
    GamesSubscription,
)

The TypeScript and Python surfaces mirror each other method-for-method. They differ only in idiomatic case (publishState ↔ publish_state) and in keyword vs options style. Both use the same MoQT substrate, so a TS player and a Python authority interoperate on the wire.

`Games` — the client

Use one Games instance per (room, player), or per (room, server) for the authority. The client opens the session lazily on the first publish or subscribe. It reuses the session for every channel.

TypeScript
Python

const games = new Games({
  token:    await fetchRoomToken("duel-42", "alice"),
  roomId:   "duel-42",
  playerId: "alice",          // omit for the authoritative server
  relayHost: "relay.clutchcall.dev",
  onState:  (state, reason) => console.log("conn", state, reason),
});

string

required

Bearer token for the relay session, scoped to (tenant, room, player?).

string

required

The room that every channel binds to. All three channels live under game/<roomId>/….

string

Player identity. Omit it for the authoritative server. It is required for publishInput and publishEvent. It becomes the from header on every frame.

string

Relay hostname. Defaults to the platform relay.

(state, reason?) => void

Connection-state callback. state is a ConnectionState (0 Connecting · 1 Connected · 2 Reconnecting · 3 Closed · 4 Failed).

WebTransportFactory

Inject a custom WebTransport factory (for a Node polyfill or tests). Optional.

games = Games(
    token=await fetch_room_token("duel-42", "alice"),
    room_id="duel-42",
    player_id="alice",          # omit for the authoritative server
    relay_host="relay.clutchcall.dev",
    on_state=lambda state, reason=None: print("conn", state, reason),
)

str

required

Bearer token, scoped to (tenant, room, player?).

str

required

The room every channel binds to.

str

Player identity. Omit it for the server. It is required for publish_input / publish_event.

str

Relay hostname. Defaults to the platform relay.

Callable[[int, Optional[str]], None]

Connection-state callback (same ConnectionState ints as TS).

The constructor throws (Error / GamesError) if token or roomId/room_id is missing.

Namespace accessors

Use these read-only helpers to inspect the raw tracks or to interoperate with them:

games.stateNs;            // "game/duel-42/state"
games.inputNs;           // "game/duel-42/input"
games.eventNs("chat");   // "game/duel-42/event/chat"

games.state_ns           # "game/duel-42/state"
games.input_ns           # "game/duel-42/input"
games.event_ns("chat")   # "game/duel-42/event/chat"

state — server → all

`publishState(args?) → StatePublisher`

Authority-only. Opens the state track and returns a StatePublisher. State frames carry no from header, because the source is always the authority. They use the datagram lane at priority 100.

TypeScript
Python

const state: StatePublisher = await games.publishState({ tickHz: 30 });

number

Tick-rate hint for the relay’s admission control and the recorder. It does not pace your writes. You drive the loop. Optional.

state = games.publish_state(tick_hz=30)   # -> StatePublisher

int

Tick-rate hint. Does not pace your writes. Optional.

`subscribeState(cb) → GamesSubscription`

Player-side. Subscribes to the authority’s state. It calls your callback with each snapshot’s raw bytes. Returns a GamesSubscription that you can close().

const sub = await games.subscribeState((bytes: Uint8Array) => {
  render(deserializeState(bytes));
});

sub = games.subscribe_state(lambda data: render(deserialize_state(data)))

`StatePublisher`

void

Publish one state snapshot. priority defaults to 100. The SDK stamps timestamps from a monotonic clock.

void

Close the state track.

input — each player → server

`publishInput() → FromPublisher`

Player-only. Returns a FromPublisher that prefixes every frame with this client’s playerId. Input uses the datagram lane at priority 100. The call throws if the client has no playerId.

const input: FromPublisher = await games.publishInput();
addEventListener("tick", () => input.write(serializeInput(localInput)));

inp = games.publish_input()   # -> FromPublisher
inp.write(serialize_input(local_input))

`subscribeInputs(cb) → GamesSubscription`

Authority-side. Receives every player’s input on one callback. The SDK decodes the from header, so you get (playerId, bytes) for each frame. You do not manage a subscription for each player.

await games.subscribeInputs((playerId: string, bytes: Uint8Array) => {
  applyInput(playerId, deserializeInput(bytes));
});

games.subscribe_inputs(lambda pid, data: apply_input(pid, deserialize_input(data)))

The SDK silently drops malformed input frames (bad from header). It does not throw into your callback, so one bad packet cannot stall the tick loop. The relay logs the dropped frames as wire-format rejects.

event — any → any (reliable)

`publishEvent(args) → FromPublisher`

Either role. Opens a reliable, ordered event channel and returns a FromPublisher. Events use a subgroup stream at priority 50. Delivery is guaranteed and in order. The SDK stamps the server’s events with from = "_authority". A player’s events carry the player’s id.

TypeScript
Python

const chat: FromPublisher = await games.publishEvent({ channel: "chat" });
chat.write(serialize({ kind: "say", text: "gg" }));

string

required

Event channel name, for example chat, ready, or rpc.use_item. Each channel is its own track under game/<room>/event/<channel>.

chat = games.publish_event(channel="chat")
chat.write(serialize({"kind": "say", "text": "gg"}))

str

required

Event channel name. Each channel is its own track.

`subscribeEvents(args, cb) → GamesSubscription`

Either role. Subscribes to one event channel. The callback gets the decoded sender id and the raw event bytes.

await games.subscribeEvents({ channel: "chat" }, (fromPlayerId, bytes) => {
  appendChat(fromPlayerId, deserialize(bytes));
});

games.subscribe_events(
    channel="chat",
    on_event=lambda pid, data: append_chat(pid, deserialize(data)),
)

`FromPublisher`

Both publishInput and publishEvent return this handle. It prefixes every write with the caller’s from id.

void

Publish one frame. priority defaults to the channel default (100 for input, 50 for events). The SDK adds the from header for you.

void

Close the underlying track.

Handles & lifecycle

`GamesSubscription`

Every subscribe* method returns this handle. It has read-only ns / name plus:

void

Stop receiving on this channel.

`Games.close()`

await games.close();   // closes the shared MoQT session + all tracks

games.close()          # closes the shared session + all tracks

Closes the single underlying session. This closes every publisher and subscription on the session. After close(), the next publish or subscribe opens a fresh session.

Connection events

There is no separate event emitter. The onState / on_state callback that you pass to the constructor delivers the connection lifecycle. The underlying session auto-reconnects with capped backoff. It replays every publish and subscribe on reconnect, so your channels reattach without code on your side.

`ConnectionState`	Meaning
`0` Connecting	dialling the relay
`1` Connected	session up; channels (re)attached
`2` Reconnecting	link dropped; retrying with backoff
`3` Closed	you called `close()`
`4` Failed	unrecoverable (e.g. bad URL or auth)

Wire helpers (advanced)

The SDK exports the from-header codec. Use it for interop tests, or for callers that bypass the high-level client but stay wire-compatible:

import {
  encodeWithFrom,
  decodeWithFrom,
  FROM_HEADER_BYTES,   // 1
  MAX_FROM_LEN,        // 0xff
} from "@clutchcall/sdk/games";

const framed = encodeWithFrom("alice", payload);
const { fromPlayerId, payload: body } = decodeWithFrom(framed);

from clutchcall.games import (
    encode_with_from,
    decode_with_from,
    FROM_HEADER_BYTES,   # 1
    MAX_FROM_LEN,        # 0xff
)

framed = encode_with_from("alice", payload)
decoded = decode_with_from(framed)   # .from_player_id, .payload

Other languages

The Go and Rust SDKs expose the same (room, player) model and the same three channels over the shared MoqtClient. Method names use each language’s idiomatic case. Package coordinates: github.com/clutchcall/clutchcall-sdk/go, clutchcall. Unity games use the Netcode transport drop-in. They do not call this client directly.

​Games — the client

​Namespace accessors

​state — server → all

​publishState(args?) → StatePublisher

​subscribeState(cb) → GamesSubscription

​StatePublisher

​input — each player → server

​publishInput() → FromPublisher

​subscribeInputs(cb) → GamesSubscription

​event — any → any (reliable)

​publishEvent(args) → FromPublisher

​subscribeEvents(args, cb) → GamesSubscription

​FromPublisher

​Handles & lifecycle

​GamesSubscription

​Games.close()

​Connection events

​Wire helpers (advanced)

​Other languages

`Games` — the client

Namespace accessors

state — server → all

`publishState(args?) → StatePublisher`

`subscribeState(cb) → GamesSubscription`

`StatePublisher`

input — each player → server

`publishInput() → FromPublisher`

`subscribeInputs(cb) → GamesSubscription`

event — any → any (reliable)

`publishEvent(args) → FromPublisher`

`subscribeEvents(args, cb) → GamesSubscription`

`FromPublisher`

Handles & lifecycle

`GamesSubscription`

`Games.close()`

Connection events

Wire helpers (advanced)

Other languages