# Getting started From an empty repository to a game running on a `q` channel. Each step hands the next one a concrete string, and nothing here is assumed. ```mermaid flowchart LR S1["1. a channel
ids, a credential, two prefixes"] --> S2["2. install"] S2 --> S3["3. game.ts
your rules and your message type"] S3 --> S4["4. handler.ts
the actor and its transport"] S4 --> S5["5. deploy
reservedConcurrency set"] S5 --> S6["6. a client
a gameId plus the channel JWT"] ``` If you would rather read code first, run [`examples/actor-game`](../examples/actor-game/README.md) — steps 3 and 4, complete and runnable, with nothing to install and nothing to deploy. ## 1. Get a channel and its credential A **channel** is what the platform provisions for your game: an id, an endpoint, and a credential scoped to it. A **`q` channel** is the kind whose gateway understands nothing and simply bridges frames to your actor — see [The platform § The two channel kinds](platform.md#the-two-channel-kinds). Someone provisions it once, in the yyt console or with the `yyt` CLI; `cli/README.md` in the [`service`](https://github.com/yingyeothon/service) repository is that recipe. If you have no console access, this is the step to ask someone for — everything below needs its output. | What you copy | Looks like | Used for | | ------------------------------- | ------------------------------- | ----------------------------------------------- | | the `q` channel id | `q_0123456789abcdef` | the client's `channelId` | | its `wsUrl` | `wss://gw.yyt.life/?channel=…` | the client's `url` — **origin only**, see below | | a Redis credential | host, user, password | your actor's own connection | | the **inbound** key prefix | `game:::` | the actor's event, queue, lock and awaiter keys | | the **outbound** channel prefix | `game:out:::` | the pub/sub channel the gateway subscribes to | `` here is the deployment stage the channel was issued for (`dev`, `prod`) and is part of the ACL pattern. It is unrelated to the game loop's `stage`, which is a different word this guide also uses. **Copy the prefixes as one block; never retype them.** A prefix typed by hand usually stays inside the credential's ACL pattern, so it does not fail at all — it writes to a key nobody drains. See [Operations § Key prefixes and the Redis ACL](operations.md#key-prefixes-and-the-redis-acl). Nothing in tslib reads those two strings from the environment; they are plain options. `REDIS_KEY_PREFIX` and `REDIS_OUT_PREFIX` below are names this page chose, and you set them wherever you set the rest of your function's environment. `gamebaseOptionsFromEnv()` does read a fixed set — see [Operations § Configuration is injected, never read](operations.md#configuration-is-injected-never-read). ## 2. Install ```bash npm install @yingyeothon/lambda-gamebase @yingyeothon/gamebase-all-together npm install @aws-sdk/client-apigatewaymanagementapi @aws-sdk/client-lambda ``` The two AWS SDK clients are peer dependencies. Node >= 20; every package ships dual ESM and CJS. ## 3. Write the rules, and the message type Keep this file free of the framework — no imports, no IO, no clock. It is the half you own, and the half that stays unit-testable. ```ts // game.ts export interface Raid { bossHp: number; damage: Record; } /** Your own messages, plus the two the framework synthesises. */ export type Message = | { type: "attack"; connectionId: string; power?: number } | { type: "enter" | "leave"; connectionId: string; memberId: string }; export const createRaid = (hp: number): Raid => ({ bossHp: hp, damage: {} }); export function applyHit(raid: Raid, memberId: string, power = 1): number { const dealt = Math.min(Math.max(Math.floor(power), 1), 10); // clients lie raid.bossHp = Math.max(0, raid.bossHp - dealt); raid.damage[memberId] = (raid.damage[memberId] ?? 0) + dealt; return dealt; } export const isCleared = (raid: Raid) => raid.bossHp <= 0; ``` **`enter` and `leave` are reserved.** The actor decides which member a connection speaks for from them, so a client may never send one; `handleMessages` refuses them with a `400`. ## 4. Wire the actor Two things here are easy to get wrong, so they are called out in the code: the **type argument** (without it `message.power` does not exist), and the **transport** (a `q` channel's gateway listens on Redis pub/sub, not on API Gateway). ```ts // handler.ts import { runGameAllTogether } from "@yingyeothon/gamebase-all-together"; import { broadcast, createGamebaseContext, createRedisPubSubTransport, gamebaseOptionsFromEnv, handleActor, reply, type GameActorStartEvent, } from "@yingyeothon/lambda-gamebase"; import { applyHit, createRaid, isCleared, type Message } from "./game.js"; // One per container: it owns the shared Redis connection. const context = createGamebaseContext(gamebaseOptionsFromEnv()); const prefix = process.env.REDIS_KEY_PREFIX!; // the inbound block from step 1 const outPrefix = process.env.REDIS_OUT_PREFIX!; // the outbound one export async function actor(event: GameActorStartEvent) { const raid = createRaid(100); // A q channel's gateway subscribes to Redis; it is not behind API Gateway. // Passing `{ context }` instead would post frames to WS_ENDPOINT, which // nothing is listening to — and it would fail silently. const transport = createRedisPubSubTransport({ connection: context.getRedisConnection(), channelPrefix: outPrefix, gameId: event.gameId, }); await handleActor({ event, context, eventKeyPrefix: `${prefix}event:`, awaiterKeyPrefix: `${prefix}awaiter:`, queueKeyPrefix: `${prefix}queue:`, lockKeyPrefix: `${prefix}lock:`, lifetimeSeconds: 300, gameMain: (options) => runGameAllTogether({ ...options, network: { transport }, gameWaitingSeconds: 20, gameRunningSeconds: 120, pollIntervalMillis: 100, tick: { mode: "perMessage" }, // Published exactly once, and pub/sub has no redelivery. endRepeatCount: 2, isGameOver: () => isCleared(raid), processMessage: async ({ context: game, message }) => { if (message.type !== "attack") return; const user = game.connectedUsers[message.connectionId]; if (!user) return; const dealt = applyHit(raid, user.memberId, message.power); await broadcast( Object.keys(game.connectedUsers), { type: "hit", payload: { memberId: user.memberId, dealt } }, { transport }, ); }, // Fires on a reconnect too, so it is the resynchronisation point. onMemberEntered: ({ connectionId }) => reply( connectionId, { type: "snapshot", payload: raid }, { transport }, ), onGameEnd: ({ context: game, reason }) => broadcast( Object.keys(game.connectedUsers), { type: "result", payload: { reason, damage: raid.damage } }, { transport }, ), }), }); } ``` ### What allocates a run Nobody can join a game that does not exist yet, and **the platform does not create one for you**. Something of yours — an HTTP endpoint, usually called the _entry API_ — decides a run exists, writes its start event, and invokes this function: ```ts import { saveActorStartEvent, type GameActorStartEvent, } from "@yingyeothon/lambda-gamebase"; const event: GameActorStartEvent = { gameId: crypto.randomUUID(), // yours to allocate; a retry needs a NEW one members: [{ memberId: "u1", name: "Ari", email: "ari@example.test" }], callbackUrl, // optional: readyCall PUTs here once the lock is taken }; await saveActorStartEvent({ event, set, eventKeyPrefix: `${prefix}event:` }); // then invoke the actor function with `event` as its payload ``` The gateway reads that start event to decide who may connect, so **a member not listed in it is refused**. `RPUSH` is not a trigger — the invoke is explicit. See [The game actor § The three Redis keys](game-actor.md#the-three-redis-keys). `sample-dungeon` in the [`examples`](https://github.com/yingyeothon/examples) repository is a complete worked version of this half, including its deployment. ## 5. Deploy, with the ceilings respected Deployment itself is yours — Serverless, SAM, CDK, Terraform; tslib is a library and has no opinion. Three settings are not optional: - **`reservedConcurrency` on every function.** It is free; _provisioned_ concurrency is what bills, and this is the only thing holding your fleet under the platform's database connection ceiling. - **`maximumRetryAttempts: 0` on the actor.** A retried invocation replays the game from the start. - **A timeout above `gameWaitingSeconds + gameRunningSeconds` plus a margin**, and under the 900-second Lambda ceiling. The environment your functions need is the fixed set `gamebaseOptionsFromEnv()` reads, plus the two prefixes from step 1 — [Operations § Configuration is injected, never read](operations.md#configuration-is-injected-never-read) lists them, and [Operations § Sizing a run](operations.md#sizing-a-run) has the arithmetic. ## 6. Connect a client Your entry API from step 4 gives the client two things: the `gameId` it allocated, and the channel JWT the player signed in with ([Authentication](auth.md)). ```ts import { createGatewayGameClient } from "@yingyeothon/gamebase-client"; const game = createGatewayGameClient({ // The console shows wsUrl as `wss://gw.yyt.life/?channel=q_…`. // Pass the origin only; the SDK adds the query string itself. url: "wss://gw.yyt.life", channelId: "q_0123456789abcdef", gameId, // from your entry API; the caller must be in the start event token: channelJwt, }); game.on("frame", (frame) => { // Every game-defined frame, verbatim — your own schema from step 3. console.log(frame); }); game.on("finished", () => { /* close 1000: the game ended normally, show the result */ }); game.on("aborted", () => { /* close 4001: the actor died, and a retry needs a NEW gameId */ }); await game.connect(); game.send({ type: "attack", power: 3 }); ``` `connect()` resolves when the socket opens, because a `q` channel has no `hello` frame — so a connected socket is not yet a joined run. Wait for the actor's first frame. ## 7. Keep going - [The game actor](game-actor.md) — the lifecycle, and the contract that fails silently when a gateway gets it wrong. - [Authentication](auth.md) — closing the identity gap that `resolveMemberId` leaves open by default. - [Storage](storage.md) — anything that must outlive the run, on your side. - [Key-value store](kvstore.md) — announcements and each player's own record, read and written by the client with the same channel JWT it connected with. - [Asset bundles](assets.md) — files the game loads from the CDN, encrypted with a key the app carries when they must not be public. - [Troubleshooting](troubleshooting.md) — when a frame does not arrive.