Ludo Game Tutorial: Board Coordinates, Movement Algorithm & Dice Probability

const PLAYER_COLORS = ['RED', 'GREEN', 'YELLOW', 'BLUE'];

// Home entry index into the absolute OUTER_TRACK for each player
const HOME_ENTRY = { RED: 0, GREEN: 13, YELLOW: 26, BLUE: 39 };
const WIN_POSITION = 57;
const OUTER_TRACK_LEN = 52;

// Star/safe squares: indices 8, 21, 34, 47 in the absolute track
const SAFE_SQUARES = new Set([8, 21, 34, 47]);

function toAbsoluteTrack(relPos, playerId) {
    // Convert player's relative track position (0-57) to absolute (0-51)
    return (relPos + HOME_ENTRY[playerId]) % OUTER_TRACK_LEN;
}

function getMoveCandidates(player, diceValue) {
    const candidates = [];

    for (const piece of player.pieces) {
        if (piece.finished) continue;

        // Rule: piece in base needs exactly 6 to exit
        if (piece.trackPos === -1) {
            if (diceValue === 6) {
                candidates.push({ piece, moveType: 'LEAVE_BASE', targetPos: 0, priority: 3 });
            }
            continue;
        }

        // Rule: cannot overshoot the finish
        const newPos = piece.trackPos + diceValue;
        if (newPos > WIN_POSITION) continue;

        // Rule: self-collision check — cannot land on own piece
        const selfBlocked = player.pieces.some(
            p => p !== piece && !p.finished && p.trackPos === newPos
        );
        if (selfBlocked) continue;

        // Classify the move
        let moveType = 'ADVANCE';
        let priority = 6;

        // Check for capture opportunity
        const absTarget = toAbsoluteTrack(newPos, player.id);
        const opponentOnSquare = findOpponentAtAbsolute(absTarget, player.id);
        if (opponentOnSquare && !isSafeSquare(absTarget)) {
            moveType = 'CAPTURE';
            priority = 1;
        }

        // Check for home column entry
        if (piece.trackPos < OUTER_TRACK_LEN && newPos >= OUTER_TRACK_LEN) {
            moveType = 'ENTER_HOME';
            priority = Math.max(priority, 2);
        }

        // Check for safe square landing
        if (isSafeSquare(absTarget) && moveType === 'ADVANCE') {
            moveType = 'SAFE_SQUARE';
            priority = 4;
        }

        candidates.push({ piece, moveType, targetPos: newPos, priority });
    }

    // Sort by priority (lowest number = highest priority)
    candidates.sort((a, b) => a.priority - b.priority);
    return candidates;
}

function findOpponentAtAbsolute(absTrackPos, ownPlayerId) {
    // Returns opponent player ID if one occupies the absolute track position
    for (const player of gameState.players) {
        if (player.id === ownPlayerId) continue;
        for (const piece of player.pieces) {
            if (piece.finished || piece.trackPos < 0) continue;
            if (toAbsoluteTrack(piece.trackPos, player.id) === absTrackPos) {
                return player.id;
            }
        }
    }
    return null;
}

function isSafeSquare(absTrackPos) {
    return SAFE_SQUARES.has(absTrackPos);
}

const SINGLE_PROB = 1 / 6; // ~16.67% per face

// Probability of getting exactly N consecutive 6s
function probConsecutiveSixes(n) {
    return Math.pow(SINGLE_PROB, n);
}

// P(exactly one 6 in exactly one roll) = 1/6 ≈ 16.67%
// P(exactly one 6 in N rolls) = N * (1/6) * (5/6)^(N-1)
function probAtLeastOneSix(nRolls) {
    return 1 - Math.pow(5 / 6, nRolls);
}

// Three consecutive 6s: P = (1/6)^3 = 0.46% — rare but consequential
// After 2 consecutive 6s, P(third is also 6) = 16.67%
// After 2 consecutive 6s, P(at least one non-6 in next N rolls) → approaches 1

// Build a probability-weighted move score for AI evaluation
function expectedProgress(piece, diceDist = [1,1,1,1,1,1]) {
    // diceDist: weighted die (default = fair die)
    let total = 0;
    for (const [value, weight] of diceDist.entries()) {
        if (isValidMove(piece, value)) {
            total += weight * value;
        }
    }
    return total / diceDist.reduce((a, b) => a + b, 0);
}

// Monte Carlo: estimate turns-to-finish for a piece
async function monteCarloTurnsToFinish(startPos, trials = 100000) {
    let totalTurns = 0;
    let consecSix = 0;
    for (let t = 0; t < trials; t++) {
        let pos = startPos;
        let turns = 0;
        let consec = 0;
        while (pos < WIN_POSITION && turns < 500) {
            const roll = Math.floor(Math.random() * 6) + 1;
            consec = (roll === 6) ? consec + 1 : 0;
            if (consec >= 3) { consec = 0; continue; }
            if (pos === -1 && roll !== 6) { turns++; continue; }
            if (pos + roll <= WIN_POSITION) {
                pos += roll;
            }
            turns++;
        }
        totalTurns += turns;
    }
    return totalTurns / trials;
}

const ANIM_CONFIG = {
    SQUARE_STEP_MS:  120,   // ms per square for piece movement
    DICE_ROLL_MS:    800,   // total dice roll animation duration
    CAPTURE_MS:      600,   // capture retreat animation
    HOME_ENTRY_MS:   400,   // celebration pulse on home entry
    SETTLE_MS:       200,   // pause between animations
    SCALE_BOUNCE:    1.15,  // piece scale during bounce
};

class LudoAnimationController {
    constructor(canvasCtx) {
        this.ctx = canvasCtx;
        this.queue = [];
        this.running = false;
        this.currentAnim = null;
    }

    enqueue(anim) {
        this.queue.push(anim);
        if (!this.running) this.processQueue();
    }

    processQueue() {
        if (this.queue.length === 0) {
            this.running = false;
            this.emit('allAnimationsComplete');
            return;
        }
        this.running = true;
        this.currentAnim = this.queue.shift();
        this.runAnimation(this.currentAnim)
            .then(() => {
                this.emit(this.currentAnim.type + ':complete', this.currentAnim);
                return this.wait(ANIM_CONFIG.SETTLE_MS);
            })
            .then(() => this.processQueue());
    }

    runAnimation(anim) {
        switch (anim.type) {
            case 'ROLL':
                return this.animateDiceRoll(anim);
            case 'MOVE':
                return this.animatePieceMove(anim);
            case 'CAPTURE':
                return this.animateCapture(anim);
            case 'HOME_ENTRY':
                return this.animateHomeEntry(anim);
        }
    }

    animateDiceRoll(anim) {
        return new Promise(resolve => {
            const duration = ANIM_CONFIG.DICE_ROLL_MS;
            const fps = 30;
            const frames = (duration / 1000) * fps;
            let frame = 0;
            const interval = setInterval(() => {
                const value = Math.floor(Math.random() * 6) + 1;
                this.renderDiceFace(value);
                if (++frame >= frames) {
                    clearInterval(interval);
                    this.renderDiceFace(anim.result);
                    resolve();
                }
            }, 1000 / fps);
        });
    }

    animatePieceMove(anim) {
        return new Promise(resolve => {
            const steps = Math.abs(anim.toPos - anim.fromPos);
            const stepDuration = ANIM_CONFIG.SQUARE_STEP_MS;
            const totalDuration = steps * stepDuration;
            const startTime = performance.now();
            const fromCoord = getTrackCoordinate(anim.fromPos, anim.playerId);
            const toCoord = getTrackCoordinate(anim.toPos, anim.playerId);

            const animate = (now) => {
                const elapsed = now - startTime;
                const t = Math.min(elapsed / totalDuration, 1);
                const eased = easeInOutQuad(t);
                const currentStep = Math.floor(eased * steps);
                const segmentT = (eased * steps) - currentStep;
                const fromSq = getTrackCoordinate(anim.fromPos + currentStep, anim.playerId);
                const toSq = getTrackCoordinate(anim.fromPos + currentStep + 1, anim.playerId);
                const x = lerp(fromSq.x, toSq.x, segmentT);
                const y = lerp(fromSq.y, toSq.y, segmentT);
                this.renderPiece(anim.pieceId, x, y);
                if (t < 1) requestAnimationFrame(animate);
                else resolve();
            };
            requestAnimationFrame(animate);
        });
    }

    function lerp(a, b, t) { return a + (b - a) * t; }
    function easeInOutQuad(t) { return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2; }

    wait(ms) { return new Promise(r => setTimeout(r, ms)); }
    emit(type, data) { this.dispatchEvent && this.dispatchEvent(new CustomEvent(type, { detail: data })); }
}

function runLudoTestSuite() {
    const results = [];
    const test = (name, fn) => {
        try {
            fn();
            results.push({ name, pass: true });
            console.log('✅', name);
        } catch (e) {
            results.push({ name, pass: false, error: e.message });
            console.error('❌', name, e.message);
        }
    };

    // --- Board Coordinate Tests ---
    test('OUTER_TRACK has exactly 52 cells', () => {
        assertEqual(OUTER_TRACK.length, 52, 'Track length must be 52');
    });

    test('Home entry indices are spaced 13 apart', () => {
        assertEqual(HOME_ENTRY.GREEN - HOME_ENTRY.RED, 13);
        assertEqual(HOME_ENTRY.YELLOW - HOME_ENTRY.GREEN, 13);
        assertEqual(HOME_ENTRY.BLUE - HOME_ENTRY.YELLOW, 13);
        assertEqual((HOME_ENTRY.RED + 52 - HOME_ENTRY.BLUE) % 52, 13);
    });

    test('Safe squares are at indices 8, 21, 34, 47', () => {
        const expected = [8, 21, 34, 47];
        expected.forEach(idx => assertEqual(SAFE_SQUARES.has(idx), true));
    });

    test('Track wraps correctly: Red pos 51 + 1 = Green pos 0', () => {
        const greenEntry = HOME_ENTRY.GREEN;
        const redLast = OUTER_TRACK[51];
        const greenFirst = OUTER_TRACK[greenEntry];
        assertEqual(toAbsoluteTrack(51, 'RED'), 51);
        assertEqual(toAbsoluteTrack(0, 'GREEN'), greenEntry);
    });

    // --- Movement Validation Tests ---
    test('Piece in base can only move with dice=6', () => {
        const piece = { trackPos: -1, finished: false };
        assertEqual(isValidMove(piece, 6), true);
        [1,2,3,4,5].forEach(v =>
            assertEqual(isValidMove(piece, v), false)
        );
    });

    test('Cannot overshoot WIN_POSITION (57)', () => {
        const piece = { trackPos: 55, finished: false };
        assertEqual(isValidMove(piece, 2), true);  // 55+2=57 exact
        assertEqual(isValidMove(piece, 3), false);  // 55+3=58 overshoot
        assertEqual(isValidMove({ trackPos: 56, finished: false }, 2), false);
        assertEqual(isValidMove({ trackPos: 56, finished: false }, 1), true);  // 56+1=57 exact
    });

    test('Finished piece cannot move', () => {
        assertEqual(isValidMove({ trackPos: 57, finished: true }, 6), false);
    });

    test('getMoveCandidates filters correctly for self-collision', () => {
        const player = {
            id: 'RED',
            pieces: [
                { trackPos: 10, finished: false },
                { trackPos: 10, finished: false } // same position — self-collision
            ]
        };
        const cands = getMoveCandidates(player, 3);
        assertEqual(cands.length, 0); // both blocked
    });

    test('Total path for each player is exactly 57 steps', () => {
        ['RED', 'GREEN', 'YELLOW', 'BLUE'].forEach(color => {
            const piece = { trackPos: 0, finished: false };
            let steps = 0;
            while (piece.trackPos < WIN_POSITION && steps < 200) {
                piece.trackPos++;
                steps++;
            }
            assertEqual(steps, 57, `${color} path should be 57 steps`);
        });
    });

    // --- Dice Rule Tests ---
    test(probConsecutiveSixes(3).toFixed(4) === (1/216).toFixed(4)
        ? 'Three consecutive 6s probability is (1/6)^3 = 0.0046'
        : assertFail('Three 6s probability incorrect')
    );

    const passed = results.filter(r => r.pass).length;
    const failed = results.filter(r => !r.pass).length;
    console.log(`\nResults: ${passed} passed, ${failed} failed`);
    return failed === 0;
}

function assertEqual(a, b, msg) {
    if (a !== b) throw new Error(msg || `Expected ${b}, got ${a}`);
}
function assertFail(msg) { throw new Error(msg); }