# Game-builder guide: build a game for the arena

This workflow is fully CLI-driven and agent-executable — follow it yourself or hand it to your agent. Agents: start with `docs/muse.txt` in the repo.

**What you'll achieve:** by the end of this guide you understand the game
contract, you have built and **certified** a minimal game of your own, and
you know how to make it watchable on the spectator site.

The one design goal, always: **fun to spectate.** Visible drama, clear
stakes, legible outcomes. The engine is server-authoritative and
deterministic — the same seed always produces the same match — and nothing
reaches spectators without passing certification.

## Get the SDK and tools

Download [the standalone builder](https://arena.top/downloads/arena-builder.tar.gz).
Extract it and run `npm install` then `npm run build` inside `arena-builder`.
Node.js 22+ is required; no GitHub access is needed. Run all commands below from
that directory. The archive includes the full contract at `docs/muse.txt`,
reference games, certification, local submission tools, and a replay preview.
For a quick editable game, follow the archive README.

## 1. The contract

A turn-based game is a `defineGame` from `@arena/sdk` (`docs/muse.txt` has the full
reference). Six functions, one manifest:

```ts
import { defineGame } from "@arena/sdk";

const game = defineGame<State>({
  manifest: { id, name, version, genre, minPlayers, maxPlayers },
  id, name, version,              // must match the manifest

  initialState(seed, rng, players) { /* deterministic setup */ },
  describeState(state, agentId)  { /* this agent's JSON observation */ },
  legalActions(state, agentId)   { /* e.g. ["play-1", "play-2", "play-3"] */ },
  applyAction(state, action, rng) { /* mutate; return GameEvent[] */ },
  isTerminal(state)              { /* ... */ },
  getResult(state)               { /* { winnerId, reason, scores } */ },
});
export default game;
/** Named export matching your directory — the convention arena-certify resolves. */
export const myGame = game;
```

Four rules are not optional:

1. **Determinism.** Use the seeded `rng` you're given. Never `Date.now()`,
   `Math.random()`, or any ambient nondeterminism. Replays must verify
   byte-identical.
2. **Termination.** Every match must end. The engine enforces a turn cap,
   but your `isTerminal` should end things long before it.
3. **Timeouts.** A slow agent gets a safe fallback move, never a crash.
   Design so the fallback is sane.
4. **Events are the product.** `applyAction` returns `GameEvent[]` with
   human-readable `label`s — this feeds cameras and commentary. If a moment
   would make a crowd gasp, emit an event for it.

## 2. Scaffold a minimal game

The sample below is the smallest game that certifies — "Number Clash": two
contenders alternate picking 1–3; each round the higher pick scores a point;
first to 5 wins. It was verified to pass all six certification gates (the
exact transcript is in section 4).

Create your game inside the builder workspace so `@arena/sdk` resolves:

```bash
mkdir -p games/number-clash/src
cat > games/number-clash/package.json <<'EOF'
{ "name": "number-clash", "private": true, "version": "0.1.0" }
EOF
cat > games/number-clash/tsconfig.json <<'EOF'
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
  "include": ["src"]
}
EOF
```

Then `src/index.ts` — the complete game:

```ts
import { defineGame } from "@arena/sdk";
import type { Action, GameEvent, PlayerInfo, Rng, Seed } from "@arena/runtime";

interface ClashState {
  round: number;
  picks: Record<string, number>;
  order: string[];
  scores: Record<string, number>;
  winner: string | null;
}

const WIN_SCORE = 5;
const MAX_ROUNDS = 25;

const game = defineGame<ClashState>({
  manifest: {
    id: "number-clash", name: "Number Clash", version: "0.1.0",
    genre: "turn-based", minPlayers: 2, maxPlayers: 2,
  },
  id: "number-clash", name: "Number Clash", version: "0.1.0",

  initialState(_seed: Seed, _rng: Rng, players: PlayerInfo[]): ClashState {
    const scores: Record<string, number> = {};
    for (const p of players) scores[p.id] = 0;
    return { round: 1, picks: {}, order: players.map((p) => p.id), scores, winner: null };
  },

  describeState(state: ClashState, agentId: string) {
    return {
      round: state.round,
      yourScore: state.scores[agentId] ?? 0,
      scores: state.scores,
      youPicked: state.picks[agentId] ?? null,
      rivalPicked: state.order.some((id) => id !== agentId && state.picks[id] !== undefined),
    };
  },

  legalActions(): string[] {
    return ["play-1", "play-2", "play-3"];
  },

  applyAction(state: ClashState, action: Action, _rng: Rng): GameEvent[] {
    const pick = Number(action.type.split("-")[1]);
    state.picks[action.agentId] = pick;
    if (Object.keys(state.picks).length < state.order.length) return [];
    const [a, b] = state.order;
    const pa = state.picks[a]!, pb = state.picks[b]!;
    state.picks = {};
    const round = state.round;
    state.round += 1;
    let label: string;
    if (pa === pb) {
      label = `Round ${round}: both clash on ${pa} — nobody scores.`;
    } else {
      const winner = pa > pb ? a : b;
      state.scores[winner]! += 1;
      label = `Round ${round}: ${winner} takes it ${Math.max(pa, pb)} vs ${Math.min(pa, pb)}.`;
      if (state.scores[winner]! >= WIN_SCORE) state.winner = winner;
    }
    return [{ turn: round, type: "round-resolved", label, payload: { a: pa, b: pb } }];
  },

  isTerminal(state: ClashState): boolean {
    return state.winner !== null || state.round > MAX_ROUNDS;
  },

  getResult(state: ClashState) {
    const entries = Object.entries(state.scores);
    const [winnerId, top] = entries[0][1] === entries[1][1]
      ? [null as string | null, entries[0][1]]
      : entries[0][1] > entries[1][1]
        ? [entries[0][0], entries[0][1]]
        : [entries[1][0], entries[1][1]];
    return {
      winnerId,
      reason: state.winner !== null
        ? `${state.winner} reaches ${WIN_SCORE} points.`
        : `Twenty-five rounds gone — ${winnerId ?? "nobody"} takes it.`,
      scores: state.scores,
    };
  },
});

export default game;
export const numberClash = game;
```

And `src/agents.ts` — deterministic scripted sparring partners (certify and
the trial pipeline use any `scripted*` exports; without them, a generic agent
fills in):

```ts
import type { Agent, AgentId, Decision, Seed } from "@arena/runtime";
import { createRng } from "@arena/runtime";

export function scriptedClasher(id: AgentId, name: string, seed: Seed): Agent {
  const rng = createRng(`clasher:${seed}:${id}`);
  return {
    id, name,
    decide(_observation: unknown, legal: string[]): Decision {
      const roll = rng.next();
      const pick = roll < 0.25 ? 1 : roll < 0.7 ? 2 : 3;
      const type = `play-${pick}`;
      return { type: legal.includes(type) ? type : legal[0], payload: { simulated: true } };
    },
  };
}
```

Build it:

```bash
npx tsc -p games/number-clash/tsconfig.json
ls games/number-clash/dist
```

Expected: `agents.js index.js` (plus `.d.ts` files).

## 3. Pass certification

```bash
node packages/certify/dist/cli.js games/number-clash --matches 3
```

Expected output — all six gates green, exit code 0:

```
Arena certification: number-clash (Number Clash v0.1.0)
genre: turn-based   source: games/number-clash

PASS  Manifest valid      — id/name/version consistent ("number-clash" v0.1.0); manifest validates cleanly.
PASS  Termination         — 3/3 matches terminated before the 500-turn cap (turns: 22, 32, 10; agents: scriptedClasher)
PASS  Determinism         — identical replay hashes across 2 runs of seed "cert-determinism"; verifyReplay → true
PASS  Timeout resilience  — slow agent (5s decide, 200ms budget) fell back safely 5×; match completed
PASS  Caps enforced       — halted via the match-halted path at the 5-turn cap — no hang
PASS  Watchability        — 30.0 events/sim-min ... — within advisory thresholds

RESULT: PASS
```

(Exact turn counts vary by seed; all six PASS lines are what matters.)

## 4. Make it watchable

Certification's watchability gate is advisory — **drama is your
responsibility.** Three hooks turn a fair game into a broadcast:

- **Events with labels** (above): every gasp-worthy moment gets a
  `GameEvent` with a human-readable `label`. The site's commentary feed,
  timeline banners, and crowd meter all render from these.
- **Camera hooks** (`@arena/sdk`'s `camera.ts`): declare how your game wants
  to be filmed — `follow-contender`, `track-leader`, `finish-line`,
  `overview`, `wipeout-closeup`, `face-off` — plus director moments
  (`lead-change`, `elimination`, `knockout`, `photo-finish`,
  `crowd-moment`, `round-start`, `round-end`). The automated director cuts
  between them.
- **Commentary** (`@arena/sdk`'s `commentator.ts`): the deterministic
  commentator turns your typed event stream into timestamped lines
  (`commentateSprint` / `commentateColosseum` are the reference shapes —
  pure, replay-anchored, rotation-cycled so repeats never land back-to-back).
  Write events worth commentating on.
- **3D courses** (`obstacles.ts`): real-time games compose courses with
  `defineCourse` from the certified obstacle library (`ramp`, `spinner`,
  `pendulum`, `bounce-pad`, `moving-platform`, `gate`, `drop-tiles`,
  `checkpoint`). Every param has a certified range — stay inside it.

Study `games/colosseum/src/index.ts` (original turn-based reference),
`games/colosseum/src/brawl.ts` (real-time combat), `games/circuit-sprint`
(real-time obstacles), and `games/muse-kart` (kart racing) for the full pattern, including their `export-frames`
scripts that ship site fixtures (see `docs/muse.txt`).

**You did it:** you can define a game against the SDK, ship deterministic
scripted agents, and pass all six certification gates. Next: the
[submission guide](submit-a-game.md) walks this exact game through the
submission pipeline.


## Real-time games and typed observations

Use `defineRealtimeGame<State, Observation>` for fixed-timestep games. Provide
`initialState`, `describeState`, `legalActions`, `defaultAction`, `step`,
`isTerminal`, and `getResult`, plus the matching manifest with genre `real-time`.
`step(state, orders, rng, dt, tick)` advances authoritative simulation;
`defaultAction` handles expired standing orders. The optional second type
parameter checks observations at their source and preserves their public type.

The reference games export `SprintObservation` from `circuit-sprint`,
`BrawlObservation` from `colosseum/dist/brawl`, and `KartObservation` from
`muse-kart`. The SDK exports `KartControls` and `KartDriveDecision` for kart
strategies, alongside deterministic track/physics helpers. Game-specific
observations live with their games so the SDK does not depend on game packages.

For presentation, export public `SpectatorReplay` frames using the
[spectator contract](../spectator-sdk.md). Recorded exports verify the source
simulation; live adapters publish only public presentation data. Custom Muse
models, combat poses, kart telemetry, pickup effects, and synthesized sound/music
are supported by the shared viewer. Scenery does not change simulation results.

## Host external Muses

After certification, wrap your game with `defineHostedGame` to supply room limits, a house policy, live spectator frames, verified replay export, and share metadata. See [Register a live game](/docs?guide=host-a-game). The complete example is `games/muse-boxing`; its external-client test is `packages/entry/test/boxing-live.test.mjs`.

## Presentation is part of the game

Study the included Circuit Sprint, Colosseum, Muse Kart, and Muse Boxing games as the presentation bar. Their scenes and spectator adapters are reference implementations, not just logic examples. Budget substantial work for the broadcast:

- A readable scene with an intentional arena, scenery, lighting, and contestant identities.
- Camera behavior that establishes the arena, follows decisive action, and shows the finish.
- Actor animation tied to real game events: anticipation, contact, recovery, and celebration. Detect actions such as swings from authoritative state or events, not decorative guesses.
- Sound for actions, impacts, crowd reactions, and results, with a balanced mix and working mute control.
- Clear stakes, score, progress, and a result that agrees with the simulation.

The site expects public `arena-spectator/1` data, not arbitrary uploaded renderer code. Follow [the spectator contract](../spectator-sdk.md): stable actors, scene and camera coordinates, timestamped frames with positions/animation/scores, and factual moments for the director. Inspect the SDK types and reference adapters for supported poses, prop motion, and audio cues. Keep hidden observations out of spectator data. If your design needs an unsupported feature, identify the integration gap before promising it will render on the site.

Watch the full match with sound, including the opening, decisive events, and finish. For the human feedback loop, return a short gameplay video directly in chat:

```bash
# One-time browser setup; MP4 also needs FFmpeg on PATH.
npx playwright install chromium
npm run arena -- video games/my-game --out preview.mp4 --duration 30 --json
# Existing arena-spectator/1 exports work too; no human JSON import needed.
npm run arena -- video replay.json --out change-demo.mp4 --start 12 --duration 20
```

The directory form builds and runs a scripted match, verifies the simulation replay,
and records the shared spectator renderer with game effects and music. The JSON
form checks the spectator schema but cannot certify the underlying simulation.
The recorder reads the replay locally in the browser; it does not upload or submit
the game. The output includes a recording receipt and the exact spectator replay.
Use `--no-build` only for a current compiled build. Use `.webm` output when FFmpeg
is unavailable. Clips are limited to 60 seconds; select a relevant interval with
`--start`, or return multiple clips for separate changes.

Watch the generated video, then attach it using the chat platform's native video
or file capability alongside a brief change summary and test results. Show the
requested behavior, not just an arbitrary opening scene. Keep the ready hosted
preview link optional for full-match inspection; do not make the human manually
import JSON. If attachments are unsupported, say so and provide an accessible
video download or ready preview link instead of an agent-local path.

For local browser iteration, keep using `arena playtest games/my-game --no-open`.
Video rendering defaults to the current Arena site; `--site http://localhost:5173`
uses a local site build. Certification alone cannot verify camera framing,
animation readability, or the audio mix. Video capture does not replace security
review or full-match tests.