@trolleroof/tui 0.2.4 → 0.2.6

package/src/games/registry.ts

@@ -0,0 +1,130 @@
+import type { Game, GameVariation } from "../core/game.js";
+import { Connect4Game } from "./connect4/connect4.js";
+import { Game2048 } from "./g2048/game2048.js";
+import { MinesweeperGame } from "./minesweeper/minesweeper.js";
+import { SnakeGame } from "./snake/snake.js";
+import { SokobanGame } from "./sokoban/sokoban.js";
+import { SudokuGame } from "./sudoku/sudoku.js";
+import { TetrisGame } from "./tetris/tetris.js";
+
+/**
+ * Central game registry. The menu, the CLI (`gamepigeon <id>`), and any
+ * future launcher all read from here — adding a game is one entry.
+ * Entries without a factory show up as "coming soon" and can't be launched.
+ */
+
+/** What the TUI shell needs beyond the core gym-style contract. */
+export interface PlayableGame extends Game<unknown, string> {
+  isOver(): boolean;
+  hasWon(): boolean;
+  /**
+   * Auto-advance interval in ms. Games that implement this must accept a
+   * "tick" action; the shell steps it on this cadence (Tetris gravity,
+   * Snake movement).
+   */
+  tickMs?(): number;
+  /**
+   * Optional key → action translation so action ids can stay semantic
+   * ("reveal") while keys stay generic ("space"). Keys are logical key
+   * names, single lowercase chars, or "space".
+   */
+  readonly keymap?: Readonly<Record<string, string>>;
+  /** Full engine state for privileged replay checkpoints, when it exceeds the visible state. */
+  checkpointState?(): unknown;
+}
+
+export interface GameEntry {
+  /** Stable id used for CLI launch (`gamepigeon 2048`) and lookups. */
+  id: string;
+  /** Version of the game rules/state contract captured in recordings. */
+  version: string;
+  title: string;
+  /** One-liner shown next to the title in the menu. */
+  description: string;
+  /** Null while the game is still in development ("coming soon"). */
+  create: ((variationId?: string) => PlayableGame) | null;
+  variations: readonly GameVariation[];
+}
+
+const CLASSIC_VARIATION: GameVariation = {
+  id: "classic",
+  title: "Standard",
+  description: "Standard rules.",
+  goal: "Standard rules",
+};
+
+/** Launch trio — shown first in the arcade menu; everything else stays below. */
+export const FEATURED_GAME_IDS = ["2048", "tetris", "minesweeper"] as const;
+
+export const REGISTRY: readonly GameEntry[] = [
+  {
+    id: "2048",
+    version: "1",
+    title: "2048",
+    description: "Merge tiles to reach 2048.",
+    create: (variationId) => new Game2048(variationId),
+    variations: Game2048.VARIATIONS,
+  },
+  {
+    id: "tetris",
+    version: "1",
+    title: "Tetris",
+    description: "Clear lines with falling blocks.",
+    create: (variationId) => new TetrisGame(variationId),
+    variations: TetrisGame.VARIATIONS,
+  },
+  {
+    id: "minesweeper",
+    version: "1",
+    title: "Minesweeper",
+    description: "Clear the field, avoid the mines.",
+    create: () => new MinesweeperGame(),
+    variations: [CLASSIC_VARIATION],
+  },
+  {
+    id: "snake",
+    version: "1",
+    title: "Snake",
+    description: "Eat, grow, don't crash.",
+    create: () => new SnakeGame(),
+    variations: [CLASSIC_VARIATION],
+  },
+  {
+    id: "sokoban",
+    version: "1",
+    title: "Sokoban",
+    description: "Push crates onto goals.",
+    create: () => new SokobanGame(),
+    variations: [CLASSIC_VARIATION],
+  },
+  {
+    id: "connect4",
+    version: "1",
+    title: "Connect Four",
+    description: "Line up four before the bot.",
+    create: () => new Connect4Game(),
+    variations: [CLASSIC_VARIATION],
+  },
+  {
+    id: "sudoku",
+    version: "1",
+    title: "Sudoku",
+    description: "Fill every row, column, and box 1–9.",
+    create: () => new SudokuGame(),
+    variations: [CLASSIC_VARIATION],
+  },
+];
+
+export function isPlayable(entry: GameEntry): boolean {
+  return entry.create !== null;
+}
+
+/** Case-insensitive lookup by registry id. */
+export function findGame(id: string): GameEntry | undefined {
+  const norm = id.trim().toLowerCase();
+  return REGISTRY.find((e) => e.id === norm);
+}
+
+export function playableGames(): GameEntry[] {
+  return REGISTRY.filter(isPlayable);
+}

package/src/games/snake/engine.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "bun:test";
+import { Rng } from "../../core/rng.js";
+import { HEIGHT, WIDTH, newSnake, opposite, placeFood, tick } from "./engine.js";
+import { SnakeGame } from "./snake.js";
+
+describe("snake engine", () => {
+  it("starts alive, length 3, heading right", () => {
+    const s = newSnake(new Rng(1));
+    expect(s.alive).toBe(true);
+    expect(s.snake).toHaveLength(3);
+    expect(s.dir).toBe("right");
+  });
+
+  it("never places food on the snake", () => {
+    const rng = new Rng(7);
+    const s = newSnake(rng);
+    for (let i = 0; i < 50; i++) {
+      const f = placeFood(s, rng);
+      expect(s.snake.some((p) => p.x === f.x && p.y === f.y)).toBe(false);
+    }
+  });
+
+  it("grows and scores when eating", () => {
+    const rng = new Rng(1);
+    const s = newSnake(rng);
+    s.food = { x: s.snake[0]!.x + 1, y: s.snake[0]!.y };
+    const res = tick(s, rng);
+    expect(res.ate).toBe(true);
+    expect(s.score).toBe(1);
+    expect(s.snake).toHaveLength(4);
+  });
+
+  it("dies on the wall", () => {
+    const rng = new Rng(1);
+    const s = newSnake(rng);
+    let died = false;
+    for (let i = 0; i < WIDTH + 2 && !died; i++) died = tick(s, rng).died;
+    expect(died).toBe(true);
+    expect(s.alive).toBe(false);
+  });
+
+  it("opposite is symmetric", () => {
+    for (const d of ["up", "down", "left", "right"] as const) {
+      expect(opposite(opposite(d))).toBe(d);
+    }
+  });
+});
+
+describe("SnakeGame", () => {
+  it("reports the next food position when food is eaten", () => {
+    const g = new SnakeGame();
+    g.reset(42);
+    const state = g.state();
+    state.food = { x: state.snake[0]!.x + 1, y: state.snake[0]!.y };
+    (g as unknown as { st: typeof state }).st = state;
+    expect(g.step("tick").randomEffects).toMatchObject({
+      kind: "food_spawned",
+      position: { x: expect.any(Number), y: expect.any(Number) },
+    });
+  });
+
+  it("ignores reversal, accepts turns, and dies deterministically per seed", () => {
+    const g = new SnakeGame();
+    g.reset(42);
+    expect(g.step("left").moved).toBe(false); // reverse of initial "right"
+    expect(g.step("up").moved).toBe(true);
+    let steps = 0;
+    while (!g.isOver() && steps < WIDTH * HEIGHT * 4) {
+      g.step("tick");
+      steps++;
+    }
+    expect(g.isOver()).toBe(true);
+  });
+
+  it("prevents double-turn self-collision crash", () => {
+    const g = new SnakeGame();
+    g.reset(42);
+    // Heading right. Pressing "up" (legal turn) then "left" (opposite of "right") before tick.
+    expect(g.step("up").moved).toBe(true);
+    expect(g.step("left").moved).toBe(false); // Should be ignored because it is opposite to last movement dir ("right")
+    
+    // Check that state dir remains "up"
+    expect(g.state().dir).toBe("up");
+
+    // After tick, the snake should successfully move up and stay alive
+    expect(g.step("tick").done).toBe(false);
+    expect(g.isOver()).toBe(false);
+  });
+});

package/src/games/snake/engine.ts

@@ -0,0 +1,95 @@
+import type { Rng } from "../../core/rng.js";
+
+/**
+ * Pure snake rules: a head-first body on a walled grid, one food at a time.
+ * The shell drives movement with "tick" actions on a fixed cadence.
+ */
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type Dir = "up" | "down" | "left" | "right";
+
+export interface SnakeState {
+  width: number;
+  height: number;
+  /** Head first. */
+  snake: Point[];
+  dir: Dir;
+  food: Point;
+  score: number;
+  alive: boolean;
+}
+
+export const WIDTH = 20;
+export const HEIGHT = 13;
+/** Eat this many foods to "win" the episode (play continues after). */
+export const WIN_SCORE = 25;
+
+const DELTA: Record<Dir, Point> = {
+  up: { x: 0, y: -1 },
+  down: { x: 0, y: 1 },
+  left: { x: -1, y: 0 },
+  right: { x: 1, y: 0 },
+};
+
+export function opposite(dir: Dir): Dir {
+  return dir === "up" ? "down" : dir === "down" ? "up" : dir === "left" ? "right" : "left";
+}
+
+export function newSnake(rng: Rng): SnakeState {
+  const cy = Math.floor(HEIGHT / 2);
+  const cx = Math.floor(WIDTH / 2);
+  const snake = [
+    { x: cx, y: cy },
+    { x: cx - 1, y: cy },
+    { x: cx - 2, y: cy },
+  ];
+  const state: SnakeState = { width: WIDTH, height: HEIGHT, snake, dir: "right", food: { x: 0, y: 0 }, score: 0, alive: true };
+  state.food = placeFood(state, rng);
+  return state;
+}
+
+/** Random empty cell for the next food. */
+export function placeFood(state: SnakeState, rng: Rng): Point {
+  const taken = new Set(state.snake.map((p) => `${p.x},${p.y}`));
+  const free: Point[] = [];
+  for (let y = 0; y < state.height; y++) {
+    for (let x = 0; x < state.width; x++) {
+      if (!taken.has(`${x},${y}`)) free.push({ x, y });
+    }
+  }
+  return free[rng.int(free.length)] ?? { x: 0, y: 0 };
+}
+
+export interface TickResult {
+  ate: boolean;
+  died: boolean;
+}
+
+/** Advance one cell in the current direction, mutating `state`. */
+export function tick(state: SnakeState, rng: Rng): TickResult {
+  if (!state.alive) return { ate: false, died: false };
+  const head = state.snake[0]!;
+  const d = DELTA[state.dir];
+  const next = { x: head.x + d.x, y: head.y + d.y };
+
+  const hitWall = next.x < 0 || next.y < 0 || next.x >= state.width || next.y >= state.height;
+  // Tail cell frees up this tick unless we grow into it by eating.
+  const ate = next.x === state.food.x && next.y === state.food.y;
+  const body = ate ? state.snake : state.snake.slice(0, -1);
+  const hitSelf = body.some((p) => p.x === next.x && p.y === next.y);
+  if (hitWall || hitSelf) {
+    state.alive = false;
+    return { ate: false, died: true };
+  }
+
+  state.snake = [next, ...body];
+  if (ate) {
+    state.score += 1;
+    state.food = placeFood(state, rng);
+  }
+  return { ate, died: false };
+}

package/src/games/snake/snake.ts

@@ -0,0 +1,77 @@
+import type { Game, StepResult } from "../../core/game.js";
+import { Rng } from "../../core/rng.js";
+import { WIN_SCORE, newSnake, opposite, tick, type Dir, type SnakeState } from "./engine.js";
+
+export type SnakeAction = Dir | "tick";
+
+function getLastMovementDir(snake: Array<{ x: number; y: number }>): Dir | null {
+  if (snake.length < 2) return null;
+  const head = snake[0]!;
+  const neck = snake[1]!;
+  if (head.x > neck.x) return "right";
+  if (head.x < neck.x) return "left";
+  if (head.y > neck.y) return "down";
+  if (head.y < neck.y) return "up";
+  return null;
+}
+
+export class SnakeGame implements Game<SnakeState, SnakeAction> {
+  readonly name = "snake";
+  readonly actions = ["up", "down", "left", "right", "tick"] as const;
+
+  private rng = new Rng(0);
+  private st: SnakeState = newSnake(this.rng);
+  private won = false;
+
+  reset(seed: number): void {
+    this.rng = new Rng(seed);
+    this.st = newSnake(this.rng);
+    this.won = false;
+  }
+
+  tickMs(): number {
+    return Math.max(70, 150 - this.st.score * 4);
+  }
+
+  step(action: SnakeAction): StepResult {
+    if (!this.st.alive) return { reward: 0, moved: false, done: true, success: this.won };
+    if (action !== "tick") {
+      // Reversing into yourself is never legal; ignore it instead of dying.
+      // We check against both the current dir and the last actual movement direction to prevent double-turn self-collision.
+      const lastMoveDir = getLastMovementDir(this.st.snake);
+      const isOppositeToLastMove = lastMoveDir && action === opposite(lastMoveDir);
+      if (action === this.st.dir || action === opposite(this.st.dir) || isOppositeToLastMove) {
+        return { reward: 0, moved: false, done: false, success: this.won };
+      }
+      this.st.dir = action;
+      return { reward: 0, moved: true, done: false, success: this.won };
+    }
+    const res = tick(this.st, this.rng);
+    if (res.ate && this.st.score >= WIN_SCORE) this.won = true;
+    return {
+      reward: res.ate ? 1 : 0,
+      moved: true,
+      done: !this.st.alive,
+      success: this.won,
+      ...(res.ate
+        ? { randomEffects: { kind: "food_spawned", position: { ...this.st.food } } }
+        : {}),
+    };
+  }
+
+  state(): SnakeState {
+    return { ...this.st, snake: this.st.snake.map((p) => ({ ...p })), food: { ...this.st.food } };
+  }
+
+  score(): number {
+    return this.st.score;
+  }
+
+  isOver(): boolean {
+    return !this.st.alive;
+  }
+
+  hasWon(): boolean {
+    return this.won;
+  }
+}

package/src/games/sokoban/engine.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "bun:test";
+import { LEVELS, isSolvedLevel, move, parseLevel, solvable } from "./engine.js";
+import { SokobanGame } from "./sokoban.js";
+
+describe("sokoban engine", () => {
+  it("every packed level is solvable (BFS proof)", () => {
+    for (const level of LEVELS) {
+      expect(solvable(level)).toBe(true);
+    }
+  });
+
+  it("walking, pushing, and blocked pushes behave", () => {
+    const l = parseLevel(["#####", "#@$.#", "#####"]);
+    const res = move(l, "right");
+    expect(res.moved).toBe(true);
+    expect(res.pushed).toBe(true);
+    expect(isSolvedLevel(l)).toBe(true);
+    // Box now sits against the wall; pushing further is illegal.
+    expect(move(l, "right").moved).toBe(false);
+  });
+
+  it("cannot push two boxes at once", () => {
+    const l = parseLevel(["######", "#@$$.#", "######"]);
+    expect(move(l, "right").moved).toBe(false);
+  });
+});
+
+describe("SokobanGame", () => {
+  it("solving level 1 advances to level 2 and pays the level reward", () => {
+    const g = new SokobanGame();
+    g.reset(0);
+    const res = g.step("right");
+    expect(res.reward).toBe(100);
+    expect(res.done).toBe(false);
+    expect(g.state().level).toBe(1);
+    expect(g.score()).toBe(100);
+  });
+
+  it("undo restores the previous position", () => {
+    const g = new SokobanGame();
+    g.reset(0);
+    g.step("right"); // now on level 2
+    const before = g.state();
+    g.step("up");
+    g.step("undo");
+    expect(g.state().player).toEqual(before.player);
+    expect(g.state().boxes).toEqual(before.boxes);
+  });
+});

package/src/games/sokoban/engine.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure Sokoban rules plus a small built-in level pack. Levels use the
+ * classic text format: # wall, @ player, $ box, . goal, * box-on-goal,
+ * + player-on-goal, space floor. Solvability of every level is asserted
+ * by a BFS solver in the tests.
+ */
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type Dir = "up" | "down" | "left" | "right";
+
+export interface Level {
+  width: number;
+  height: number;
+  walls: Set<string>;
+  goals: Set<string>;
+  boxes: Set<string>;
+  player: Point;
+}
+
+export const LEVELS: readonly string[][] = [
+  [
+    "#####",
+    "#@$.#",
+    "#####",
+  ],
+  [
+    "######",
+    "#    #",
+    "# $$ #",
+    "# .. #",
+    "#@   #",
+    "######",
+  ],
+  [
+    "#######",
+    "#     #",
+    "# .$@ #",
+    "# .$  #",
+    "#  #  #",
+    "#######",
+  ],
+  [
+    "#######",
+    "#  .  #",
+    "#  $  #",
+    "#@ $ .#",
+    "#     #",
+    "#######",
+  ],
+  [
+    "########",
+    "# .  . #",
+    "# $  $ #",
+    "#  @   #",
+    "########",
+  ],
+];
+
+const key = (x: number, y: number): string => `${x},${y}`;
+
+export function parseLevel(rows: readonly string[]): Level {
+  const walls = new Set<string>();
+  const goals = new Set<string>();
+  const boxes = new Set<string>();
+  let player: Point = { x: 0, y: 0 };
+  rows.forEach((row, y) => {
+    [...row].forEach((ch, x) => {
+      if (ch === "#") walls.add(key(x, y));
+      if (ch === "." || ch === "*" || ch === "+") goals.add(key(x, y));
+      if (ch === "$" || ch === "*") boxes.add(key(x, y));
+      if (ch === "@" || ch === "+") player = { x, y };
+    });
+  });
+  return { width: Math.max(...rows.map((r) => r.length)), height: rows.length, walls, goals, boxes, player };
+}
+
+const DELTA: Record<Dir, Point> = {
+  up: { x: 0, y: -1 },
+  down: { x: 0, y: 1 },
+  left: { x: -1, y: 0 },
+  right: { x: 1, y: 0 },
+};
+
+export interface MoveResult {
+  moved: boolean;
+  pushed: boolean;
+}
+
+/** Walk/push one step, mutating the level. */
+export function move(level: Level, dir: Dir): MoveResult {
+  const d = DELTA[dir];
+  const nx = level.player.x + d.x;
+  const ny = level.player.y + d.y;
+  if (level.walls.has(key(nx, ny))) return { moved: false, pushed: false };
+  if (level.boxes.has(key(nx, ny))) {
+    const bx = nx + d.x;
+    const by = ny + d.y;
+    if (level.walls.has(key(bx, by)) || level.boxes.has(key(bx, by))) return { moved: false, pushed: false };
+    level.boxes.delete(key(nx, ny));
+    level.boxes.add(key(bx, by));
+    level.player = { x: nx, y: ny };
+    return { moved: true, pushed: true };
+  }
+  level.player = { x: nx, y: ny };
+  return { moved: true, pushed: false };
+}
+
+export function isSolvedLevel(level: Level): boolean {
+  return [...level.boxes].every((b) => level.goals.has(b));
+}
+
+/** Snapshot for undo. */
+export function snapshot(level: Level): { boxes: string[]; player: Point } {
+  return { boxes: [...level.boxes], player: { ...level.player } };
+}
+
+export function restore(level: Level, snap: { boxes: string[]; player: Point }): void {
+  level.boxes = new Set(snap.boxes);
+  level.player = { ...snap.player };
+}
+
+/**
+ * BFS solver used by tests to guarantee every packed level is solvable.
+ * State space is tiny for the built-in pack.
+ */
+export function solvable(rows: readonly string[], maxStates = 200_000): boolean {
+  const start = parseLevel(rows);
+  const enc = (l: Level): string => `${l.player.x},${l.player.y}|${[...l.boxes].sort().join(";")}`;
+  const seen = new Set([enc(start)]);
+  let frontier = [start];
+  while (frontier.length > 0 && seen.size < maxStates) {
+    const next: Level[] = [];
+    for (const state of frontier) {
+      if (isSolvedLevel(state)) return true;
+      for (const dir of ["up", "down", "left", "right"] as const) {
+        const copy: Level = { ...state, boxes: new Set(state.boxes), player: { ...state.player } };
+        if (!move(copy, dir).moved) continue;
+        const id = enc(copy);
+        if (!seen.has(id)) {
+          seen.add(id);
+          next.push(copy);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return frontier.some(isSolvedLevel);
+}

package/src/games/sokoban/sokoban.ts

@@ -0,0 +1,103 @@
+import type { Game, StepResult } from "../../core/game.js";
+import {
+  LEVELS,
+  isSolvedLevel,
+  move,
+  parseLevel,
+  restore,
+  snapshot,
+  type Dir,
+  type Level,
+} from "./engine.js";
+
+export type SokobanAction = Dir | "undo";
+
+export interface SokobanState {
+  level: number;
+  player: { x: number; y: number };
+  boxes: string[];
+  goals: string[];
+  moves: number;
+  pushes: number;
+}
+
+
+const LEVEL_REWARD = 100;
+
+export class SokobanGame implements Game<SokobanState, SokobanAction> {
+  readonly name = "sokoban";
+  readonly actions = ["up", "down", "left", "right", "undo"] as const;
+  readonly keymap = { z: "undo", u: "undo" } as const;
+
+  private levelIndex = 0;
+  private level: Level = parseLevel(LEVELS[0]!);
+  private history: Array<{ boxes: string[]; player: { x: number; y: number } }> = [];
+  private moves = 0;
+  private pushes = 0;
+  private solvedLevels = 0;
+  private finished = false;
+
+  reset(_seed: number): void {
+    this.levelIndex = 0;
+    this.solvedLevels = 0;
+    this.finished = false;
+    this.loadLevel(0);
+  }
+
+  private loadLevel(index: number): void {
+    this.levelIndex = index;
+    this.level = parseLevel(LEVELS[index]!);
+    this.history = [];
+    this.moves = 0;
+    this.pushes = 0;
+  }
+
+  step(action: SokobanAction): StepResult {
+    if (this.finished) return { reward: 0, moved: false, done: true, success: true };
+    if (action === "undo") {
+      const snap = this.history.pop();
+      if (!snap) return { reward: 0, moved: false, done: false, success: false };
+      restore(this.level, snap);
+      this.moves = Math.max(0, this.moves - 1);
+      return { reward: 0, moved: true, done: false, success: false };
+    }
+    const snap = snapshot(this.level);
+    const res = move(this.level, action);
+    if (!res.moved) return { reward: 0, moved: false, done: false, success: false };
+    this.history.push(snap);
+    this.moves++;
+    if (res.pushed) this.pushes++;
+    if (!isSolvedLevel(this.level)) return { reward: 0, moved: true, done: false, success: false };
+
+    this.solvedLevels++;
+    if (this.levelIndex + 1 >= LEVELS.length) {
+      this.finished = true;
+      return { reward: LEVEL_REWARD, moved: true, done: true, success: true };
+    }
+    this.loadLevel(this.levelIndex + 1);
+    return { reward: LEVEL_REWARD, moved: true, done: false, success: false };
+  }
+
+  state(): SokobanState {
+    return {
+      level: this.levelIndex,
+      player: { ...this.level.player },
+      boxes: [...this.level.boxes].sort(),
+      goals: [...this.level.goals].sort(),
+      moves: this.moves,
+      pushes: this.pushes,
+    };
+  }
+
+  score(): number {
+    return this.solvedLevels * LEVEL_REWARD;
+  }
+
+  isOver(): boolean {
+    return this.finished;
+  }
+
+  hasWon(): boolean {
+    return this.finished;
+  }
+}