# The yyt platform, and where tslib sits yyt is a platform for building a multiplayer game by writing **only game logic**, in your own AWS account. This page is the map: what yyt runs, what you run, and which pieces of tslib you end up using. It states the shape and defers every detail of the wire to the `service` repository, which owns it. ## The whole picture The one box you write is at the bottom. ```mermaid flowchart TD C["browser or Unity client
gamebase-client"] GW["realtime gateway, Go
lobby and q channels"] CDN["catalog CDN
immutable map assets"] DOC["doc store
versioned JSON"] C -->|"wss, lobby"| GW C -->|"wss, q"| GW C -->|"GET, no credential"| CDN C -->|"GET and PUT own row, If-Match"| DOC subgraph platform["operated by yyt"] R[("Redis
256 MB, allkeys-lru")] DB[("MariaDB
max_connections 60")] end GW -->|"party, positions, queue, pub/sub"| R DOC --> DB subgraph yours["your AWS account"] A["game actor, Lambda
lambda-gamebase"] end GW -->|"invoke"| A A -->|"per-channel scoped ACL user"| R ``` Two consequences run through everything below. **The platform generalises storage shapes and transport scopes, never game rules** — it never learns what a "character" or an "item" is. And the client ships with no content: it receives its map, its capability set and its protocol from the server, which is what makes one client SDK work across games. ## The words this guide uses Six of them come from the platform rather than from tslib, and every later page spends them freely. | Term | Means | | ------------- | -------------------------------------------------------------------------------- | | **channel** | What you provision per game: an id, an endpoint, and a credential scoped to it | | **member** | One player of one run, named in its start event by a `memberId`. Not an account | | **zone** | A named area of a map. The lobby relays positions and chat within one | | **party** | A group a player belongs to, and therefore a relay scope the gateway understands | | **entry API** | An endpoint of _yours_ that allocates a run and hands a client its `gameId` | | **tick** | One pass of a loop: the gateway's position flush, or your game's simulation step | Three more are tslib's own and are defined where they are used: an **actor** ([The game actor](game-actor.md)), the **lease** on its lock and the **awaiter** that resolves a waiting sender ([Actor system](actor-system.md)). **`stage` means two unrelated things**, which is worth knowing before you meet the second. A deployment stage (`dev`, `prod`) appears in your Redis key prefixes; a game stage is `wait`, `running` or `end`. ## The two channel kinds A channel is what you provision in the console, and its kind decides how much the gateway understands. ```mermaid flowchart LR subgraph lobby["lobby — a scope relay"] L1[client] -->|"pos, say, party, event"| LG[gateway] LG -->|"enter, leave, snapshot
synthesised by the gateway"| L1 end subgraph q["q — an opaque bridge to your actor"] Q1[client] -->|"any payload"| QG[gateway] QG -->|"RPUSH"| QL[("Redis list
durable")] QL --> QA["your actor"] QA -->|"PUBLISH"| QP[("Redis pub/sub
lossy")] QP --> QG QG --> Q1 end ``` On a `lobby` channel the gateway knows scopes, not semantics: it routes to a zone, a party or a user, and never interprets a payload. It also synthesises the `enter`, `leave` and `snapshot` frames, which is the part clients must not reimplement — without them a player who walks away freezes on every screen. On a `q` channel the gateway understands nothing. It carries frames between the player and a `@yingyeothon/lambda-gamebase` actor running in your account, and reads none of them. **Note the asymmetry in that second diagram, because it is deliberate and it shapes your code.** Inbound is a durable Redis list: discrete, non-idempotent events that must not be lost. Outbound is pub/sub: self-contained frames where the next tick heals a gap. It is why `endRepeatCount` must be 2 or more over a gateway transport — an end frame is not a snapshot, and nothing later heals it. ## The three storage shapes Every game datum belongs to exactly one. Game-specific schema lives _inside_ a value and is never interpreted by the platform. | Shape | Backing | Example | Written by | The rule that bites | | ------------- | -------------- | -------------------------------- | ------------------------ | ------------------------------------------------- | | **asset** | S3 + CDN | a map, with NPCs inlined | an editor or upload | immutable; a new version is a new URL | | **doc** | versioned JSON | a character sheet, an inventory | a server, never a client | every write is conditional on the version it read | | **ephemeral** | Redis | party roster, retained positions | gateway or your actor | **every key carries a TTL, with no exceptions** | The TTL rule is not advice. The Redis instance is shared and runs `allkeys-lru`, and the participant credential is scoped so that key enumeration is denied — so a key written without a TTL can never be found again and will evict someone else's state. tslib enforces it where it can: `createRedisQueue`'s `ttlSeconds` is required, and `repository-redis` refuses a TTL-less `set()` outright. The conditional-write rule is the same kind of thing seen from the other side: two dungeon results landing on one inventory is the failure it exists to prevent. [Storage](storage.md) is how tslib does it. ## Where tslib fits Only `gamebase-client`, `kvstore-client` and `asset-client` name the platform in their source; `lambda-gamebase` and `gamebase-all-together` are shaped by it without depending on it. Everything else is a general library that a game happens to need. ```mermaid flowchart BT found["foundation
codec · logger · event-broker
repository · actor-system · naive-socket"] back["backends and transport
naive-redis · repository-* · actor-system-*
logger-* · s3-cache-bridge-client · lambda-authorizer"] edge["platform edges
lambda-gamebase · lambda-authorizer-jwt
gamebase-client · kvstore-client · asset-client"] loop["game loop
gamebase-all-together"] found --> back back --> edge edge --> loop ``` That is roles, not dependencies — the [root README](../README.md) has the exact edge list, and it is the only place that does. The half of the platform you replace is a `gameMain`: rules, in your own language, over messages you defined. Everything around it — the lock that stops two invocations simulating one game, the queue, the fan-out, the reconnect — belongs to the packages below it. ## What the `service` repository owns tslib follows the platform; it never defines it. These are the normative documents, all public, in [`yingyeothon/service`](https://github.com/yingyeothon/service): | Document | What it settles | | ---------------------------------- | ---------------------------------------------------------------------- | | `gateway/README.md` | **The wire spec.** Frame tables both directions, refusals, close codes | | `docs/realtime-gateway-design.md` | The two channel kinds, and what the gateway does on your behalf | | `docs/auth-game-contract.md` | The channel JWT's claims, lifetime and reuse rules | | `services/auth/README.md` | The sign-in endpoints and the token they issue | | `services/state/README.md` | The doc store and the KV routes: versioned JSON, `If-Match`, scopes | | `services/console/README.md` | Channels, secrets, and the Redis prefixes it prints as one block | | `services/match/README.md` | The matchmaking socket, one source of a `gameId` | | `cli/README.md` | The `yyt` CLI: provisioning channels and publishing map assets | | `sample-dungeon` (`examples` repo) | A whole game on this stack: auth, match, callback, actor | The Unity half of the client SDK is [`csharplib`](https://github.com/yingyeothon/csharplib), whose `docs/` is this same guide from the client side. When this page and the gateway README disagree, the gateway README is right. ## Read next [The game actor](game-actor.md), which is the box you write.