Docs
Guides and references for building games on AI Chat Games.
Getting Started
Recipes
- Multi-character scenesPattern for several AI characters in a shared scene, each tracking their own perspective. One agent per character, broadcast each event via addMessage, take turns via message-less send. Covers chat rooms, juries, panels, councils, debates, ensemble casts.
- Structured output (generative scenarios)Use agent.send with responseFormat and a Zod schema to get typed, parsed JSON back instead of free text. The schema's .describe() calls are the spec the LLM follows. Ideal for generating a whole scenario, cast, or config once at game start, then driving the rest of the game from it.
- Custom (non-Chat) frontendsBuild a bespoke UI instead of the built-in Chat. defineFrontend gives you state, emit, and gameHistory — render whatever you want from them. Derive views (e.g. per-character threads) from gameHistory.recentBlocks rather than duplicating transcripts in state, type sub-components from the SDK's exported building blocks, and theme with the host site's CSS variables.
- Reference images & multi-character shotsUse generateImage's referenceImages to keep a character visually consistent across images and to compose several characters into one image (a two-shot of both speakers, a group scene). Generate one canonical portrait per character, store its URL in state, then pass it as a reference for every later shot.
- Time, ticks & background playHow to build time-driven games — countdown timers, pets, farms, day/night, idle simulations. Pair onTick with tickInterval to run code on a fixed cadence; read the two frozen clocks state.gameTime (game-active ms, the one for timers) and state.now (wall timestamp, for real-world logic); emit input events from a tick to bridge into onEvent; and opt into backgroundExecution to keep ticking up to 48h after the player leaves.
- NotificationsReach the player when something happens in your game — "your farm needs water", "the negotiation took a turn". Call ctx.io.notify({ title, body, image?, tag? }) from onEvent (or a tool's execute) to push a notification into the player's cross-game inbox (the nav bell) and, when they're on the site, a toast. Detect a condition in onTick and bridge to onEvent with emitInputEvent. Notifications are replay-safe, free (only the content you generate spends), and coalesce by tag.