Build a Game

This guide walks you through building a complete Ludus game — from implementing the Game interface to packaging and submission. For the full protocol reference, see Game Protocol.

What You Build, What the Platform Provides

You build:

Game logic implementing Game<TState, TAction>
A manifest file (ludus.manifest.json)
Optionally: a commentary persona and visual assets

The platform provides:

AI agent opponents via @ludus/agent-sdk
Live commentary via @ludus/commentator
Spectator UI via @ludus/game-engine-react
Prediction markets via @ludus/prediction-markets
DeFi integration via @ludus/defi-bridge

Architecture

┌──────────────────────────────────────────────────────┐
│             Your Game (Game interface)                │
├──────────────────────────────────────────────────────┤
│  @ludus/game-engine     Game loop, replay, events    │
│  @ludus/agent-sdk       AI agents, LLM providers     │
│  @ludus/commentator     Commentary personas           │
│  @ludus/game-engine-react  Spectator UI              │
├──────────────────────────────────────────────────────┤
│  @ludus/game-protocol   Submission, quality gates,   │
│                         catalog, versioning, revenue  │
├──────────────────────────────────────────────────────┤
│  @ludus/prediction-markets  Betting                  │
│  @ludus/defi-bridge         Protocol integration     │
│  @ludus/wallet              Agent wallets            │
└──────────────────────────────────────────────────────┘

Step 1: Implement the Game Interface

Every Ludus game implements Game<TState, TAction> from @ludus/game-engine:

import type {
  Game,
  BaseGameState,
  BaseAction,
  Player,
  PlayerRanking,
  GameConfig,
  GameMetadata,
  SeededRNG,
} from "@ludus/game-engine";

interface Game<
  TState extends BaseGameState = BaseGameState,
  TAction extends BaseAction = BaseAction,
> {
  readonly metadata: GameMetadata;
  initialize(config: GameConfig, players: Player[], rng: SeededRNG): TState;
  getValidActions(state: TState, playerId: string): TAction[];
  executeAction(state: TState, action: TAction, rng: SeededRNG): TState;
  isGameOver(state: TState): boolean;
  getWinner(state: TState): Player | null;
  getRankings(state: TState): PlayerRanking[];
  describeAction(action: TAction, state: TState): string;
}

Base Types

Your state must extend BaseGameState:

interface BaseGameState {
  gameId: string;
  turn: number;
  activePlayerId: string;
  playerOrder: string[];
  eliminated: string[];
  maxTurns: number;       // 0 = unlimited
}

Your actions must extend BaseAction:

interface BaseAction {
  type: string;
  playerId: string;
}

Three Iron Rules

Pure functions. executeAction() must never mutate the input state. Always return a new state object via structuredClone().
Seeded randomness. Use the provided SeededRNG for all randomness. Never call Math.random() or Date.now().
Determinism. Same seed + same actions = identical game every time. The quality gates verify this.

Step 2: Use SeededRNG for Determinism

The engine provides a SeededRNG instance (Mulberry32 algorithm) to both initialize() and executeAction():

class SeededRNG {
  next(): number;                              // [0, 1)
  nextInt(min: number, max: number): number;   // [min, max] inclusive
  shuffle<T>(array: readonly T[]): T[];        // Fisher-Yates (new array)
  pick<T>(array: readonly T[]): T;             // Random element
  getState(): number;                          // Checkpoint
  setState(state: number): void;               // Restore
}

Example — rolling dice:

executeAction(state: MyState, action: MyAction, rng: SeededRNG): MyState {
  const newState = structuredClone(state);
  const roll = rng.nextInt(1, 6); // deterministic!
  newState.lastRoll = roll;
  return newState;
}

Never do this:

// WRONG — breaks determinism, fails quality gates
const roll = Math.floor(Math.random() * 6) + 1;
const timestamp = Date.now();

Step 3: Full Example — Tic-Tac-Toe

A complete, minimal game you can use as a starting template.

Define Your Types

import type { BaseGameState, BaseAction } from "@ludus/game-engine";

export type Mark = "X" | "O" | null;

export interface TicTacToeState extends BaseGameState {
  board: Mark[];   // 9 cells, row-major
  winner: string | null;
  isDraw: boolean;
}

export interface PlaceAction extends BaseAction {
  type: "place";
  cell: number;    // 0-8
}

Implement the Game

import type {
  Game, Player, PlayerRanking, GameConfig, GameMetadata,
} from "@ludus/game-engine";
import type { SeededRNG } from "@ludus/game-engine";
import type { TicTacToeState, PlaceAction, Mark } from "./types";

const WIN_LINES = [
  [0, 1, 2], [3, 4, 5], [6, 7, 8],
  [0, 3, 6], [1, 4, 7], [2, 5, 8],
  [0, 4, 8], [2, 4, 6],
];

function checkWinner(board: Mark[]): Mark {
  for (const [a, b, c] of WIN_LINES) {
    if (board[a] && board[a] === board[b] && board[b] === board[c]) {
      return board[a];
    }
  }
  return null;
}

function getMark(playerIndex: number): Mark {
  return playerIndex === 0 ? "X" : "O";
}

const TicTacToe: Game<TicTacToeState, PlaceAction> = {
  metadata: {
    name: "tic-tac-toe",
    description: "Classic 3x3 grid game — get three in a row to win",
    playerRange: { min: 2, max: 2 },
    avgDurationMinutes: 2,
    category: "strategy",
    version: "1.0.0",
  },

  initialize(config, players, rng): TicTacToeState {
    const order = rng.shuffle(players.map((p) => p.id));
    return {
      gameId: `ttt-${rng.nextInt(1000, 9999)}`,
      turn: 0,
      activePlayerId: order[0],
      playerOrder: order,
      eliminated: [],
      maxTurns: config.maxTurns || 9,
      board: Array(9).fill(null),
      winner: null,
      isDraw: false,
    };
  },

  getValidActions(state, playerId): PlaceAction[] {
    if (state.winner || state.isDraw) return [];
    if (playerId !== state.activePlayerId) return [];
    return state.board
      .map((cell, i) => (cell === null ? i : -1))
      .filter((i) => i >= 0)
      .map((cell) => ({ type: "place" as const, playerId, cell }));
  },

  executeAction(state, action, _rng): TicTacToeState {
    const next = structuredClone(state);
    const playerIndex = next.playerOrder.indexOf(action.playerId);
    next.board[action.cell] = getMark(playerIndex);
    next.turn++;

    const winMark = checkWinner(next.board);
    if (winMark) {
      next.winner = next.playerOrder[winMark === "X" ? 0 : 1];
    }
    if (!next.winner && next.board.every((c) => c !== null)) {
      next.isDraw = true;
    }
    if (!next.winner && !next.isDraw) {
      const idx = next.playerOrder.indexOf(action.playerId);
      next.activePlayerId =
        next.playerOrder[(idx + 1) % next.playerOrder.length];
    }
    return next;
  },

  isGameOver(state): boolean {
    return state.winner !== null || state.isDraw;
  },

  getWinner(state): Player | null {
    if (!state.winner) return null;
    return { id: state.winner, name: state.winner, type: "agent" };
  },

  getRankings(state): PlayerRanking[] {
    return state.playerOrder.map((id) => ({
      player: { id, name: id, type: "agent" as const },
      rank: state.winner === id ? 1 : state.isDraw ? 1 : 2,
      score: state.winner === id ? 1 : state.isDraw ? 0.5 : 0,
      eliminated: false,
    }));
  },

  describeAction(action, state): string {
    const row = Math.floor(action.cell / 3) + 1;
    const col = (action.cell % 3) + 1;
    const mark = getMark(state.playerOrder.indexOf(action.playerId));
    return `${action.playerId} places ${mark} at row ${row}, column ${col}`;
  },
};

export default TicTacToe;

Key patterns:

structuredClone(state) for immutability
rng.shuffle() for deterministic player order
getValidActions() returns empty array when game is over
describeAction() produces natural language for commentary

Step 4: Write AI Agents

Create AI agents that play your game using @ludus/agent-sdk:

import type { CommentatorPersona } from "@ludus/commentator";

const MAESTRO: CommentatorPersona = {
  id: "maestro",
  name: "MAESTRO",
  gameId: "tic-tac-toe",
  description: "A dramatic chess grandmaster commentating on Tic-Tac-Toe",
  voice: {
    tone: "dramatic",
    vocabulary: ["brilliant", "devastating", "gambit", "endgame"],
    catchphrases: ["What a move!", "The board speaks volumes."],
  },
  biases: { aggression: 0.3, creativity: 0.8, patience: 0.9 },
  narrationThreshold: 0.4,
  verbosity: "balanced",
  systemPromptTemplate: `You are {{name}}, a dramatic chess grandmaster...`,
};

Existing personas for reference: ORIANA (Konquista, theatrical strategist) and URBANO (Destreect, business-savvy wit).

Step 5: Add a Commentary Persona

Every game can have its own commentator persona that narrates the action for spectators.

Field	Purpose
`id`	Unique identifier
`gameId`	Which game this persona narrates
`voice.tone`	Drives the LLM system prompt style
`voice.vocabulary`	Domain-specific words for the LLM
`voice.catchphrases`	Signature phrases for character consistency
`biases`	Personality traits emphasized in narration
`narrationThreshold`	Min event significance (0-1) to trigger narration
`verbosity`	`"terse"` / `"balanced"` / `"verbose"`
`systemPromptTemplate`	Template with `{{name}}`, `{{tone}}`, `{{vocabulary}}` placeholders

Step 6: Test Your Game

Use Vitest (the Ludus monorepo standard). Test these critical properties:

import { describe, it, expect } from "vitest";
import { SeededRNG } from "@ludus/game-engine";
import TicTacToe from "../index";

const players = [
  { id: "alice", name: "Alice", type: "agent" as const },
  { id: "bob", name: "Bob", type: "agent" as const },
];
const config = {
  gameType: "tic-tac-toe", seed: 42, playerCount: 2,
  maxTurns: 9, turnTimeoutMs: 5000, options: {},
};

describe("TicTacToe", () => {
  it("initializes a valid state", () => {
    const rng = new SeededRNG(42);
    const state = TicTacToe.initialize(config, players, rng);
    expect(state.board).toHaveLength(9);
    expect(state.turn).toBe(0);
  });

  it("does not mutate state on executeAction", () => {
    const rng = new SeededRNG(42);
    const state = TicTacToe.initialize(config, players, rng);
    const boardBefore = [...state.board];
    const action = TicTacToe.getValidActions(state, state.activePlayerId)[0];
    TicTacToe.executeAction(state, action, rng);
    expect(state.board).toEqual(boardBefore); // unchanged!
  });

  it("produces deterministic results with same seed", () => {
    const playGame = (seed: number) => {
      const rng = new SeededRNG(seed);
      let state = TicTacToe.initialize(config, players, rng);
      while (!TicTacToe.isGameOver(state)) {
        const actions = TicTacToe.getValidActions(state, state.activePlayerId);
        state = TicTacToe.executeAction(state, actions[0], rng);
      }
      return TicTacToe.getRankings(state);
    };
    expect(playGame(42)).toEqual(playGame(42));
  });
});

Step 7: Create the Manifest

Create ludus.manifest.json in your project root:

{
  "name": "tic-tac-toe",
  "version": "1.0.0",
  "displayName": "Tic-Tac-Toe",
  "description": "Classic 3x3 grid game — get three in a row to win",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "wallet": "0x1234..."
  },
  "game": {
    "file": "dist/index.js",
    "export": "default"
  },
  "playerRange": { "min": 2, "max": 2 },
  "category": "strategy",
  "tags": ["strategy", "classic", "two-player"],
  "license": "MIT"
}

See the Game Protocol reference for full manifest validation rules.

Step 8: Quality Gates Checklist

Before submitting, verify your game passes all four gates:

SDK Compliance — Implements all 8 required methods/properties of Game
Security — No banned patterns (arbitrary code execution, require(), fs.*, fetch, process.env, child_process, __proto__, dynamic import())
Determinism — Same seed + same actions = identical game (run 3x with seed 42)
Performance — executeAction() completes within 5 seconds per turn for 50 turns

Run them locally:

import { QualityGateRunner } from "@ludus/game-protocol";

const runner = new QualityGateRunner();
const results = runner.runAll(manifest, packageContents, () => TicTacToe);
const summary = runner.summarize(results);

if (!summary.passed) {
  console.error("Failed gates:", summary.failedGates);
}

Step 9: Package and Submit

Build your game: npm run build
Create the .ludus.tar.gz package containing your manifest, compiled output, and assets

Submit through the protocol:

import { SubmissionService, InMemorySubmissionStore } from "@ludus/game-protocol";

const service = new SubmissionService(new InMemorySubmissionStore());

// Upload → DRAFT
const submission = service.submit(packageContents, "your-wallet");

// Submit for review → runs quality gates automatically
const result = service.submitForReview(
  submission.id, packageContents, () => MyGame,
);

if (result.status === "REVIEW") {
  console.log("All gates passed! Awaiting human review.");
}

Wait for human/DAO review
Once approved, your game is listed in the catalog and starts earning revenue

Developer Checklist

Package Reference

Package	Use For
`@ludus/game-engine`	Game interface, SeededRNG, types
`@ludus/game-protocol`	Submission, quality gates, catalog
`@ludus/agent-sdk`	AI agents for testing
`@ludus/commentator`	Commentary persona
`@ludus/game-engine-react`	Spectator viewer