Tic-tac-toe with bots

This tutorial picks up where Tic-tac-toe with gamekit leaves off. Same game, same app, same cli — we add one optional field to the game and a sibling bots package, then wire them into the CLI so a human can play against the computer. Reference code: examples/games/tic-tac-toe/bots and the bot-aware CLI at examples/games/tic-tac-toe/cli.

1. Add the `legalActions` hook to the game

The bot runtime needs to know which moves a seat may legally play. Add one field to defineGame in game/src/index.ts:

export const ticTacToe = defineGame({
  maxPlayers: 2,
  legalActions: ({ G, derived }, playerID) => {
    if (!derived.activePlayers.includes(playerID)) return [];
    const out: { event: string; payload: PlaceMarkArgs; label: string }[] = [];
    for (let row = 0; row < G.board.length; row += 1) {
      const cells = G.board[row]!;
      for (let col = 0; col < cells.length; col += 1) {
        if (cells[col] === null) {
          out.push({ event: "placeMark", payload: { row, col }, label: `(${row},${col})` });
        }
      }
    }
    return out;
  },
  // ...existing fields: setup, turn, moves, views, computed
});
// playerIDs is now part of the definition; the legacy `defineGame(match, ...)` form
// is gone — see [Reference: core](/reference/core#definegame-definition).

Three things are worth noting:

The engine never reads this field. It is metadata for the bot runtime. Authors who don’t ship bots can omit it.
We return [] when the seat is not in derived.activePlayers, so the runner knows it is not this seat’s turn.
payload is { row, col } — the same shape the existing placeMark move accepts.

2. Create the `bots` package

Same workspace, sibling to game/, app/, and cli/.

`bots/package.json`

{
  "name": "@my/tic-tac-toe-bots",
  "private": true,
  "type": "module",
  "openturn": { "runtime": "worker" },
  "exports": { ".": "./src/index.ts" },
  "scripts": { "typecheck": "bun x tsc -p tsconfig.json" },
  "dependencies": {
    "@openturn/bot": "workspace:*",
    "@openturn/core": "workspace:*",
    "@my/tic-tac-toe-game": "workspace:*"
  }
}

`bots/tsconfig.json`

{
  "extends": "../../../../tsconfig.worker.json",
  "compilerOptions": { "composite": true },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts"]
}

3. Write the random bot

bots/src/random.ts:

import { defineBot } from "@openturn/bot";
import type { ticTacToe } from "@my/tic-tac-toe-game";

export const randomBot = defineBot<typeof ticTacToe>({
  name: "random",
  decide({ legalActions, rng }) {
    if (legalActions.length === 0) {
      throw new Error("randomBot: no legal actions available");
    }
    return rng.pick(legalActions);
  },
});

That is the entire bot. rng is forked from the snapshot’s RNG and salted by bot name + seat + turn, so identical seeds produce identical bot games.

4. Write the minimax bot

Tic-tac-toe is small enough that depth-9 alpha-beta minimax solves the position exactly. bots/src/minimax.ts:

import { defineBot, simulate } from "@openturn/bot";
import { ticTacToe } from "@my/tic-tac-toe-game";

const OTHER: Record<string, string> = { "0": "1", "1": "0" };

interface ResultLike { winner?: string; draw?: boolean }

function legalForSnapshot(snapshot: { G: { board: (string | null)[][] } }, playerID: string) {
  const out = [];
  for (let row = 0; row < snapshot.G.board.length; row += 1) {
    const cells = snapshot.G.board[row]!;
    for (let col = 0; col < cells.length; col += 1) {
      if (cells[col] === null) {
        out.push({ event: "placeMark", payload: { row, col } });
      }
    }
  }
  return out;
}

function evaluate(snapshot: { meta: { result: ResultLike | null } }, me: string): number | null {
  const r = snapshot.meta.result;
  if (r === null || r === undefined) return null;
  if (r.draw === true) return 0;
  if (r.winner === me) return 10;
  if (typeof r.winner === "string") return -10;
  return 0;
}

function search(snapshot: never, toMove: string, me: string, depth: number, alpha: number, beta: number): number {
  const terminal = evaluate(snapshot as never, me);
  if (terminal !== null) return terminal - Math.sign(terminal) * depth;

  const moves = legalForSnapshot(snapshot as never, toMove);
  if (moves.length === 0) return 0;

  if (toMove === me) {
    let best = -Infinity;
    for (const action of moves) {
      const sim = simulate(ticTacToe, snapshot, toMove as never, action);
      if (!sim.ok) continue;
      best = Math.max(best, search(sim.next as never, OTHER[toMove]!, me, depth + 1, alpha, beta));
      alpha = Math.max(alpha, best);
      if (alpha >= beta) break;
    }
    return best;
  }
  let best = Infinity;
  for (const action of moves) {
    const sim = simulate(ticTacToe, snapshot, toMove as never, action);
    if (!sim.ok) continue;
    best = Math.min(best, search(sim.next as never, OTHER[toMove]!, me, depth + 1, alpha, beta));
    beta = Math.min(beta, best);
    if (alpha >= beta) break;
  }
  return best;
}

export const minimaxBot = defineBot<typeof ticTacToe>({
  name: "minimax",
  thinkingBudgetMs: 5_000,
  decide({ legalActions, snapshot, playerID }) {
    if (legalActions.length === 0) throw new Error("minimaxBot: no legal actions");
    if (snapshot === null) return legalActions[0]!;     // hosted host: simulate unavailable

    let bestAction = legalActions[0]!;
    let bestScore = -Infinity;
    for (const action of legalActions) {
      const sim = simulate(ticTacToe, snapshot, playerID, action);
      if (!sim.ok) continue;
      const score = search(sim.next as never, OTHER[playerID]!, playerID, 1, -Infinity, Infinity);
      if (score > bestScore) { bestScore = score; bestAction = action; }
    }
    return bestAction;
  },
});

Three things keep this honest:

We use simulate from @openturn/bot to dry-run candidates. It clones the snapshot, applies the move, and returns the resulting snapshot — the live session is never touched.
Alpha-beta pruning + depth-as-tiebreaker (terminal - Math.sign(terminal) * depth) makes the bot prefer faster wins and slower losses.
The hosted-host fallback (snapshot === null) returns a legal action — search-based bots run as in-process bots; over the network, switch to a heuristic strategy.

`bots/src/index.ts`

export { randomBot } from "./random";
export { minimaxBot } from "./minimax";

5. Wire bots into the CLI

The CLI already pulls createLocalSession and the game definition. Patch it to accept a --bot <seat>=<name> flag:

import { stdout } from "node:process";
import { attachLocalBots, type Bot } from "@openturn/bot";
import { createLocalSession, type PlayerID } from "@openturn/core";
import { minimaxBot, randomBot } from "@my/tic-tac-toe-bots";
import { ticTacToe } from "@my/tic-tac-toe-game";

const cliArgs = Bun.argv.slice(2);
const botFlags = parseBotFlags(cliArgs);     // e.g. { "1": "random" }

const raw = createLocalSession(ticTacToe, { match: { players: ticTacToe.playerIDs } });

const bots: Partial<Record<PlayerID, Bot<typeof ticTacToe>>> = {};
for (const [seat, name] of Object.entries(botFlags)) {
  const bot = name === "random" ? randomBot : name === "minimax" ? minimaxBot : null;
  if (bot === null) {
    console.error(`Unknown bot "${name}". Available: random, minimax.`);
    process.exit(1);
  }
  bots[seat] = bot;
}

const { session, isBot, whenIdle, detachAll } = attachLocalBots({
  session: raw,
  game: ticTacToe,
  bots,
});

try {
  await play();
} finally {
  detachAll();
}

async function play() {
  while (true) {
    const snapshot = session.getState();
    if (snapshot.meta.result?.winner) {
      console.log(`Winner: ${snapshot.meta.result.winner}`);
      return;
    }
    if (snapshot.meta.result?.draw) {
      console.log("Draw");
      return;
    }

    const playerID = snapshot.derived.activePlayers[0]!;

    if (isBot(playerID)) {
      console.log(`Bot ${playerID} thinking...`);
      await whenIdle(playerID);
      continue;
    }

    // ... existing human-input path: read stdin, parse, applyEvent
  }
}

function parseBotFlags(args: readonly string[]): Record<PlayerID, string> {
  const out: Record<PlayerID, string> = {};
  for (let i = 0; i < args.length; i += 1) {
    if (args[i] !== "--bot") continue;
    const value = args[i + 1];
    if (value === undefined) throw new Error("--bot expects <seat>=<name>");
    const eq = value.indexOf("=");
    if (eq < 0) throw new Error(`--bot value "${value}" must be <seat>=<name>`);
    out[value.slice(0, eq)] = value.slice(eq + 1);
  }
  return out;
}

Key details:

We call applyEvent on the returned session, not the raw one. The facade notifies the runner so the bot wakes up after each human move.
isBot(playerID) and whenIdle(playerID) come from the same return value — no per-bot bookkeeping.
detachAll() runs in finally so the runner is always cleaned up, even on errors.

6. Run it

# Random bot opponent
bun run cli/src/index.ts --bot 1=random

# Optimal-play opponent
bun run cli/src/index.ts --bot 1=minimax

# Two bots play each other (no human input expected)
bun run cli/src/index.ts --bot 0=minimax --bot 1=random

Against random, you should win most games as long as you take the center first. Against minimax, the best you can do is force a draw — depth-9 alpha-beta solves tic-tac-toe.

7. Add tests

The pure-functional engine makes integration tests cheap. A 1000-match random-vs-random suite verifies the runner end-to-end in a few seconds:

// bots/src/index.test.ts
import { describe, expect, test } from "bun:test";
import { attachLocalBots } from "@openturn/bot";
import { createLocalSession } from "@openturn/core";
import { ticTacToe } from "@my/tic-tac-toe-game";
import { randomBot } from "./random";

test("1000 matches: every match terminates legally", async () => {
  const matches = 1000;
  const buckets = { winner0: 0, winner1: 0, draw: 0 };

  for (let i = 0; i < matches; i += 1) {
    const raw = createLocalSession(ticTacToe, {
      match: { players: ticTacToe.playerIDs },
      seed: `r-${i}`,
    });
    const { session, isBot, whenIdle, detachAll } = attachLocalBots({
      session: raw,
      game: ticTacToe,
      bots: { "0": randomBot, "1": randomBot },
    });

    for (let step = 0; step < 20; step += 1) {
      const snapshot = session.getState();
      if (snapshot.meta.result !== null) break;
      const active = snapshot.derived.activePlayers[0]!;
      if (isBot(active)) await whenIdle(active);
    }

    const r = session.getState().meta.result;
    expect(r).not.toBeNull();
    if (r?.draw) buckets.draw += 1;
    else if (r?.winner === "0") buckets.winner0 += 1;
    else if (r?.winner === "1") buckets.winner1 += 1;

    detachAll();
  }

  expect(buckets.winner0 + buckets.winner1 + buckets.draw).toBe(matches);
  expect(buckets.draw).toBeGreaterThan(0);
}, 60_000);

bun test runs it.

What you have built

One additive field on the game (legalActions) that the engine ignores and the bot runtime uses.
A sibling bots package with a 5-line random bot and a 60-line alpha-beta minimax bot.
A CLI that takes --bot <seat>=<name> and drives the same loop for human-vs-human, human-vs-bot, and bot-vs-bot.
An integration test that proves the runner terminates 1000 matches legally.

Cloud play uses attachHostedBot against a HostedClient, with the bot living in a separate sidecar process — see Concepts: bots.

Tutorial: tic-tac-toe with gamekit — the base game this builds on.
Concepts: AI bots — design rationale.
Reference: @openturn/bot — full API.
How-to: add a bot — practical recipes for heuristic and search-based bots.

​1. Add the legalActions hook to the game

​2. Create the bots package

​bots/package.json

​bots/tsconfig.json

​3. Write the random bot

​4. Write the minimax bot

​bots/src/index.ts

​5. Wire bots into the CLI

​6. Run it

​7. Add tests

​What you have built

​Related