Build a Complete Ludo Game — REST API + Socket.IO + Docker

ludo-game/
├── src/
│   ├── engine/
│   │   ├── board.js         // board constants, square mapping
│   │   ├── dice.js          // dice roll logic
│   │   ├── tokens.js        // token state management
│   │   ├── moves.js         // move validation rules
│   │   └── game.js          // main Game class orchestrating all engine modules
│   ├── api/
│   │   ├── routes.js        // Express router mounting all endpoints
│   │   └── middleware.js    // auth, error handler, request logger
│   ├── socket/
│   │   └── handler.js       // Socket.IO connection handling and room management
│   └── index.js             // entry point: Express app + HTTP server + Socket.IO bind
├── public/
│   └── index.html           // minimal browser client
├── tests/
│   └── game.test.js         // engine unit tests
├── Dockerfile
├── docker-compose.yml
└── package.json

mkdir ludo-game && cd ludo-game
npm init -y
npm install express socket.io cors uuid dotenv
npm install --save-dev jest

# Server settings
PORT=3000
NODE_ENV=development

# LudoKingAPI credentials (replace with your own)
LUDOKING_API_KEY=your_api_key_here
LUDOKING_API_URL=https://api.ludokingapi.site/v1

# Game settings
MAX_PLAYERS=4
DICE_MAX=6
TOKEN_HOME_SQUARES=57     // squares a token must travel to reach home
BOARD_START_SQUARE=1    // first playable square on the main track

// Constants for the classic Ludo board layout
const OUTER_TRACK = 52;
const SQUARES_PER_PLAYER = 13;   // 52 / 4 = 13 squares per quarter
const HOME_COLUMN_LENGTH = 6;

/**
 * getStartSquare — the first playable square on the outer track for a player.
 * Player 0 starts at square 0, player 1 at square 13, player 2 at square 26, etc.
 */
function getStartSquare(playerIndex) {
  return (playerIndex * SQUARES_PER_PLAYER) % OUTER_TRACK;
}

/**
 * getHomeEntrySquare — the square just before a player's home column begins.
 * A token lands here after completing the full outer track circuit.
 */
function getHomeEntrySquare(playerIndex) {
  return (getStartSquare(playerIndex) - 1 + OUTER_TRACK) % OUTER_TRACK;
}

/**
 * normalizeSquare — wraps a square index into the 0-51 outer track range.
 * Handles negative offsets (tokens moving backwards from start) correctly.
 */
function normalizeSquare(square) {
  return ((square % OUTER_TRACK) + OUTER_TRACK) % OUTER_TRACK;
}

/**
 * isInHomeColumn — returns true if the token has entered its player's home column
 * and is still on the board (not yet finished).
 * @param {number} playerIndex
 * @param {number} outerSquare  — the token's position on the outer track (0-51)
 * @param {number} homeStep    — how many squares into the home column the token is (0-6)
 */
function isInHomeColumn(playerIndex, outerSquare, homeStep) {
  if (homeStep <= 0) return false;
  const entry = getHomeEntrySquare(playerIndex);
  return normalizeSquare(outerSquare - entry) > 0;
}

module.exports = { OUTER_TRACK, SQUARES_PER_PLAYER, HOME_COLUMN_LENGTH,
  getStartSquare, getHomeEntrySquare, normalizeSquare, isInHomeColumn };

const { randomInt } = require('crypto');
const DICE_FACES = 6;

/**
 * rollDice — returns a random integer between 1 and DICE_FACES (inclusive).
 * Uses crypto.randomInt for server-side unpredictability.
 */
function rollDice() {
  return randomInt(1, DICE_FACES + 1);
}

/**
 * canMoveAgain — in Ludo, rolling a 6 grants an extra turn.
 * @param {number} diceValue
 * @returns {boolean}
 */
function canMoveAgain(diceValue) {
  return diceValue === 6;
}

module.exports = { rollDice, canMoveAgain, DICE_FACES };

/**
 * createToken — factory function producing a fresh token in the starting state.
 * @param {number} playerIndex  — 0-based player index (0-3)
 * @param {number} tokenIndex   — 0-based token index within that player (0-3)
 */
function createToken(playerIndex, tokenIndex) {
  return {
    player: playerIndex,
    index: tokenIndex,
    square: -1,       // -1 means "in house" (not yet on the board)
    homeStep: 0,      // 0 = not in home column; 1-6 = position in home column
    finished: false
  };
}

/**
 * canLeaveHouse — token can only leave house if the dice roll is exactly 6.
 * @param {object} token
 * @param {number} dice
 * @returns {boolean}
 */
function canLeaveHouse(token, dice) {
  return token.square === -1 && dice === 6;
}

/**
 * isHome — token has reached the end of its home column.
 * @param {object} token
 * @returns {boolean}
 */
function isHome(token) {
  return token.homeStep >= 7;
}

module.exports = { createToken, canLeaveHouse, isHome };

const { OUTER_TRACK, getStartSquare, getHomeEntrySquare, normalizeSquare, isInHomeColumn } = require('./board');
const { canLeaveHouse } = require('./tokens');

const SAFE_SQUARES = new Set([0, 8, 13, 21, 26, 34, 39, 47]);
// Each player's start square is a safe star square

/**
 * validateMove — core rule engine. Returns { valid: true } or { valid: false, reason: string }.
 *
 * Rules enforced:
 *  1. Token belongs to the player attempting to move
 *  2. Token is not already finished
 *  3. If in house: dice must be 6 to leave
 *  4. If on board: movement must not overshoot the home column
 *  5. If landing on opponent token (not on safe square): capture
 *
 * @param {object} token         — token being moved
 * @param {number} dice          — dice value (1-6)
 * @param {number} currentPlayer — index of player attempting the move
 * @param {number} playerCount   — total number of players in game
 * @param {object[]} allTokens   — all tokens in game (for capture detection)
 */
function validateMove(token, dice, currentPlayer, playerCount, allTokens) {
  // Rule 1: token belongs to mover
  if (token.player !== currentPlayer) {
    return { valid: false, reason: "Token does not belong to the current player" };
  }

  // Rule 2: token not finished
  if (token.finished) {
    return { valid: false, reason: "Token has already finished the race" };
  }

  // Rule 3: leaving house
  if (token.square === -1) {
    if (!canLeaveHouse(token, dice)) {
      return { valid: false, reason: "Must roll a 6 to move a token out of house" };
    }
    return { valid: true, action: "leave_house" };
  }

  // Rule 4: token on the board — calculate destination
  const entry = getHomeEntrySquare(token.player);
  const stepsFromEntry = normalizeSquare(token.square - entry);
  const newHomeStep = token.homeStep + dice;

  // Overshooting home column
  if (newHomeStep > 7) {   // 6 home squares + 1 for "finished"
    return { valid: false, reason: "Move overshoots home column" };
  }

  // Reaching exactly home
  if (newHomeStep === 7) {
    return { valid: true, action: "finish" };
  }

  // Still in home column
  if (newHomeStep > 0) {
    return { valid: true, action: "home_column", newHomeStep };
  }

  // Moving along outer track
  const targetSquare = normalizeSquare(token.square + dice);

  // Rule 5: capture check — can only capture on non-safe squares
  const occupant = allTokens.find(t =>
    t.player !== token.player &&
    t.square !== -1 &&
    t.homeStep === 0 &&
    normalizeSquare(t.square) === targetSquare
  );
  if (occupant && !SAFE_SQUARES.has(targetSquare)) {
    return { valid: true, action: "capture", capturedToken: occupant, targetSquare };
  }

  return { valid: true, action: "move", targetSquare };
}

module.exports = { validateMove, SAFE_SQUARES };

const { v4: uuidv4 } = require('uuid');
const { rollDice, canMoveAgain } = require('./dice');
const { createToken, isHome } = require('./tokens');
const { validateMove } = require('./moves');
const { getStartSquare, normalizeSquare } = require('./board');

class Game {
  constructor({ playerCount = 2, variant = 'classic' } = {}) {
    this.id = uuidv4();
    this.variant = variant;
    this.playerCount = playerCount;
    this.players = [];          // { id, name }
    this.tokens = [];
    this.currentPlayer = 0;
    this.diceValue = 0;
    this.extraTurn = false;
    this.gameOver = false;
    this.winner = null;
    this.lastEvent = null;   // { type, data } — consumed by Socket.IO

    // Initialize tokens: 4 per player
    for (let p = 0; p < playerCount; p++) {
      for (let t = 0; t < 4; t++) {
        this.tokens.push(createToken(p, t));
      }
    }
  }

  /**
   * addPlayer — register a player and return their player ID.
   */
  addPlayer(name) {
    if (this.players.length >= this.playerCount) {
      throw new Error("Game is full");
    }
    const id = uuidv4();
    this.players.push({ id, name });
    return id;
  }

  /**
   * roll — roll the dice for the current player. Returns the dice value.
   */
  roll() {
    this.diceValue = rollDice();
    this.extraTurn = canMoveAgain(this.diceValue);
    this.lastEvent = { type: 'dice_rolled', player: this.currentPlayer, value: this.diceValue };
    return this.diceValue;
  }

  /**
   * submitMove — validate and execute a move. Returns { success, reason, event }.
   */
  submitMove(playerIndex, tokenIndex) {
    if (this.gameOver) {
      return { success: false, reason: "Game is already over" };
    }
    if (playerIndex !== this.currentPlayer) {
      return { success: false, reason: "Not this player's turn" };
    }
    if (this.diceValue === 0) {
      return { success: false, reason: "Must roll dice before submitting a move" };
    }

    const token = this.tokens.find(t => t.player === playerIndex && t.index === tokenIndex);
    if (!token) {
      return { success: false, reason: "Invalid token index" };
    }

    const result = validateMove(token, this.diceValue, playerIndex, this.playerCount, this.tokens);
    if (!result.valid) {
      return { success: false, reason: result.reason };
    }

    // Apply the validated move
    this.applyMove(token, result);

    // Check for win
    this.checkWin(playerIndex);

    // Advance turn if no extra turn earned
    if (!this.extraTurn && !this.gameOver) {
      this.advanceTurn();
    } else {
      this.extraTurn = false;  // consume the flag; reset for next roll
    }

    return { success: true, event: this.lastEvent };
  }

  applyMove(token, result) {
    switch (result.action) {
      case 'leave_house':
        token.square = getStartSquare(token.player);
        this.lastEvent = { type: 'token_left_house', player: token.player, tokenIndex: token.index };
        break;
      case 'move':
        token.square = result.targetSquare;
        this.lastEvent = { type: 'token_moved', player: token.player, tokenIndex: token.index, square: result.targetSquare };
        break;
      case 'capture':
        const captured = result.capturedToken;
        captured.square = -1;   // captured token goes back to house
        token.square = result.targetSquare;
        this.lastEvent = { type: 'token_captured', player: token.player, tokenIndex: token.index,
          capturedBy: token.player, capturedTokenIndex: captured.index };
        break;
      case 'home_column':
        token.homeStep = result.newHomeStep;
        this.lastEvent = { type: 'token_home_column', player: token.player, tokenIndex: token.index, homeStep: result.newHomeStep };
        break;
      case 'finish':
        token.homeStep = 7;
        token.finished = true;
        this.lastEvent = { type: 'token_finished', player: token.player, tokenIndex: token.index };
        break;
    }
  }

  checkWin(playerIndex) {
    const playerTokens = this.tokens.filter(t => t.player === playerIndex);
    if (playerTokens.every(t => t.finished)) {
      this.gameOver = true;
      this.winner = playerIndex;
      this.lastEvent = { type: 'game_over', winner: playerIndex };
    }
  }

  advanceTurn() {
    this.currentPlayer = (this.currentPlayer + 1) % this.playerCount;
    this.diceValue = 0;
  }

  /**
   * getState — serializable snapshot for REST responses and Socket.IO broadcasts.
   */
  getState() {
    return {
      game_id: this.id,
      variant: this.variant,
      player_count: this.playerCount,
      players: this.players,
      current_player: this.currentPlayer,
      dice: this.diceValue,
      tokens: this.tokens,
      game_over: this.gameOver,
      winner: this.winner
    };
  }
}

module.exports = Game;

require('dotenv').config();
const express = require('express');
const http = require('http');
const { Server } = require('socket.io');
const cors = require('cors');

const app = express();
const server = http.createServer(app);
const io = new Server(server, {
  cors: { origin: "*", methods: ["GET", "POST"] }
});

app.use(express.static('public'));
app.use(cors());
app.use(express.json());

// In-memory store — replace with Redis/Postgres for production multi-instance deployment
const games = new Map();

require('./api/routes')(app, games, io);
require('./socket/handler')(io, games);

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Ludo server running on http://localhost:${PORT}`);
});

const Game = require('../engine/game');

function authMiddleware(req, res, next) {
  const apiKey = req.headers['authorization']?.replace('Bearer ', '');
  if (!apiKey && process.env.NODE_ENV === 'production') {
    return res.status(401).json({ error: 'unauthorized', message: 'Missing API key' });
  }
  next();
}

module.exports = function(app, games, io) {

  // POST /games — create a new game room
  app.post('/games', authMiddleware, (req, res) => {
    const { player_count = 2, variant = 'classic', host_name } = req.body;
    if (player_count < 2 || player_count > 4) {
      return res.status(400).json({ error: 'invalid_player_count', message: 'Player count must be 2-4' });
    }
    const game = new Game({ playerCount: player_count, variant });
    const hostId = game.addPlayer(host_name || 'Host');
    games.set(game.id, game);
    io.emit('game_created', { game_id: game.id, host_id: hostId });
    res.status(201).json({ game_id: game.id, host_id: hostId, state: game.getState() });
  });

  // POST /games/:id/join — join an existing game
  app.post('/games/:id/join', authMiddleware, (req, res) => {
    const game = games.get(req.params.id);
    if (!game) return res.status(404).json({ error: 'not_found', message: 'Game not found' });
    try {
      const playerId = game.addPlayer(req.body.name || 'Player');
      io.to(req.params.id).emit('player_joined', { player_id: playerId, state: game.getState() });
      res.json({ player_id: playerId, state: game.getState() });
    } catch (e) {
      res.status(400).json({ error: 'join_failed', message: e.message });
    }
  });

  // GET /games/:id/state — fetch current game state (no side effects)
  app.get('/games/:id/state', authMiddleware, (req, res) => {
    const game = games.get(req.params.id);
    if (!game) return res.status(404).json({ error: 'not_found', message: 'Game not found' });
    res.json(game.getState());
  });

  // POST /games/:id/roll — roll the dice for the current player
  app.post('/games/:id/roll', authMiddleware, (req, res) => {
    const game = games.get(req.params.id);
    if (!game) return res.status(404).json({ error: 'not_found' });
    const { player_id } = req.body;
    const player = game.players.find(p => p.id === player_id);
    if (!player) return res.status(400).json({ error: 'invalid_player' });
    if (game.players[game.currentPlayer].id !== player_id) {
      return res.status(400).json({ error: 'not_your_turn' });
    }
    const diceValue = game.roll();
    io.to(req.params.id).emit('dice_rolled', { player: game.currentPlayer, value: diceValue, state: game.getState() });
    res.json({ dice: diceValue, state: game.getState() });
  });

  // POST /games/:id/move — submit a move
  app.post('/games/:id/move', authMiddleware, (req, res) => {
    const game = games.get(req.params.id);
    if (!game) return res.status(404).json({ error: 'not_found' });
    const { player_id, token_index } = req.body;
    const playerIndex = game.players.findIndex(p => p.id === player_id);
    if (playerIndex === -1) return res.status(400).json({ error: 'invalid_player' });
    const result = game.submitMove(playerIndex, token_index);
    if (!result.success) {
      return res.status(400).json({ error: 'illegal_move', message: result.reason });
    }
    io.to(req.params.id).emit('game_state', { event: result.event, state: game.getState() });
    res.json({ success: true, event: result.event, state: game.getState() });
  });

  // Global error handler
  app.use((err, req, res, _next) => {
    console.error(err);
    res.status(500).json({ error: 'internal_error', message: err.message });
  });
};

/**
 * Socket.IO handler — manages real-time bidirectional communication.
 *
 * Events emitted by server:
 *   game_created     — new game was created
 *   player_joined    — a player successfully joined a game room
 *   dice_rolled      — a player rolled the dice (includes new dice value)
 *   token_moved      — a token changed position
 *   token_captured   — a token landed on and sent an opponent back to house
 *   token_finished   — a token reached home
 *   game_over        — game ended (includes winner index)
 *   error            — invalid action (includes reason string)
 *
 * Events received from client:
 *   join_room        — client wants to observe a game
 *   leave_room       — client disconnects from a game room
 *   ping             — heartbeat to keep connection alive
 */

module.exports = function(io, games) {

  io.on('connection', (socket) => {
    console.log(`Client connected: ${socket.id}`);

    socket.on('join_room', ({ game_id }) => {
      const game = games.get(game_id);
      if (!game) {
        socket.emit('error', { message: 'Game not found' });
        return;
      }
      socket.join(game_id);
      socket.gameId = game_id;  // track which room this socket belongs to
      socket.emit('joined_room', { game_id, state: game.getState() });
      console.log(`Socket ${socket.id} joined room ${game_id}`);
    });

    socket.on('leave_room', ({ game_id }) => {
      socket.leave(game_id);
      socket.gameId = null;
      console.log(`Socket ${socket.id} left room ${game_id}`);
    });

    socket.on('ping', () => {
      socket.emit('pong', { timestamp: Date.now() });
    });

    socket.on('disconnect', (reason) => {
      console.log(`Client disconnected: ${socket.id} — ${reason}`);
      if (socket.gameId) {
        socket.leave(socket.gameId);
      }
    });
  });
};

<!-- Serve this file from src/index.js: app.use(express.static('public')) -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Ludo Game Client</title>
  <style>
    body { font-family: system-ui; background: #0f1117; color: #e6edf3; margin: 0; padding: 20px; }
    button { padding: 8px 16px; border-radius: 6px; border: 1px solid #30363d; background: #21262d; color: #e6edf3; cursor: pointer; margin: 4px; }
    button:hover { background: #30363d; }
    button:disabled { opacity: 0.5; cursor: not-allowed; }
    #log { background: #161b22; border-radius: 8px; padding: 12px; height: 300px; overflow-y: auto; font-family: monospace; font-size: 13px; margin-top: 16px; white-space: pre-wrap; }
    #state { background: #161b22; border-radius: 8px; padding: 12px; margin-top: 12px; font-family: monospace; }
  </style>
</head>
<body>
  <h2>Ludo Game Client</h2>
  <div>
    <button id="btnCreate">Create Game</button>
    <input id="gameIdInput" placeholder="Game ID" />
    <button id="btnJoin">Join Game</button>
    <button id="btnRoll">Roll Dice</button>
  </div>
  <div id="state">No active game</div>
  <h3>Event Log</h3>
  <div id="log"></div>

  <script src="/socket.io/socket.io.js"></script>
  <script>
    const API = 'http://localhost:3000';
    const socket = io(API);
    let currentGame = null;
    let myPlayerId = null;
    const logEl = document.getElementById('log');

    function info(msg) {
      logEl.textContent += `[${new Date().toLocaleTimeString()}] ${msg}\n`;
      logEl.scrollTop = logEl.scrollHeight;
    }

    function renderState(state) {
      if (!state) { document.getElementById('state').textContent = 'No active game'; return; }
      const cur = state.current_player;
      document.getElementById('state').innerHTML =
        `Game: ${state.game_id.slice(0,8)}... | ` +
        `Current: Player ${cur} | Dice: ${state.dice} | Over: ${state.game_over}` +
        (state.game_over ? ` | Winner: Player ${state.winner}` : '');
    }

    // REST helper
    async function api(path, options = {}) {
      const res = await fetch(`${API}${path}`, {
        headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer test' },
        ...options,
        body: options.body ? JSON.stringify(options.body) : undefined
      });
      return res.json();
    }

    // Socket.IO event handlers
    socket.on('dice_rolled', ({ player, value, state }) => {
      info(`Player ${player} rolled a ${value}`);
      renderState(state);
    });
    socket.on('token_moved', ({ event, state }) => {
      info(`Token moved: player=${event.player} token=${event.tokenIndex} square=${event.square}`);
      renderState(state);
    });
    socket.on('token_captured', ({ event, state }) => {
      info(`CAPTURE: Player ${event.player} sent token=${event.capturedTokenIndex} back to house!`);
      renderState(state);
    });
    socket.on('game_over', ({ event, state }) => {
      info(`GAME OVER! Player ${event.winner} wins!`);
      renderState(state);
    });
    socket.on('joined_room', ({ state }) => {
      info(`Joined room. Players: ${state.players.length}/${state.player_count}`);
      renderState(state);
    });
    socket.on('error', ({ message }) => { info(`ERROR: ${message}`); });

    // Button handlers
    document.getElementById('btnCreate').onclick = async () => {
      const data = await api('/games', { method: 'POST', body: { player_count: 2, host_name: 'Alice' } });
      currentGame = data.game_id;
      myPlayerId = data.host_id;
      document.getElementById('gameIdInput').value = currentGame;
      socket.emit('join_room', { game_id: currentGame });
      info(`Game created: ${currentGame}`);
      renderState(data.state);
    };

    document.getElementById('btnJoin').onclick = async () => {
      const gameId = document.getElementById('gameIdInput').value;
      if (!gameId) { info('Enter a game ID first'); return; }
      const data = await api(`/games/${gameId}/join`, { method: 'POST', body: { name: 'Bob' } });
      myPlayerId = data.player_id;
      currentGame = gameId;
      socket.emit('join_room', { game_id: gameId });
      info(`Joined game: ${gameId}`);
      renderState(data.state);
    };

    document.getElementById('btnRoll').onclick = async () => {
      if (!currentGame) { info('Create or join a game first'); return; }
      const data = await api(`/games/${currentGame}/roll`, { method: 'POST', body: { player_id: myPlayerId } });
      renderState(data.state);
    };
  </script>
</body>
</html>

# ---- Base stage: install all dependencies ----
FROM node:20-slim AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# ---- Builder stage: run tests and linting ----
FROM base AS builder
COPY package*.json ./
RUN npm install
COPY tests/ ./tests/
RUN npm test

# ---- Production stage: minimal runtime image ----
FROM node:20-slim
WORKDIR /app
COPY --from=base /app/node_modules ./node_modules
COPY src/ ./src/
COPY public/ ./public/

# Non-root user for security (Docker best practice)
RUN groupadd -r ludo && useradd -r -g ludo ludo
USER ludo

EXPOSE 3000
ENV NODE_ENV=production
ENV PORT=3000

CMD ["node", "src/index.js"]

version: '3.9'

services:
  # Development profile: mounts source as a volume for hot reload
  ludo-dev:
    build:
      context: .
      target: builder
    ports:
      - "3000:3000"
    volumes:
      - ./src:/app/src:ro
      - ./public:/app/public:ro
    environment:
      - NODE_ENV=development
      - PORT=3000
    command: node src/index.js
    profiles:
      - dev

  # Production profile: runs the optimized production image
  ludo-server:
    build:
      context: .
      target: production
    ports:
      - "3000:3000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/games/Health/state"] || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LUDOKING_API_KEY=${LUDOKING_API_KEY}
    profiles:
      - prod

# Development (hot reload via volume mounts)
docker-compose --profile dev up --build

# Production (optimized production image)
LUDOKING_API_KEY=your_key_here docker-compose --profile prod up --build -d

# Verify the container is running
docker ps | grep ludo-server