terminal-ludo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+<div align="center">
+
+# 🎲 terminal-ludo
+
+**Classic Ludo, right in your terminal.**
+Fully offline · zero dependencies · play against AI or hotseat with friends.
+
+[![npm version](https://img.shields.io/npm/v/terminal-ludo.svg)](https://www.npmjs.com/package/terminal-ludo)
+[![node](https://img.shields.io/badge/node-%E2%89%A514-brightgreen.svg)](https://nodejs.org)
+[![dependencies](https://img.shields.io/badge/dependencies-0-blue.svg)](package.json)
+[![license](https://img.shields.io/badge/license-MIT-informational.svg)](LICENSE)
+
+</div>
+
+```
+npx terminal-ludo
+```
+
+---
+
+## Contents
+
+- [Preview](#preview)
+- [Features](#features)
+- [Install](#install)
+- [How to play](#how-to-play)
+- [Rules](#rules)
+- [Command-line options](#command-line-options)
+- [Saving & resuming](#saving--resuming)
+- [Board legend](#board-legend)
+- [Project structure](#project-structure)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Preview
+
+The board is a colour 15×15 grid. Tokens on the track render as filled coloured
+pills so they are easy to spot; tokens still in the yard sit in their corner.
+
+```
+            · · ·
+  ○   ○     ·   ◈   ○   ○
+            Y   ·
+  R   R     R   ·   G   G
+            ·   ·
+            ·   ·
+· 2 · · · ·       · · · ✦ · ·
+·             ★             ·
+· · ✦ · · ·       · · · · 2 ·
+            ·   ·
+  ○   B     ·   ·   Y   ○
+            ·   ·
+  B   ○     ·   2   ○   Y
+            ◈   ·
+            · · ·
+```
+
+> Actual output is in full colour — red, green, yellow and blue.
+
+## Features
+
+- 🎯 **Full classic rules** — 4 tokens per player, capture, safe squares, home columns, exact-roll finish.
+- 🤖 **Play vs. AI** — 0–4 humans; the rest are computer players.
+- 🎚️ **Three difficulty levels** — `easy`, `normal`, `hard`.
+- 🎨 **Choose your colours** — pick which colours play and which are human.
+- 🎲 **Animated dice roll**.
+- ⌨️ **Single-keypress controls** — press Enter to roll, no typing or Enter-to-confirm.
+- 💾 **Save & resume** — quit anytime, pick up later.
+- 👀 **`--watch` demo** — sit back and watch four AIs battle.
+- 👥 **Hotseat multiplayer** on one machine.
+- 🖥️ **Any ANSI terminal** — honours `NO_COLOR`.
+- 📦 **Zero runtime dependencies** — works anywhere Node ≥ 14 runs, no internet needed.
+
+## Install
+
+Run instantly without installing:
+
+```sh
+npx terminal-ludo
+```
+
+Or install globally for a permanent `ludo` command:
+
+```sh
+npm install -g terminal-ludo
+ludo
+```
+
+**Requirements:** Node.js ≥ 14 and a terminal that supports ANSI colour (virtually all do).
+
+## How to play
+
+Run `ludo` and answer the prompts:
+
+1. **How many players** (2–4).
+2. **Which colours play** — only asked when fewer than 4 are in the game.
+3. **Which colours are human** — a comma-separated list; the rest are AI. Enter `none` for an all-CPU game.
+
+Colours can be given by **name** (`red`), **initial** (`r`), or **number** (`1`).
+For example `red, blue`, `r b`, and `1 4` all pick red and blue.
+
+### Controls
+
+On your turn everything is a **single keypress** — no typing, no Enter-to-confirm:
+
+| Key         | Action                                   |
+|-------------|------------------------------------------|
+| `Enter`     | Roll the dice                            |
+| `1`–`4`     | Move that token (when you have a choice) |
+| any key     | Continue after a turn                    |
+| `s`         | Save the game and quit                   |
+| `q`         | Quit without saving                      |
+
+## Rules
+
+- You need a **6** to move a token out of your yard onto the board.
+- Rolling a **6** — or **capturing** an opponent, or sending a token **home** — earns an **extra turn**.
+- Rolling three **6s** in a row forfeits the turn.
+- Landing on an opponent sends it back to its yard — **except** on a **safe square** (`✦`) or a coloured **start** (`◈`).
+- Tokens must reach home on an **exact** roll; you cannot overshoot.
+- First player to get **all four tokens home** wins. Play continues for the remaining places.
+
+## Command-line options
+
+```
+ludo [options]
+
+  -h, --help                 Show help
+  -w, --watch                Watch four AI players battle it out (no input)
+  -d, --difficulty <level>   AI level: easy | normal | hard   (default: normal)
+  -l, --load <file>          Resume a previously saved game
+```
+
+Examples:
+
+```sh
+ludo                          # interactive game
+ludo -d hard                  # play against a tougher AI
+ludo --watch -d hard          # demo: four hard AIs play themselves
+ludo --load ludo-save.json    # resume a saved game
+```
+
+## Saving & resuming
+
+- Press **`s`** at the roll prompt to save to `ludo-save.json` and quit.
+- Press **`q`** to quit without saving.
+- Pressing **Ctrl-C** mid-game autosaves to `ludo-autosave.json`.
+- Resume any save with `ludo --load <file>`.
+
+## Board legend
+
+| Symbol                | Meaning                                        |
+|-----------------------|------------------------------------------------|
+| `◈`                   | A colour's start square (safe)                 |
+| `✦`                   | Star / safe square                             |
+| `·`                   | Regular track cell                             |
+| `★`                   | Centre goal                                    |
+| filled `R` `G` `Y` `B` pill | A token on the board (red, green, yellow, blue) |
+| number                | Count when several tokens share a cell         |
+| `○` in a yard         | An empty base slot (that token is out on the board) |
+
+## Project structure
+
+```
+terminal-ludo/
+├── bin/
+│   └── ludo.js        # CLI entry point (the `ludo` command)
+├── src/
+│   ├── constants.js   # board geometry: track, home columns, safe squares
+│   ├── game.js        # pure, testable rules engine + save/load
+│   ├── ai.js          # heuristic AI with difficulty levels
+│   ├── render.js      # ANSI board renderer
+│   └── cli.js         # interactive loop, input handling, animation
+└── test/
+    └── game.test.js   # rule-engine tests (no framework, no deps)
+```
+
+The rules live in `src/game.js` as a dependency-free, side-effect-free engine, so
+they can be tested and reused independently of the terminal front-end.
+
+## Development
+
+```sh
+git clone https://github.com/rohan4naik/CLI-Ludo.git
+cd CLI-Ludo
+npm test        # run the rule-engine tests
+npm start       # run the game
+```
+
+There are no build steps and no dependencies to install.
+
+## Contributing
+
+Issues and pull requests are welcome at
+[github.com/rohan4naik/CLI-Ludo](https://github.com/rohan4naik/CLI-Ludo).
+Please run `npm test` before opening a PR.
+
+## License
+
+[MIT](LICENSE)

package/bin/ludo.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "terminal-ludo",
+  "version": "1.0.0",
+  "description": "Classic Ludo board game for your terminal. Offline, zero dependencies, play against AI or hotseat with friends.",
+  "keywords": [
+    "ludo",
+    "game",
+    "board-game",
+    "terminal",
+    "cli",
+    "tui",
+    "offline",
+    "ascii",
+    "dice"
+  ],
+  "license": "MIT",
+  "author": "rohan4naik",
+  "type": "commonjs",
+  "bin": {
+    "ludo": "bin/ludo.js",
+    "terminal-ludo": "bin/ludo.js"
+  },
+  "main": "src/game.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/ludo.js",
+    "test": "node test/game.test.js"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohan4naik/CLI-Ludo.git"
+  },
+  "homepage": "https://github.com/rohan4naik/CLI-Ludo#readme",
+  "bugs": {
+    "url": "https://github.com/rohan4naik/CLI-Ludo/issues"
+  }
+}

package/src/ai.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const { SAFE_INDICES, GOAL_OFFSET, TRACK_LEN } = require('./constants');
+
+// Heuristic AI with three difficulty levels.
+//   easy   - mostly random, ignores threats
+//   normal - full heuristic (default)
+//   hard   - full heuristic with sharper threat/aggression weighting
+function chooseMove(game, color, dice, moves, difficulty = 'normal') {
+  if (moves.length === 0) return null;
+  if (moves.length === 1) return moves[0];
+
+  // Easy players blunder often: 65% of the time they move at random.
+  if (difficulty === 'easy' && Math.random() < 0.65) {
+    return moves[Math.floor(Math.random() * moves.length)];
+  }
+
+  let best = moves[0];
+  let bestScore = -Infinity;
+  for (const move of moves) {
+    const score = scoreMove(game, color, dice, move, difficulty);
+    if (score > bestScore) {
+      bestScore = score;
+      best = move;
+    }
+  }
+  return best;
+}
+
+function scoreMove(game, color, dice, move, difficulty = 'normal') {
+  const hard = difficulty === 'hard';
+  let score = 0;
+
+  // Capturing an opponent is almost always great (more so on hard).
+  const captures = game.capturesFor(color, move.to);
+  score += captures.length * (hard ? 1300 : 1000);
+
+  // Getting a token all the way home.
+  if (move.to === GOAL_OFFSET) score += 800;
+
+  // Bringing a fresh token out of the yard keeps options open.
+  if (move.from < 0) score += 400;
+
+  // Reaching the safety of the home column.
+  if (move.to >= 51 && move.to < GOAL_OFFSET) score += 200;
+
+  // Landing on a safe square.
+  const abs = game.absIndex(color, move.to);
+  if (abs !== null && SAFE_INDICES.has(abs)) score += 120;
+
+  // Prefer progressing tokens that are already advanced.
+  score += move.to * 3;
+
+  // Avoid parking a lone token where an opponent one dice-roll behind could
+  // capture it next turn (only matters on unsafe track squares). Hard players
+  // weigh this danger more heavily.
+  if (abs !== null && !SAFE_INDICES.has(abs) && move.to < GOAL_OFFSET) {
+    if (isThreatened(game, color, abs)) score -= hard ? 260 : 150;
+  }
+
+  return score;
+}
+
+// Is absolute square `abs` reachable by an opponent token within 1..6 steps?
+function isThreatened(game, color, abs) {
+  for (const other of game.colors) {
+    if (other === color) continue;
+    for (const off of game.tokens[other]) {
+      if (off < 0 || off > 50) continue;
+      const oAbs = game.absIndex(other, off);
+      let d = abs - oAbs;
+      if (d < 0) d += TRACK_LEN;
+      if (d >= 1 && d <= 6) return true;
+    }
+  }
+  return false;
+}
+
+module.exports = { chooseMove };

package/src/cli.js

@@ -0,0 +1,467 @@
+'use strict';
+
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+const { Game } = require('./game');
+const { chooseMove } = require('./ai');
+const { render, status, paint, FG, LETTER, BOLD, DIM } = require('./render');
+const { PLAYERS } = require('./constants');
+
+// ---------------------------------------------------------------------------
+// Keypress-based input.
+//
+// We read raw keypresses rather than lines so that prompts like "press Enter
+// to roll" react to a single key with no visible text field / cursor. A tiny
+// line editor (readLine) is layered on top for the few prompts that genuinely
+// need typed text (player counts, colour lists).
+// ---------------------------------------------------------------------------
+const stdin = process.stdin;
+const stdout = process.stdout;
+const IS_TTY = !!stdin.isTTY;
+
+readline.emitKeypressEvents(stdin);
+if (IS_TTY) {
+  try { stdin.setRawMode(true); } catch (_) { /* not a raw-capable TTY */ }
+}
+stdin.resume();
+
+const keyBuffer = [];
+const keyWaiters = [];
+let inputClosed = false;
+
+stdin.on('keypress', (str, key) => {
+  if (key && key.ctrl && key.name === 'c') { onInterrupt(); return; }
+  const ev = { str: str || '', key: key || {} };
+  const w = keyWaiters.shift();
+  if (w) w(ev);
+  else keyBuffer.push(ev);
+});
+stdin.on('end', () => {
+  inputClosed = true;
+  while (keyWaiters.length) keyWaiters.shift()({ str: '', key: { name: 'return' }, eof: true });
+});
+
+function nextKey() {
+  return new Promise((res) => {
+    if (keyBuffer.length) return res(keyBuffer.shift());
+    if (inputClosed) return res({ str: '', key: { name: 'return' }, eof: true });
+    keyWaiters.push(res);
+  });
+}
+
+function isEnter(ev) {
+  const n = ev.key.name;
+  return ev.eof || n === 'return' || n === 'enter' || ev.str === '\r' || ev.str === '\n';
+}
+
+// Wait for a single keypress (optionally after printing a prompt).
+async function readKey(prompt) {
+  if (prompt) stdout.write(prompt);
+  return nextKey();
+}
+
+// Read a line of text, echoing characters when interactive.
+async function readLine(prompt) {
+  if (prompt) stdout.write(prompt);
+  let buf = '';
+  while (true) {
+    const ev = await nextKey();
+    if (isEnter(ev)) {
+      if (IS_TTY) stdout.write('\n');
+      return buf;
+    }
+    if (ev.key.name === 'backspace') {
+      if (buf.length) {
+        buf = buf.slice(0, -1);
+        if (IS_TTY) stdout.write('\b \b');
+      }
+      continue;
+    }
+    const ch = ev.str;
+    if (ch && ch >= ' ') {
+      buf += ch;
+      if (IS_TTY) stdout.write(ch);
+    }
+  }
+}
+const ask = readLine; // typed prompts (counts, colours)
+
+function cleanup() {
+  if (IS_TTY) {
+    try { stdin.setRawMode(false); } catch (_) { /* ignore */ }
+  }
+  stdin.pause();
+}
+// Safety net: never leave the terminal stuck in raw mode, even on a crash.
+process.on('exit', () => {
+  if (IS_TTY) {
+    try { stdin.setRawMode(false); } catch (_) { /* ignore */ }
+  }
+});
+
+const FAST = !!process.env.LUDO_FAST;
+const sleep = (ms) => new Promise((res) => setTimeout(res, FAST ? 0 : ms));
+
+function rollDice() {
+  return 1 + Math.floor(Math.random() * 6);
+}
+
+const DICE_FACES = ['⚀', '⚁', '⚂', '⚃', '⚄', '⚅'];
+const DEFAULT_SAVE = path.join(process.cwd(), 'ludo-save.json');
+
+let currentGame = null; // for autosave on Ctrl-C
+
+function clear() {
+  process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+}
+
+function title() {
+  return paint(BOLD, '  L U D O ') + paint(DIM, ' — terminal edition');
+}
+
+function draw(game, message) {
+  clear();
+  console.log(title());
+  console.log();
+  console.log(render(game));
+  console.log();
+  console.log(status(game));
+  if (game.humans.size > 0) {
+    console.log(paint(DIM, "  (at the roll prompt: 's' saves & quits, 'q' quits)"));
+  }
+  console.log();
+  if (message) console.log(message);
+}
+
+// ---------------------------------------------------------------------------
+// Dice-roll animation (only for a human's own roll; AI just pauses briefly).
+// ---------------------------------------------------------------------------
+async function animateDice(finalDice) {
+  if (FAST) return;
+  const frames = 9;
+  for (let i = 0; i < frames; i++) {
+    const f = 1 + Math.floor(Math.random() * 6);
+    process.stdout.write('\r  🎲 rolling…  ' + paint(BOLD, DICE_FACES[f - 1]) + '   ');
+    await sleep(35 + i * 14);
+  }
+  process.stdout.write(
+    '\r  🎲 rolled    ' + paint(BOLD, DICE_FACES[finalDice - 1] + '  ' + finalDice) + '   \n'
+  );
+  await sleep(220);
+}
+
+// ---------------------------------------------------------------------------
+// Save / load
+// ---------------------------------------------------------------------------
+function saveGame(game, file) {
+  fs.writeFileSync(file, JSON.stringify(game.serialize(), null, 2));
+}
+
+function loadGame(file) {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return Game.deserialize(data);
+}
+
+// ---------------------------------------------------------------------------
+// Turn flow
+// ---------------------------------------------------------------------------
+async function doRoll(game, color) {
+  if (game.isHuman(color)) {
+    const prompt =
+      paint(FG[color] + BOLD, color) +
+      ' — ' + paint(BOLD, 'press Enter') + ' to roll   ' +
+      paint(DIM, '(s = save · q = quit)') + '  ';
+    while (true) {
+      const ev = await readKey(prompt);
+      const ch = (ev.str || '').toLowerCase();
+      if (ch === 's') {
+        saveGame(game, DEFAULT_SAVE);
+        clear();
+        console.log(paint(BOLD, 'Game saved to ') + DEFAULT_SAVE);
+        console.log('Resume with:  ' + paint(BOLD, `ludo --load "${DEFAULT_SAVE}"`));
+        cleanup();
+        process.exit(0);
+      }
+      if (ch === 'q') {
+        clear();
+        console.log(paint(DIM, 'Thanks for playing!'));
+        cleanup();
+        process.exit(0);
+      }
+      // Enter or Space rolls; any other key is ignored (keeps the prompt).
+      if (isEnter(ev) || ev.key.name === 'space') break;
+    }
+    const dice = rollDice();
+    await animateDice(dice);
+    game.lastDice = dice;
+    return dice;
+  }
+  // AI
+  await sleep(650);
+  const dice = rollDice();
+  game.lastDice = dice;
+  return dice;
+}
+
+async function pickMove(game, color, dice, moves) {
+  if (!game.isHuman(color)) {
+    return chooseMove(game, color, dice, moves, game.difficulty);
+  }
+  if (moves.length === 1) {
+    await sleep(150);
+    return moves[0];
+  }
+  const lines = moves.map((m, i) => `  ${paint(BOLD, String(i + 1))}) ${describeMove(game, color, m)}`);
+  console.log('Choose a token to move ' + paint(DIM, `(press 1-${moves.length})`) + ':');
+  console.log(lines.join('\n'));
+  while (true) {
+    const ev = await readKey('> ');
+    if (ev.eof) return chooseMove(game, color, dice, moves, game.difficulty);
+    const idx = parseInt(ev.str, 10) - 1;
+    if (Number.isInteger(idx) && idx >= 0 && idx < moves.length) {
+      stdout.write(String(idx + 1) + '\n');
+      return moves[idx];
+    }
+    // ignore other keys and keep waiting
+  }
+}
+
+function describeMove(game, color, m) {
+  let where;
+  if (m.from < 0) where = 'leave the yard → start';
+  else if (m.to === 56) where = `token ${m.token + 1} → HOME`;
+  else if (m.to >= 51) where = `token ${m.token + 1} → home column`;
+  else where = `token ${m.token + 1}: ${m.from} → ${m.to}`;
+  const caps = game.capturesFor(color, m.to);
+  if (caps.length) where += paint(BOLD, `  (captures ${caps.map((x) => LETTER[x.color]).join(',')}!)`);
+  return where;
+}
+
+async function playTurn(game) {
+  const color = game.current;
+  draw(game, `${paint(FG[color] + BOLD, color)}'s turn.`);
+
+  const dice = await doRoll(game, color);
+  game.sixStreak = dice === 6 ? game.sixStreak + 1 : 0;
+
+  const faceMsg = `${paint(FG[color] + BOLD, color)} rolled ${paint(BOLD, DICE_FACES[dice - 1] + ' ' + dice)}.`;
+
+  if (game.sixStreak >= 3) {
+    draw(game, faceMsg + '  ' + paint(DIM, 'Three sixes — turn forfeited!'));
+    await pause(game, color);
+    game.nextTurn();
+    return;
+  }
+
+  const moves = game.legalMoves(color, dice);
+  if (moves.length === 0) {
+    const extra = dice === 6 ? '  Rolling again (6).' : '';
+    draw(game, faceMsg + '  No legal move.' + extra);
+    await pause(game, color);
+    if (dice !== 6) game.nextTurn();
+    return;
+  }
+
+  draw(game, faceMsg);
+  const move = await pickMove(game, color, dice, moves);
+  const result = game.applyMove(color, move);
+
+  let msg = faceMsg + '  ' + describeMove(game, color, move);
+  if (result.captured.length) {
+    msg += '\n' + paint(BOLD, `Captured ${result.captured.map((x) => x.color).join(', ')}! Sent back to yard.`);
+  }
+  if (result.home) msg += '\n' + paint(BOLD, `A ${color} token reached home!`);
+  if (game.hasFinished(color) && game.finishers[game.finishers.length - 1] === color) {
+    msg += '\n' + paint(FG[color] + BOLD, `${color.toUpperCase()} has all tokens home — finished #${game.finishers.length}!`);
+  }
+
+  draw(game, msg);
+  await pause(game, color);
+
+  if (result.extraTurn && !game.hasFinished(color)) return; // same player again
+  game.nextTurn();
+}
+
+async function pause(game, color) {
+  if (game.isHuman(color)) {
+    await readKey(paint(DIM, 'Press any key to continue…'));
+    if (IS_TTY) stdout.write('\n');
+  } else {
+    await sleep(game.watch ? 700 : 850);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Setup / arg parsing
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const opts = { watch: false, difficulty: 'normal', load: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--watch' || a === '-w') opts.watch = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--load' || a === '-l') opts.load = argv[++i];
+    else if (a.startsWith('--load=')) opts.load = a.slice(7);
+    else if (a === '--difficulty' || a === '-d') opts.difficulty = argv[++i];
+    else if (a.startsWith('--difficulty=')) opts.difficulty = a.slice(13);
+  }
+  if (!['easy', 'normal', 'hard'].includes(opts.difficulty)) opts.difficulty = 'normal';
+  return opts;
+}
+
+function printHelp() {
+  console.log(`${title()}
+
+Usage: ludo [options]
+
+Options:
+  -h, --help                 Show this help
+  -w, --watch                Watch four AI players battle it out (no input)
+  -d, --difficulty <level>   AI level: easy | normal | hard   (default: normal)
+  -l, --load <file>          Resume a previously saved game
+
+In-game (on the roll prompt):
+  Enter   roll the dice
+  s       save the game and quit
+  q       quit without saving
+
+Examples:
+  ludo                       Interactive game (asks player counts)
+  ludo -d hard               Interactive game vs. hard AI
+  ludo --watch -d hard       Demo: four hard AIs play themselves
+  ludo --load ludo-save.json Resume a saved game
+`);
+}
+
+// Resolve one token (name, initial, or 1-based index) to a colour in `pool`.
+function resolveColor(token, pool) {
+  const t = token.trim().toLowerCase();
+  if (!t) return null;
+  const byName = pool.find((c) => c === t);
+  if (byName) return byName;
+  const byInitial = pool.find((c) => LETTER[c].toLowerCase() === t);
+  if (byInitial) return byInitial;
+  const idx = parseInt(t, 10) - 1;
+  if (Number.isInteger(idx) && pool[idx]) return pool[idx];
+  return null;
+}
+
+// Parse a comma/space separated list of colours from `pool`, de-duplicated.
+function parseColorList(input, pool) {
+  const out = [];
+  for (const tok of input.split(/[,\s]+/)) {
+    const c = resolveColor(tok, pool);
+    if (c && !out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+function colorMenu(pool) {
+  return pool.map((c, i) => `${i + 1}) ` + paint(FG[c] + BOLD, c)).join('   ');
+}
+
+async function setup(opts) {
+  clear();
+  console.log(title());
+  console.log();
+  console.log('Colours: ' + PLAYERS.map((c) => paint(FG[c] + BOLD, c)).join(', '));
+  console.log(paint(DIM, `AI difficulty: ${opts.difficulty}`));
+  console.log();
+
+  const nRaw = (await ask('How many players (2-4)? [4] ')).trim();
+  let n = parseInt(nRaw, 10);
+  if (!Number.isInteger(n) || n < 2 || n > 4) n = 4;
+
+  // Pick which colours are in the game (only matters when fewer than 4).
+  let colors = PLAYERS.slice(0, n);
+  if (n < 4) {
+    console.log('\nChoose ' + n + ' colours:  ' + colorMenu(PLAYERS));
+    const pick = parseColorList(await ask(`Which colours play? [${colors.join(', ')}] `), PLAYERS);
+    if (pick.length >= 2) colors = pick.slice(0, n);
+  }
+
+  // Pick which of those colours are controlled by a human.
+  console.log('\nIn play:  ' + colorMenu(colors));
+  const humansRaw = await ask(
+    `Which colours are human? (comma list, or 'none') [${colors[0]}] `
+  );
+  let humans;
+  if (humansRaw.trim().toLowerCase() === 'none') humans = [];
+  else {
+    humans = parseColorList(humansRaw, colors);
+    if (humansRaw.trim() === '') humans = [colors[0]]; // default: first colour
+  }
+
+  const game = new Game(colors);
+  for (const c of humans) game.humans.add(c);
+  game.difficulty = opts.difficulty;
+  return game;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    printHelp();
+    cleanup();
+    return;
+  }
+
+  let game;
+  if (opts.load) {
+    try {
+      game = loadGame(opts.load);
+      if (game.difficulty === undefined) game.difficulty = opts.difficulty;
+    } catch (err) {
+      console.error(paint(BOLD, 'Could not load save file: ') + err.message);
+      cleanup();
+      process.exitCode = 1;
+      return;
+    }
+  } else if (opts.watch) {
+    game = new Game(PLAYERS.slice());
+    game.difficulty = opts.difficulty;
+    game.watch = true; // all AI, no humans
+  } else {
+    game = await setup(opts);
+  }
+  currentGame = game;
+
+  while (!game.gameOver) {
+    await playTurn(game);
+  }
+
+  const podium = game.finishers.slice();
+  for (const c of game.colors) if (!podium.includes(c)) podium.push(c);
+
+  draw(game, '');
+  console.log(paint(BOLD, '  🏆  Game over!'));
+  console.log();
+  podium.forEach((c, i) => {
+    const medal = ['🥇', '🥈', '🥉', '  '][i] || '  ';
+    console.log(`  ${medal} ${i + 1}. ${paint(FG[c] + BOLD, c)}  (${game.homeCount(c)}/4 home)`);
+  });
+  console.log();
+  cleanup();
+}
+
+// Ctrl-C: in raw mode the OS won't send SIGINT, so the keypress handler calls
+// this directly. We also register it on SIGINT for non-raw / piped runs.
+function onInterrupt() {
+  cleanup();
+  if (currentGame && !currentGame.gameOver && currentGame.humans.size > 0) {
+    try {
+      const auto = path.join(process.cwd(), 'ludo-autosave.json');
+      saveGame(currentGame, auto);
+      console.log('\n' + paint(DIM, 'Autosaved to ' + auto + ' — resume with  ludo --load "' + auto + '"'));
+    } catch (_) {
+      console.log('\n' + paint(DIM, 'Thanks for playing!'));
+    }
+  } else {
+    console.log('\n' + paint(DIM, 'Thanks for playing!'));
+  }
+  process.exit(0);
+}
+process.on('SIGINT', onInterrupt);
+
+module.exports = { main };

package/src/constants.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Board geometry for a classic 15x15 Ludo board.
+//
+// The shared main track is a 52-cell loop. Coordinates are [row, col] on the
+// 15x15 grid. Index 0 is Red's starting square; the loop runs clockwise.
+// ---------------------------------------------------------------------------
+
+const TRACK = [
+  [6, 1], [6, 2], [6, 3], [6, 4], [6, 5],           // 0-4   red arm (right)
+  [5, 6], [4, 6], [3, 6], [2, 6], [1, 6], [0, 6],   // 5-10  up
+  [0, 7],                                            // 11    top turn
+  [0, 8], [1, 8], [2, 8], [3, 8], [4, 8], [5, 8],   // 12-17 down
+  [6, 9], [6, 10], [6, 11], [6, 12], [6, 13], [6, 14], // 18-23 green arm (right)
+  [7, 14],                                           // 24    right turn
+  [8, 14], [8, 13], [8, 12], [8, 11], [8, 10], [8, 9], // 25-30 back
+  [9, 8], [10, 8], [11, 8], [12, 8], [13, 8], [14, 8], // 31-36 down
+  [14, 7],                                           // 37    bottom turn
+  [14, 6], [13, 6], [12, 6], [11, 6], [10, 6], [9, 6], // 38-43 up
+  [8, 5], [8, 4], [8, 3], [8, 2], [8, 1], [8, 0],   // 44-49 left arm
+  [7, 0],                                            // 50    left turn
+  [6, 0],                                            // 51    back to start
+];
+
+// Home columns (the coloured lane leading to the centre). 6 cells each; the
+// last cell is the goal — a token reaching it is "home".
+const HOME_COLUMNS = {
+  red:    [[7, 1], [7, 2], [7, 3], [7, 4], [7, 5], [7, 6]],
+  green:  [[1, 7], [2, 7], [3, 7], [4, 7], [5, 7], [6, 7]],
+  yellow: [[7, 13], [7, 12], [7, 11], [7, 10], [7, 9], [7, 8]],
+  blue:   [[13, 7], [12, 7], [11, 7], [10, 7], [9, 7], [8, 7]],
+};
+
+// Where each colour enters the shared track (index into TRACK).
+const START_INDEX = { red: 0, green: 13, yellow: 26, blue: 39 };
+
+// Full journey length per token: 51 shared-track steps (offset 0..50) plus a
+// 6-cell home column (offset 51..56). Offset 56 == home / goal.
+const HOME_ENTRY_OFFSET = 51; // first offset inside the home column
+const GOAL_OFFSET = 56;       // exact offset that counts as "home"
+const TRACK_LEN = TRACK.length; // 52
+
+// Safe squares: the four coloured starts and the four star squares. Tokens on
+// these cannot be captured.
+const SAFE_INDICES = new Set([0, 8, 13, 21, 26, 34, 39, 47]);
+
+const PLAYERS = ['red', 'green', 'yellow', 'blue'];
+
+// The 6x6 yard corners and the 2x2 slots where based tokens sit.
+const YARDS = {
+  red:    { origin: [0, 0],   slots: [[1, 1], [1, 3], [3, 1], [3, 3]] },
+  green:  { origin: [0, 9],   slots: [[1, 10], [1, 12], [3, 10], [3, 12]] },
+  yellow: { origin: [9, 9],   slots: [[10, 10], [10, 12], [12, 10], [12, 12]] },
+  blue:   { origin: [9, 0],   slots: [[10, 1], [10, 3], [12, 1], [12, 3]] },
+};
+
+const CENTER = [7, 7];
+
+module.exports = {
+  TRACK,
+  TRACK_LEN,
+  HOME_COLUMNS,
+  START_INDEX,
+  HOME_ENTRY_OFFSET,
+  GOAL_OFFSET,
+  SAFE_INDICES,
+  PLAYERS,
+  YARDS,
+  CENTER,
+};

package/src/game.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const {
+  TRACK_LEN,
+  START_INDEX,
+  HOME_ENTRY_OFFSET,
+  GOAL_OFFSET,
+  SAFE_INDICES,
+  PLAYERS,
+} = require('./constants');
+
+// Token offsets:
+//   -1        -> in the yard (base), needs a 6 to come out
+//    0..50    -> on the shared track (offset from the colour's start square)
+//   51..56    -> inside the home column (56 == home / goal)
+const BASE = -1;
+
+class Game {
+  // activeColors: array of colour names actually playing (2-4).
+  constructor(activeColors = PLAYERS.slice()) {
+    this.colors = activeColors.slice();
+    this.tokens = {};
+    for (const c of this.colors) this.tokens[c] = [BASE, BASE, BASE, BASE];
+    this.humans = new Set(); // colours controlled by a human
+    this.turn = 0;           // index into this.colors
+    this.lastDice = null;
+    this.sixStreak = 0;
+    this.winner = null;
+    this.finishers = [];     // colours that have finished, in order
+  }
+
+  get current() {
+    return this.colors[this.turn];
+  }
+
+  isHuman(color) {
+    return this.humans.has(color);
+  }
+
+  // Absolute track index for a token, or null if in base / home column.
+  absIndex(color, offset) {
+    if (offset < 0 || offset > 50) return null;
+    return (START_INDEX[color] + offset) % TRACK_LEN;
+  }
+
+  hasFinished(color) {
+    return this.tokens[color].every((o) => o === GOAL_OFFSET);
+  }
+
+  // Legal moves for `color` given a dice value. Returns [{token, from, to}].
+  legalMoves(color, dice) {
+    const moves = [];
+    const offs = this.tokens[color];
+    for (let t = 0; t < offs.length; t++) {
+      const from = offs[t];
+      if (from === GOAL_OFFSET) continue; // already home
+      if (from === BASE) {
+        if (dice === 6) moves.push({ token: t, from, to: 0 });
+        continue;
+      }
+      const to = from + dice;
+      if (to > GOAL_OFFSET) continue; // must land exactly on the goal
+      moves.push({ token: t, from, to });
+    }
+    return moves;
+  }
+
+  // Would applying `move` for `color` capture at least one opponent token?
+  wouldCapture(color, move) {
+    return this.capturesFor(color, move.to).length > 0;
+  }
+
+  // List of {color, token} opponents captured if `color` lands on `toOffset`.
+  capturesFor(color, toOffset) {
+    const abs = this.absIndex(color, toOffset);
+    if (abs === null) return [];       // home column: never captures
+    if (SAFE_INDICES.has(abs)) return []; // safe square: no captures
+    const hits = [];
+    for (const other of this.colors) {
+      if (other === color) continue;
+      const offs = this.tokens[other];
+      for (let t = 0; t < offs.length; t++) {
+        if (this.absIndex(other, offs[t]) === abs) hits.push({ color: other, token: t });
+      }
+    }
+    return hits;
+  }
+
+  // Apply a move. Returns { captured: [...], home: bool, extraTurn: bool }.
+  applyMove(color, move) {
+    const captured = this.capturesFor(color, move.to);
+    for (const cap of captured) this.tokens[cap.color][cap.token] = BASE;
+    this.tokens[color][move.token] = move.to;
+
+    const home = move.to === GOAL_OFFSET;
+    if (this.hasFinished(color) && !this.finishers.includes(color)) {
+      this.finishers.push(color);
+    }
+    const extraTurn = this.lastDice === 6 || captured.length > 0 || home;
+    return { captured, home, extraTurn };
+  }
+
+  // Advance to the next colour that has not finished.
+  nextTurn() {
+    this.sixStreak = 0;
+    for (let i = 0; i < this.colors.length; i++) {
+      this.turn = (this.turn + 1) % this.colors.length;
+      if (!this.hasFinished(this.current)) return;
+    }
+  }
+
+  // True once only one (or zero) unfinished players remain.
+  get gameOver() {
+    const remaining = this.colors.filter((c) => !this.hasFinished(c));
+    return remaining.length <= 1;
+  }
+
+  // Count of tokens home for a colour.
+  homeCount(color) {
+    return this.tokens[color].filter((o) => o === GOAL_OFFSET).length;
+  }
+
+  // Plain-object snapshot for saving to disk.
+  serialize() {
+    return {
+      v: 1,
+      colors: this.colors.slice(),
+      tokens: JSON.parse(JSON.stringify(this.tokens)),
+      humans: [...this.humans],
+      turn: this.turn,
+      lastDice: this.lastDice,
+      sixStreak: this.sixStreak,
+      finishers: this.finishers.slice(),
+      difficulty: this.difficulty,
+    };
+  }
+
+  // Rebuild a Game from a serialized snapshot.
+  static deserialize(data) {
+    if (!data || !Array.isArray(data.colors)) throw new Error('invalid save file');
+    const g = new Game(data.colors);
+    g.tokens = data.tokens;
+    g.humans = new Set(data.humans || []);
+    g.turn = data.turn || 0;
+    g.lastDice = data.lastDice ?? null;
+    g.sixStreak = data.sixStreak || 0;
+    g.finishers = data.finishers || [];
+    if (data.difficulty) g.difficulty = data.difficulty;
+    return g;
+  }
+}
+
+module.exports = { Game, BASE };

package/src/render.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const {
+  TRACK,
+  HOME_COLUMNS,
+  START_INDEX,
+  SAFE_INDICES,
+  YARDS,
+  CENTER,
+  PLAYERS,
+} = require('./constants');
+const { BASE } = require('./game');
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+
+// Foreground colours (bright) per player.
+const FG = {
+  red: '\x1b[91m',
+  green: '\x1b[92m',
+  yellow: '\x1b[93m',
+  blue: '\x1b[94m',
+};
+// Background colours for yards / home columns.
+const BG = {
+  red: '\x1b[101m',
+  green: '\x1b[102m',
+  yellow: '\x1b[103m',
+  blue: '\x1b[104m',
+};
+const BLACK_FG = '\x1b[30m'; // dark text on a coloured token so it stays legible
+
+const LETTER = { red: 'R', green: 'G', yellow: 'Y', blue: 'B' };
+const supportsColor = process.stdout.isTTY !== false && !process.env.NO_COLOR;
+
+function paint(code, s) {
+  return supportsColor ? code + s + RESET : s;
+}
+
+function key(r, c) {
+  return r + ',' + c;
+}
+
+// Build lookup maps so we can decide what to draw in each grid cell.
+const trackAt = new Map();
+TRACK.forEach(([r, c], i) => trackAt.set(key(r, c), i));
+
+const homeAt = new Map(); // "r,c" -> color
+for (const color of PLAYERS) {
+  HOME_COLUMNS[color].forEach(([r, c]) => homeAt.set(key(r, c), color));
+}
+
+const yardCells = new Map(); // "r,c" -> color   (the 6x6 corners)
+for (const color of PLAYERS) {
+  const [r0, c0] = YARDS[color].origin;
+  for (let r = r0; r < r0 + 6; r++) {
+    for (let c = c0; c < c0 + 6; c++) yardCells.set(key(r, c), color);
+  }
+}
+
+const yardSlotColor = new Map(); // "r,c" -> color
+for (const color of PLAYERS) {
+  YARDS[color].slots.forEach(([r, c]) => yardSlotColor.set(key(r, c), color));
+}
+
+const startCell = new Map(); // "r,c" -> color
+for (const color of PLAYERS) {
+  const [r, c] = TRACK[START_INDEX[color]];
+  startCell.set(key(r, c), color);
+}
+
+// Render the whole board (plus token positions) to a string.
+function render(game) {
+  // Map each grid cell to the tokens sitting on it.
+  const occupants = new Map(); // "r,c" -> [{color, token}]
+  const baseTokens = {};       // color -> list of based token indices
+  for (const color of game.colors) {
+    baseTokens[color] = [];
+    game.tokens[color].forEach((offset, t) => {
+      if (offset === BASE) {
+        baseTokens[color].push(t);
+        return;
+      }
+      const [r, c] = cellFor(color, offset);
+      const k = key(r, c);
+      if (!occupants.has(k)) occupants.set(k, []);
+      occupants.get(k).push({ color, token: t });
+    });
+  }
+
+  // Place based tokens into their yard slots.
+  const slotFill = new Map(); // "r,c" -> {color, token}
+  for (const color of game.colors) {
+    const slots = YARDS[color].slots;
+    baseTokens[color].forEach((t) => {
+      const [r, c] = slots[t];
+      slotFill.set(key(r, c), { color, token: t });
+    });
+  }
+
+  const lines = [];
+  for (let r = 0; r < 15; r++) {
+    let line = '';
+    for (let c = 0; c < 15; c++) {
+      line += cellString(game, r, c, occupants, slotFill);
+    }
+    lines.push(line);
+  }
+  return lines.join('\n');
+}
+
+// Grid coordinate for a token of `color` at a given offset (>=0).
+function cellFor(color, offset) {
+  if (offset <= 50) {
+    const abs = (START_INDEX[color] + offset) % TRACK.length;
+    return TRACK[abs];
+  }
+  return HOME_COLUMNS[color][offset - 51];
+}
+
+function cellString(game, r, c, occupants, slotFill) {
+  const k = key(r, c);
+
+  // A token on the board takes precedence. Draw it as a filled coloured pill
+  // (dark letter on the colour's background) so it is easy to spot on the track.
+  const occ = occupants.get(k);
+  if (occ && occ.length) {
+    const top = occ[0];
+    const ch = occ.length > 1 ? String(occ.length) : LETTER[top.color];
+    return paint(BG[top.color] + BLACK_FG + BOLD, ch) + paint(BG[top.color], ' ');
+  }
+
+  // A based token in its yard slot.
+  const slot = slotFill.get(k);
+  if (slot) {
+    return paint(BG[slot.color] + BOLD, LETTER[slot.color]) + paint(BG[slot.color], ' ');
+  }
+
+  // Centre goal.
+  if (r === CENTER[0] && c === CENTER[1]) return paint(BOLD, '★') + ' ';
+
+  // Home column cell.
+  const homeColor = homeAt.get(k);
+  if (homeColor) return paint(BG[homeColor], '  ');
+
+  // Start square (coloured).
+  const startColor = startCell.get(k);
+  if (startColor) return paint(FG[startColor] + BOLD, '◈') + ' ';
+
+  // Regular track cell.
+  if (trackAt.has(k)) {
+    const abs = trackAt.get(k);
+    if (SAFE_INDICES.has(abs)) return paint(DIM, '✦') + ' ';
+    return paint(DIM, '·') + ' ';
+  }
+
+  // Yard interior (coloured block, empty slot marker).
+  const yardColor = yardCells.get(k);
+  if (yardColor) {
+    if (yardSlotColor.has(k)) return paint(BG[yardColor] + DIM, '○') + paint(BG[yardColor], ' ');
+    return paint(BG[yardColor], '  ');
+  }
+
+  return '  ';
+}
+
+// A short coloured status/legend block.
+function status(game) {
+  const rows = game.colors.map((color) => {
+    const tag = game.isHuman(color) ? 'you' : 'cpu';
+    const home = game.homeCount(color);
+    const marker = color === game.current ? '▶' : ' ';
+    const label = paint(FG[color] + BOLD, LETTER[color] + ' ' + color.padEnd(6));
+    return `${marker} ${label} (${tag})  home ${home}/4`;
+  });
+  return rows.join('\n');
+}
+
+module.exports = { render, status, paint, FG, LETTER, RESET, BOLD, DIM };