feat: game engine state machine with reducer pattern

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

_._ _..._ .-', _.._(`))
'-. ` ' /-._.-' ',/
) \ '.
/ _ _ | \
| a a / |
\ .-. ;
'-('' ).-' ,' ;
'-; | .'
\ \ /
| 7 .__ _.-\ \
| | | `` | |
/,_| | /,_/ /
/,_/ '----'

Piggy Benissy

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Simeon Garratt | www.simeongarratt.com | @SimeonGarratt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

src/lib/game/engine.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from "vitest";
+import { gameReducer, createInitialState } from "./engine";
+import type { ShuffledQuestion } from "./types";
+
+const mockQuestion = (id: string, difficulty: "easy" | "medium" | "hard" = "medium"): ShuffledQuestion => ({
+  id, category: "General", difficulty, questionText: `Question ${id}?`,
+  correctAnswer: "Correct", incorrectAnswers: ["Wrong1", "Wrong2", "Wrong3"],
+  allAnswers: ["Correct", "Wrong1", "Wrong2", "Wrong3"],
+});
+
+describe("createInitialState", () => {
+  it("creates idle state for quick-fire", () => {
+    const state = createInitialState("quick-fire", [mockQuestion("1")]);
+    expect(state.phase).toBe("idle");
+    expect(state.mode).toBe("quick-fire");
+    expect(state.score).toBe(0);
+    expect(state.currentQuestionIndex).toBe(0);
+  });
+});
+
+describe("gameReducer", () => {
+  it("START transitions from idle to playing", () => {
+    const state = createInitialState("quick-fire", [mockQuestion("1")]);
+    const next = gameReducer(state, { type: "START" });
+    expect(next.phase).toBe("playing");
+    expect(next.startedAt).not.toBeNull();
+  });
+
+  it("ANSWER_CORRECT increments score and streak", () => {
+    let state = createInitialState("quick-fire", [mockQuestion("1"), mockQuestion("2")]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 200 });
+    expect(state.score).toBe(200);
+    expect(state.streak).toBe(1);
+    expect(state.questionsCorrect).toBe(1);
+    expect(state.currentQuestionIndex).toBe(1);
+  });
+
+  it("ANSWER_WRONG resets streak to 0", () => {
+    let state = createInitialState("quick-fire", [mockQuestion("1"), mockQuestion("2")]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 100 });
+    state = gameReducer(state, { type: "ANSWER_WRONG" });
+    expect(state.streak).toBe(0);
+    expect(state.questionsCorrect).toBe(1);
+    expect(state.currentQuestionIndex).toBe(2);
+  });
+
+  it("ANSWER_WRONG in streak mode ends the game", () => {
+    let state = createInitialState("streak", [mockQuestion("1"), mockQuestion("2")]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "ANSWER_WRONG" });
+    expect(state.phase).toBe("finished");
+  });
+
+  it("answering last question finishes the game", () => {
+    let state = createInitialState("quick-fire", [mockQuestion("1")]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 100 });
+    expect(state.phase).toBe("finished");
+  });
+
+  it("TIME_UP finishes the game", () => {
+    let state = createInitialState("quick-fire", [mockQuestion("1")]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "TIME_UP" });
+    expect(state.phase).toBe("finished");
+  });
+
+  it("tracks streakMax across the game", () => {
+    let state = createInitialState("quick-fire", [
+      mockQuestion("1"), mockQuestion("2"), mockQuestion("3"), mockQuestion("4"),
+    ]);
+    state = gameReducer(state, { type: "START" });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 100 });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 100 });
+    state = gameReducer(state, { type: "ANSWER_WRONG" });
+    state = gameReducer(state, { type: "ANSWER_CORRECT", points: 100 });
+    expect(state.streakMax).toBe(2);
+    expect(state.streak).toBe(1);
+  });
+
+  it("NEXT_PHASE transitions challenge-me phases", () => {
+    let state = createInitialState("challenge-me", [mockQuestion("1")]);
+    state = gameReducer(state, { type: "START" });
+    expect(state.challengePhase).toBe("easy");
+    state = gameReducer(state, { type: "NEXT_PHASE" });
+    expect(state.challengePhase).toBe("medium");
+    state = gameReducer(state, { type: "NEXT_PHASE" });
+    expect(state.challengePhase).toBe("hard");
+    state = gameReducer(state, { type: "NEXT_PHASE" });
+    expect(state.phase).toBe("finished");
+  });
+});

src/lib/game/engine.ts

@@ -0,0 +1,112 @@
+import type { GameMode, GamePhase, ShuffledQuestion } from "./types";
+
+export type ChallengePhase = "easy" | "medium" | "hard";
+const CHALLENGE_PROGRESSION: ChallengePhase[] = ["easy", "medium", "hard"];
+
+/**
+ * The complete state of an in-progress game session.
+ */
+export interface GameState {
+  mode: GameMode;
+  phase: GamePhase;
+  questions: ShuffledQuestion[];
+  currentQuestionIndex: number;
+  score: number;
+  streak: number;
+  streakMax: number;
+  questionsCorrect: number;
+  startedAt: number | null;
+  finishedAt: number | null;
+  challengePhase: ChallengePhase;
+  lastAnswerCorrect: boolean | null;
+}
+
+/**
+ * All actions that can be dispatched to the game reducer.
+ */
+export type GameAction =
+  | { type: "START" }
+  | { type: "ANSWER_CORRECT"; points: number }
+  | { type: "ANSWER_WRONG" }
+  | { type: "TIME_UP" }
+  | { type: "NEXT_PHASE" }
+  | { type: "ADD_QUESTIONS"; questions: ShuffledQuestion[] };
+
+/**
+ * Creates the initial idle GameState for the given mode and question list.
+ */
+export function createInitialState(mode: GameMode, questions: ShuffledQuestion[]): GameState {
+  return {
+    mode, phase: "idle", questions, currentQuestionIndex: 0,
+    score: 0, streak: 0, streakMax: 0, questionsCorrect: 0,
+    startedAt: null, finishedAt: null, challengePhase: "easy", lastAnswerCorrect: null,
+  };
+}
+
+/**
+ * Pure reducer for the game state machine. Returns a new GameState given the
+ * current state and an action — never mutates the input state.
+ */
+export function gameReducer(state: GameState, action: GameAction): GameState {
+  switch (action.type) {
+    case "START":
+      return { ...state, phase: "playing", startedAt: Date.now() };
+
+    case "ANSWER_CORRECT": {
+      const newStreak = state.streak + 1;
+      const newIndex = state.currentQuestionIndex + 1;
+      const isFinished = newIndex >= state.questions.length;
+      return {
+        ...state,
+        score: state.score + action.points,
+        streak: newStreak,
+        streakMax: Math.max(state.streakMax, newStreak),
+        questionsCorrect: state.questionsCorrect + 1,
+        currentQuestionIndex: newIndex,
+        lastAnswerCorrect: true,
+        phase: isFinished ? "finished" : state.phase,
+        finishedAt: isFinished ? Date.now() : null,
+      };
+    }
+
+    case "ANSWER_WRONG": {
+      if (state.mode === "streak") {
+        return {
+          ...state,
+          streak: 0,
+          currentQuestionIndex: state.currentQuestionIndex + 1,
+          lastAnswerCorrect: false,
+          phase: "finished",
+          finishedAt: Date.now(),
+        };
+      }
+      const newIndex = state.currentQuestionIndex + 1;
+      const isFinished = newIndex >= state.questions.length;
+      return {
+        ...state,
+        streak: 0,
+        currentQuestionIndex: newIndex,
+        lastAnswerCorrect: false,
+        phase: isFinished ? "finished" : state.phase,
+        finishedAt: isFinished ? Date.now() : null,
+      };
+    }
+
+    case "TIME_UP":
+      return { ...state, phase: "finished", finishedAt: Date.now() };
+
+    case "NEXT_PHASE": {
+      const idx = CHALLENGE_PROGRESSION.indexOf(state.challengePhase);
+      if (idx >= CHALLENGE_PROGRESSION.length - 1) {
+        return { ...state, phase: "finished", finishedAt: Date.now() };
+      }
+      return { ...state, challengePhase: CHALLENGE_PROGRESSION[idx + 1]! };
+    }
+
+    case "ADD_QUESTIONS":
+      return { ...state, questions: [...state.questions, ...action.questions] };
+
+    default:
+      return state;
+  }
+}