Cookbook

Task-oriented snippets for the games modality. Each snippet assumes that you imported the client:

import { Games } from "clutchcall_connect/games";

from clutchcall.games import Games

Join a room as a player

Construct with a playerId to take the player role.

const me = new Games({
  relayHost: "relay.firstbyte.fast",
  token:     await fetchRoomToken("duel-42", "alice"),
  roomId:    "duel-42",
  playerId:  "alice",
});

me = Games(
    relay_host="relay.firstbyte.fast",
    token=await fetch_room_token("duel-42", "alice"),
    room_id="duel-42",
    player_id="alice",
)

Run the authoritative server

Omit playerId to take the authority role. The authority publishes state and reads every player’s input.

const auth = new Games({ relayHost, token, roomId: "duel-42" }); // no playerId

auth = Games(token=tok, room_id="duel-42")   # no player_id

Broadcast world state on a tick

Open the state publisher once. Then write a self-contained snapshot on each tick. You drive the clock.

const state = await auth.publishState({ tickHz: 30 });
setInterval(() => state.write(serializeWorld(world)), 1000 / 30);

import asyncio
state = auth.publish_state(tick_hz=30)
async def loop():
    while True:
        state.write(serialize_world(world))
        await asyncio.sleep(1 / 30)

Render incoming state on the client

Subscribe to state. Each callback is one snapshot. Delivery is latest-wins, so do not block on an older snapshot.

await me.subscribeState((bytes) => render(deserializeState(bytes)));

me.subscribe_state(lambda data: render(deserialize_state(data)))

Send player input each tick

publishInput returns a publisher bound to this player’s id. You do not attach your own from.

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

inp = me.publish_input()
inp.write(serialize_input(local_input))

Fan in every player’s input on the server

One callback receives all players. The SDK decodes the from header for you.

await auth.subscribeInputs((playerId, bytes) => {
  applyInput(playerId, deserializeInput(bytes));
});

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

Send a reliable chat event

Events use a reliable, ordered stream. Use them for data that must not be dropped.

const chat = await me.publishEvent({ channel: "chat" });
chat.write(serialize({ text: "gg" }));

chat = me.publish_event(channel="chat")
chat.write(serialize({"text": "gg"}))

Receive events with the sender id

subscribeEvents gives you the decoded sender and the payload.

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

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

Use multiple event channels

Each channel is an isolated reliable track. Use separate channels for chat and for gameplay RPCs.

const chat   = await me.publishEvent({ channel: "chat" });
const rpc    = await me.publishEvent({ channel: "rpc.use_item" });

await me.subscribeEvents({ channel: "chat" },        onChat);
await me.subscribeEvents({ channel: "rpc.use_item" }, onItemRpc);

chat = me.publish_event(channel="chat")
rpc  = me.publish_event(channel="rpc.use_item")

me.subscribe_events(channel="chat",         on_event=on_chat)
me.subscribe_events(channel="rpc.use_item", on_event=on_item_rpc)

Emit a server-authoritative event

The authority can also publish events. The SDK stamps them with from = "_authority", so clients know that the server sent them.

const settle = await auth.publishEvent({ channel: "match.result" });
settle.write(serialize({ winner: "alice", score: [3, 1] }));

settle = auth.publish_event(channel="match.result")
settle.write(serialize({"winner": "alice", "score": [3, 1]}))

Override priority on a write

state and input default to priority 100. Events default to priority 50. Set a higher priority on a critical event to put it above the rest of its lane.

const events = await me.publishEvent({ channel: "chat" });
events.write(serialize(urgentLine), 90);   // higher than default 50

events = me.publish_event(channel="chat")
events.write(serialize(urgent_line), priority=90)

Track connection state

Pass onState to watch the link. The session reconnects and replays your channels automatically. You do not re-subscribe by hand.

const me = new Games({
  relayHost, token, roomId: "duel-42", playerId: "alice",
  onState: (s) => {
    if (s === 1) showOnline();
    if (s === 2) showReconnecting();
  },
});

me = Games(
    token=tok, room_id="duel-42", player_id="alice",
    on_state=lambda s, reason=None: (
        show_online() if s == 1 else show_reconnecting() if s == 2 else None
    ),
)

Stop one channel without leaving the room

Every subscribe* returns a handle. Call close() on the handle to stop one channel. The other channels stay open.

const sub = await me.subscribeEvents({ channel: "chat" }, onChat);
sub.close();   // stop receiving chat; input/state stay live

sub = me.subscribe_events(channel="chat", on_event=on_chat)
sub.close()

Leave the room

close() closes the shared session and every channel on it.

await me.close();

me.close()

Validate a player id before joining

Player ids must encode to 255 UTF-8 bytes or fewer, because the wire header has one length byte. Check untrusted ids on the client.

if (new TextEncoder().encode(playerId).length > 255) {
  throw new Error("player id too long");
}

if len(player_id.encode("utf-8")) > 255:
    raise ValueError("player id too long")

To select a channel: if a newer message will replace a dropped message, use state or input (datagram, latest-wins). If a player will miss a dropped message, use an event (reliable, ordered).

Start here

Console

Guides

Reference

Join a room as a player

Run the authoritative server

Broadcast world state on a tick

Render incoming state on the client

Send player input each tick

Fan in every player’s input on the server

Send a reliable chat event

Receive events with the sender id

Use multiple event channels

Emit a server-authoritative event

Override priority on a write

Track connection state

Stop one channel without leaving the room

Leave the room

Validate a player id before joining

​Join a room as a player

​Run the authoritative server

​Broadcast world state on a tick

​Render incoming state on the client

​Send player input each tick

​Fan in every player’s input on the server

​Send a reliable chat event

​Receive events with the sender id

​Use multiple event channels

​Emit a server-authoritative event

​Override priority on a write

​Track connection state

​Stop one channel without leaving the room

​Leave the room

​Validate a player id before joining

Join a room as a player

Run the authoritative server

Broadcast world state on a tick

Render incoming state on the client

Send player input each tick

Fan in every player’s input on the server

Send a reliable chat event

Receive events with the sender id

Use multiple event channels

Emit a server-authoritative event

Override priority on a write

Track connection state

Stop one channel without leaving the room

Leave the room

Validate a player id before joining