add-game

You are helping add a new game to the Ancient Games platform. This is a full-stack TypeScript monorepo (npm workspaces) with:

• shared/ — types and game manifests
• backend/ — Node.js + Express + Socket.io + game logic
• frontend/ — React 18 + Vite + Tailwind CSS

Architecture: Game Isolation

Each game is self-contained in its own folder. The platform uses registries and manifests so that adding a new game never requires modifying shared UI components (Home.tsx, MoveLog, etc.). Changes are limited to:

1. Engine-level changes (shared types, backend engine, backend registry) — committed first
2. Game-specific resources (board, rules, controls, score, manifest entry) — committed second

Arguments

Parse $ARGUMENTS as: <game-id> "<Display Name>" "<emoji>"

• game-id: kebab-case identifier (e.g. fox-and-geese)
• Display Name: human-readable title (e.g. Fox & Geese)
• emoji: single emoji for the game picker (e.g. 🦊)

If any argument is missing, ask the user before proceeding.

Step 0: Understand the game

Before writing any code, if the game rules are not obvious or well-known, ask the user to describe:

1. Board layout and number of positions
2. Number of pieces per player
3. Dice mechanic (or whether it's dice-free — use rollDice() returning 1 always)
4. Win condition
5. Any special squares, captures, or multi-phase mechanics

---

COMMIT 1: Engine & Shared Types

This commit adds the game engine and all shared type changes. No frontend changes.

Step 1: Shared types — add GameType and GameManifest entry

Edit shared/types/game.ts:

1a. Add to the GameType union:

export type GameType = ... | 'GAME_ID';

1b. Add entry to GAME_MANIFESTS:

'GAME_ID': {
  type: 'GAME_ID',
  title: 'DISPLAY NAME',
  emoji: 'EMOJI',
  description: '2 players',  // or appropriate description
  playerColors: ['#COLOR1', '#COLOR2'],  // choose distinct colors for each player
  supportsHistory: true,      // set true if the game has a move log
  // supportsAnimation: true, // only if implementing piece animation
  // disabled: true,          // if not yet playable
  // aiGenerated: true,       // if AI-designed game
},

The manifest drives: Home.tsx game picker, MoveLog player colors, title display everywhere, and animation gating. No manual changes to those files needed.

Step 2: Backend — create the game engine

Create backend/src/games/GAME_ID/GAMECLASSGame.ts:

import { GameEngine } from '../GameEngine';
import { BoardState, Move, Player, PiecePosition } from '@ancient-games/shared';

export class GAMECLASSGame extends GameEngine {
  gameType = 'GAME_ID' as const;
  playerCount = 2;

  private readonly PIECES_PER_PLAYER = N;

  initializeBoard(): BoardState {
    const pieces: PiecePosition[] = [];
    for (let player = 0; player < 2; player++) {
      for (let i = 0; i < this.PIECES_PER_PLAYER; i++) {
        pieces.push({ playerNumber: player, pieceIndex: i, position: -1 });
      }
    }
    return {
      pieces,
      currentTurn: Math.floor(Math.random() * 2),
      diceRoll: null,
      lastMove: null,
    };
  }

  rollDice(): number {
    // Standard d6: return Math.ceil(Math.random() * 6);
    // Binary dice (0–4): sum of 4 coin flips
    // No dice (Morris-style): return 1;
    return Math.ceil(Math.random() * 6);
  }

  validateMove(board: BoardState, move: Move, player: Player): boolean {
    const piece = board.pieces.find(
      (p) => p.playerNumber === player.playerNumber && p.pieceIndex === move.pieceIndex,
    );
    if (!piece) return false;
    if (board.diceRoll === null) return false;
    // TODO: implement game-specific validation
    return false;
  }

  applyMove(board: BoardState, move: Move): BoardState {
    const newPieces = board.pieces.map((p) => ({ ...p }));
    const pieceIdx = newPieces.findIndex(
      (p) => p.playerNumber === board.currentTurn && p.pieceIndex === move.pieceIndex,
    );
    if (pieceIdx === -1) return board;

    newPieces[pieceIdx] = { ...newPieces[pieceIdx], position: move.to };

    // IMPORTANT: applyMove must always:
    //   1. Advance currentTurn (unless extra-turn rule applies)
    //   2. Set diceRoll: null
    const extraTurn = false;
    return {
      ...board,
      pieces: newPieces,
      currentTurn: extraTurn ? board.currentTurn : (board.currentTurn + 1) % 2,
      diceRoll: null,
      lastMove: move,
    };
  }

  checkWinCondition(board: BoardState): number | null {
    for (let playerNumber = 0; playerNumber < 2; playerNumber++) {
      const playerPieces = board.pieces.filter((p) => p.playerNumber === playerNumber);
      if (playerPieces.every((p) => p.position === 99)) return playerNumber;
    }
    return null;
  }

  getValidMoves(board: BoardState, playerNumber: number, diceRoll: number): Move[] {
    const moves: Move[] = [];
    const playerPieces = board.pieces.filter(
      (p) => p.playerNumber === playerNumber && p.position !== 99,
    );
    for (const piece of playerPieces) {
      // TODO: compute legal destinations from piece.position + diceRoll
    }
    return moves;
  }

  canMove(board: BoardState, playerNumber: number, diceRoll: number): boolean {
    return this.getValidMoves(board, playerNumber, diceRoll).length > 0;
  }

  isCaptureMove(board: BoardState, move: Move): boolean {
    // Return true if this move captures an opponent piece by landing on it.
    // Return false if game has no capture-by-landing mechanic (e.g. Morris).
    return false;
  }
}

Key rules for applyMove:

• Always set diceRoll: null — the server checks this to know a move was applied
• Always advance currentTurn to (currentTurn + 1) % 2, unless the game has an extra-turn mechanic
• Return a new BoardState object (spread ...board, then override fields) — never mutate in place

Step 2b: Backend — add to Mongoose schema enum

Edit backend/src/models/Session.ts. The gameType field has a hardcoded enum that MongoDB validates against — if you skip this step, session creation will fail with "not a valid enum value":

gameType: { type: String, enum: [..., 'GAME_ID'], required: true },

Step 3: Backend — register in GameRegistry

Edit backend/src/games/GameRegistry.ts:

import { GAMECLASSGame } from './GAME_ID/GAMECLASSGame';
// Add to the Map:
['GAME_ID', new GAMECLASSGame() as GameEngine],

Step 3b: Backend — write game engine tests

Create backend/src/games/GAME_ID/GAMECLASSGame.test.ts (colocated with the engine):

import { describe, it, expect } from 'vitest';
import { GAMECLASSGame } from './GAMECLASSGame';
import { Move, Player } from '@ancient-games/shared';

const game = new GAMECLASSGame();

function makePlayer(playerNumber: number): Player {
  return { id: 'p', displayName: 'P', socketId: 's', ready: true, playerNumber, status: 'active' };
}

describe('GAMECLASSGame', () => {
  describe('initializeBoard', () => {
    it('creates the correct number of pieces', () => {
      const board = game.initializeBoard();
      expect(board.pieces).toHaveLength(EXPECTED_TOTAL);
      expect(board.pieces.filter((p) => p.playerNumber === 0)).toHaveLength(EXPECTED_PER_PLAYER);
    });

    it('starts with null diceRoll', () => {
      expect(game.initializeBoard().diceRoll).toBeNull();
    });

    it('currentTurn is 0 or 1', () => {
      expect([0, 1]).toContain(game.initializeBoard().currentTurn);
    });
  });

  describe('rollDice', () => {
    it('returns values within expected range', () => {
      const results = new Set<number>();
      for (let i = 0; i < 200; i++) results.add(game.rollDice());
      expect(Math.min(...results)).toBeGreaterThanOrEqual(MIN_ROLL);
      expect(Math.max(...results)).toBeLessThanOrEqual(MAX_ROLL);
    });
  });

  describe('validateMove', () => {
    it('rejects move when diceRoll is null', () => {
      const board = game.initializeBoard();
      const move: Move = { playerId: '', pieceIndex: 0, from: -1, to: 0 };
      expect(game.validateMove(board, move, makePlayer(board.currentTurn))).toBe(false);
    });
    // TODO: add game-specific validation tests
  });

  describe('applyMove', () => {
    // TODO: test piece movement, diceRoll cleared, currentTurn advances, captures
  });

  describe('checkWinCondition', () => {
    it('returns null at game start', () => {
      expect(game.checkWinCondition(game.initializeBoard())).toBeNull();
    });
    // TODO: test win detection
  });

  describe('getValidMoves', () => {
    it('returns moves from initial position', () => {
      const board = game.initializeBoard();
      board.diceRoll = TYPICAL_ROLL;
      const moves = game.getValidMoves(board, board.currentTurn, TYPICAL_ROLL);
      expect(moves.length).toBeGreaterThan(0);
    });
  });
});

Replace EXPECTED_TOTAL, EXPECTED_PER_PLAYER, MIN_ROLL, MAX_ROLL, TYPICAL_ROLL with actual values. Fill in all TODO sections with concrete tests.

Step 3c: Verify and commit

npm run build --workspace=shared
npm run build --workspace=backend
npm test  # or: cd backend && npx vitest run

Commit message: feat: add DISPLAY NAME game engine

This commit touches: shared/types/game.ts, backend/src/games/GAME_ID/, backend/src/games/GameRegistry.ts, backend/src/models/Session.ts

---

COMMIT 2: Game-Specific Frontend Resources

This commit adds all frontend pieces. It should NOT modify any shared platform files (GameRoom.tsx board dispatch, Home.tsx, GameControls.tsx dispatcher, etc.) — only add new files to the game folder and register in lookup records.

Step 4: Frontend — create the board component

Create frontend/src/components/games/GAME_ID/GAMECLASSBoard.tsx:

import { Session, GameState } from '@ancient-games/shared';
import { socketService } from '../../../services/socket';

interface GAMECLASSBoardProps {
  session: Session;
  gameState: GameState;
  playerId: string;
  isMyTurn: boolean;
  animatingPiece?: { playerNumber: number; pieceIndex: number } | null;
}

export default function GAMECLASSBoard({
  session,
  gameState,
  playerId,
  isMyTurn,
}: GAMECLASSBoardProps) {
  const { board } = gameState;

  function handleRollDice() {
    if (!isMyTurn || board.diceRoll !== null) return;
    socketService.getSocket()?.emit('game:roll-dice', {
      sessionCode: session.sessionCode,
      playerId,
    });
  }

  function handleMove(pieceIndex: number, from: number, to: number) {
    if (!isMyTurn || board.diceRoll === null) return;
    socketService.getSocket()?.emit('game:move', {
      sessionCode: session.sessionCode,
      playerId,
      move: { playerId, pieceIndex, from, to, diceRoll: board.diceRoll },
    });
  }

  // TODO: render the board, pieces, and controls
  return (
    <div className="flex flex-col items-center gap-4 p-4">
      {isMyTurn && board.diceRoll === null && !gameState.finished && (
        <button onClick={handleRollDice} className="btn btn-primary px-6 py-3 text-lg font-semibold">
          Roll Dice
        </button>
      )}
      {board.diceRoll !== null && (
        <div className="text-2xl font-bold" style={{ color: '#E8C870' }}>
          Roll: {board.diceRoll}
        </div>
      )}
      <div className="text-gray-400 text-sm">[Board rendering not yet implemented]</div>
    </div>
  );
}

Board rendering notes:

• Use SVG or CSS grid — look at UrBoard.tsx for SVG patterns, MorrisBoard.tsx for grid patterns
• SVG must be responsive on mobile: Use viewBox attribute and width="100%" with style={{ maxWidth: SVG_W }} instead of fixed width={SVG_W}. This ensures the board scales down on narrow viewports while staying centered via parent items-center flex layout.

  const SVG_W = 412; // your computed width
  <svg viewBox={`0 0 ${SVG_W} ${SVG_H}`} width="100%" style={{ maxWidth: SVG_W, ... }}>
  

• Pieces are in board.pieces, filtered by playerNumber and position
• Use session.sessionCode (not session.code) when emitting socket events
• game:move requires top-level playerId in the payload

Step 5: Frontend — create rules component

Create frontend/src/components/games/GAME_ID/GAMECLASSRules.tsx:

import { Section } from '../../GameRules';

export default function GAMECLASSRules() {
  return (
    <>
      <div className="text-center pb-1">
        <div className="text-2xl mb-1">EMOJI</div>
        <p className="font-bold" style={{ color: '#F0D090' }}>
          DISPLAY NAME
        </p>
        <p className="text-xs mt-1" style={{ color: '#7A6A50' }}>
          Brief description
        </p>
      </div>
      <Section title="Objective">How to win.</Section>
      <Section title="Movement">How pieces move.</Section>
      <Section title="Special Rules">Any special mechanics.</Section>
    </>
  );
}

Step 5b: Frontend — export a piece preview component

Export a <GAMECLASSPiecePreview> component from the board file:

// In GAMECLASSBoard.tsx, add near the top (after imports, before the default export):
export function GAMECLASSPiecePreview({ playerNumber, size = 20 }: { playerNumber: 0 | 1; size?: number }) {
  // Render a small SVG of the player's piece at the given size.
  // Player 0 gets their piece, Player 1 gets theirs.
  // If the game has no persistent piece identity (e.g. RPS), return null.
  const color = playerNumber === 0 ? '#PLAYER0_COLOR' : '#PLAYER1_COLOR';
  return (
    <svg viewBox="0 0 20 20" width={size} height={size}>
      <circle cx="10" cy="10" r="8" fill={color} />
    </svg>
  );
}

Then register it in frontend/src/components/games/GamePiecePreview.tsx — add a case 'GAME_ID': to the switch statement:

case 'GAME_ID':
  return <GAMECLASSPiecePreview playerNumber={playerNumber} size={size} />;

And add the import at the top of GamePiecePreview.tsx:

import { GAMECLASSPiecePreview } from './GAME_ID/GAMECLASSBoard';

Step 6: Frontend — create score info (optional)

Create frontend/src/components/games/GAME_ID/gameIdScoreInfo.ts if the game has meaningful score display:

import { PiecePosition } from '@ancient-games/shared';

export function getScoreInfo(pieces: PiecePosition[], seatIndex: number): string | null {
  const finished = pieces.filter((p) => p.playerNumber === seatIndex && p.position === 99).length;
  const onBoard = pieces.filter(
    (p) => p.playerNumber === seatIndex && p.position >= 0 && p.position < 99,
  ).length;
  return `${onBoard} on board \u00B7 ${finished} finished`;
}

Step 7: Frontend — create controls (optional)

Create frontend/src/components/games/GAME_ID/GAMECLASSControls.tsx if the game needs custom dice/controls UI beyond what the board component provides. Import GameControlsProps from ../../GameControls.

Step 8: Register in frontend lookup records

These are the only shared files that need editing — adding entries to lookup records:

8a. frontend/src/components/GameRoom.tsx — add to boardComponents record:

'GAME_ID': lazy(() => import('./games/GAME_ID/GAMECLASSBoard')),

8b. frontend/src/components/GameRules.tsx — add to rulesComponents record:

'GAME_ID': lazy(() => import('./games/GAME_ID/GAMECLASSRules')),

8c. frontend/src/utils/gameScoreInfo.ts — add import and registry entry (if score info created):

import { getScoreInfo as gameIdScore } from '../components/games/GAME_ID/gameIdScoreInfo';
// In registry:
'GAME_ID': gameIdScore,

8d. frontend/src/components/GameControls.tsx — add to controlComponents record (if controls created):

'GAME_ID': lazy(() => import('./games/GAME_ID/GAMECLASSControls')),

8e. frontend/src/components/lobby/SessionLobby.tsx — replace GAME_NAMES usage with getGameTitle:

Note: SessionLobby still has a local GAME_NAMES record. Replace it with getGameTitle from @ancient-games/shared, or add the new entry to the existing record until that cleanup is done:

GAME_ID: 'DISPLAY NAME',

Step 8f: Verify and commit

npm run build
npm run lint 2>&1 | head -20  # fix errors if any

Commit message: feat: add DISPLAY NAME frontend (board, rules, controls)

---

Files NOT touched when adding a game

Thanks to the manifest and registry architecture, these files need no changes:

• Home.tsx — reads from GAME_MANIFESTS automatically
• MoveLog.tsx — reads player colors from manifest
• gameHandlers.ts — uses GameRegistry and engine methods (including isCaptureMove)
• AnimationOverlay.tsx — only activated for games with supportsAnimation: true

Common pitfalls

1. applyMove must set diceRoll: null — the server checks this to know a move was applied
2. applyMove must advance currentTurn — or the same player moves forever
3. validateMove reads board.diceRoll, not the move's diceRoll — the server stores the roll on board before calling validate
4. Position 99 = finished, not "captured" — filter !== 99 when computing available pieces
5. Morris exception: diceRoll is repurposed as a phase indicator. Only do this if your game needs multi-phase turns.
6. Mongoose enum must be updated — backend/src/models/Session.ts has a separate hardcoded enum array. MongoDB will reject session creation with "not a valid enum value" until this is updated.
7. session.sessionCode not session.code — use session.sessionCode in socket events
8. game:move requires top-level playerId — payload is { sessionCode, playerId, move }
9. isCaptureMove must be implemented — even if just returning false. The server calls this on every move to determine capture status.
10. SVG board must use viewBox + responsive width — Don't use fixed width={SVG_W}. Instead use viewBox={0 0 ${SVG_W} ${SVG_H}} with width="100%" and style={{ maxWidth: SVG_W, ... }}. This ensures the board centers on mobile and scales properly without horizontal overflow.

Checklist

After implementing, verify:

Commit 1 (Engine):

• [ ] shared/types/game.ts — GameType union updated
• [ ] shared/types/game.ts — GAME_MANIFESTS entry added (with title, emoji, description, colors)
• [ ] backend/src/models/Session.ts — Mongoose gameType enum updated
• [ ] backend/src/games/GAME_ID/GAMECLASSGame.ts — engine created with isCaptureMove
• [ ] backend/src/games/GameRegistry.ts — engine registered
• [ ] backend/src/games/GAME_ID/GAMECLASSGame.test.ts — tests written and passing

Commit 2 (Frontend):

• [ ] frontend/src/components/games/GAME_ID/GAMECLASSBoard.tsx — board created (default export)
• [ ] frontend/src/components/games/GAME_ID/GAMECLASSBoard.tsx — GAMECLASSPiecePreview exported
• [ ] frontend/src/components/games/GamePiecePreview.tsx — new game registered in switch
• [ ] frontend/src/components/games/GAME_ID/GAMECLASSRules.tsx — rules created (default export)
• [ ] frontend/src/components/games/GAME_ID/gameIdScoreInfo.ts — score info (if applicable)
• [ ] frontend/src/components/games/GAME_ID/GAMECLASSControls.tsx — controls (if applicable)
• [ ] GameRoom.tsx — boardComponents record entry added
• [ ] GameRules.tsx — rulesComponents record entry added
• [ ] gameScoreInfo.ts — registry entry added (if applicable)
• [ ] GameControls.tsx — controlComponents record entry added (if applicable)
• [ ] SessionLobby.tsx — GAME_NAMES entry added
• [ ] npm run build passes with no TypeScript errors