brick-engine-js 1.0.1

package/src/core/Game.ts

@@ -0,0 +1,307 @@
+import p5 from 'p5';
+import type GameView from '../view/GameView';
+import GameControl from './module/control/GameControl';
+import GameGrid from './module/grid/GameGrid';
+import GameRenderer from './module/renderer/GameRenderer';
+import GameState from './module/state/GameState';
+import GameText from './module/text/GameText';
+import GameTime from './module/time/GameTime';
+import GameSound from './module/sound/GameSound';
+import GameScore from './module/score/GameScore';
+
+import { Initializable } from './types/Interfaces';
+import { ControlEventType, ControlKey, GameModules, StateProperty } from './types/Types';
+import GameHudGrid from './module/grid/GameHudGrid';
+import InterfaceIdentifierHelper from './helpers/InterfaceIdentifierHelper';
+import InitialStateSnapshot from './InitialStateSnapshot';
+import GameSession from './module/session/GameSession';
+
+/**
+ * Base abstract class for the game.
+ *
+ * It manages the game loop, initialization of core modules, and integration with p5.js.
+ * All game logic should be implemented in subclasses by overriding `processTick` and `processFrame`.
+ */
+export default abstract class Game implements Initializable {
+    protected _p: p5;
+    protected _view: GameView;
+
+    private _modules: GameModules = undefined as unknown as GameModules;
+
+    private _initialStateSnapshot = new InitialStateSnapshot();
+
+    private _gameId: string = 'unknown';
+
+    private _switchHandler: (newGame: Game) => void = undefined as unknown as (newGame: Game) => void;
+
+    /**
+     * Gets the game ID
+     */
+    get gameId(): string {
+        return this._gameId;
+    }
+
+    /**
+     * Sets the game ID
+     */
+    set gameId(id: string) {
+        this._gameId = id;
+    }
+
+    /**
+     * Registers the callback to be used when a game requests to switch to another game.
+     * This is typically called by the engine's main loop (index.ts).
+     * @param handler The callback function.
+     */
+    setSwitchHandler(handler: (newGame: Game) => void) {
+        this._switchHandler = handler;
+    }
+
+    /**
+     * Propagates the switch handler to the new game.
+     * @param game Game instance that has the switch handler.
+     */
+    propagateSwitchHandler(game: Game) {
+        this.setSwitchHandler(game._switchHandler);
+    }
+
+    /**
+     * Creates an instance of the Game.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {GameView} view - The view strategy associated with this game.
+     */
+    constructor(p: p5, view: GameView) {
+        this._p = p;
+        this._view = view;
+        this._initialStateSnapshot.captureBaseProperties(this);
+    }
+
+    /**
+     * Gets the game view.
+     *
+     * @returns {GameView} The game view instance.
+     */
+    get view(): GameView {
+        return this._view;
+    }
+
+    /**
+     * Switches execution to a new game instance.
+     * Use this instead of global window methods.
+     *
+     * @param {Game} newGame - The new game instance to load.
+     */
+    switchGame(newGame: Game): void {
+        this.destroy(); // Clean up current game
+        if (this._switchHandler) {
+            this._switchHandler(newGame);
+        } else {
+            console.error('Game switch handler not registered. Cannot switch game.');
+        }
+    }
+
+    /**
+     * Gets the game modules.
+     *
+     * @returns {GameModules} The collection of initialized game modules.
+     */
+    get modules(): GameModules {
+        return this._modules;
+    }
+
+    /**
+     * Sets up the game, initializing all modules and viewing components.
+     * Called automatically by the engine key sequence.
+     */
+    setup() {
+        this._view.build();
+
+        this._modules = {
+            renderer: new GameRenderer(this._p),
+            grid: new GameGrid(),
+            hudGrid: new GameHudGrid(),
+            text: new GameText(this._p),
+            state: new GameState(),
+            control: new GameControl(),
+            time: new GameTime(),
+            sound: new GameSound(),
+            score: new GameScore(),
+            session: new GameSession(),
+        };
+
+        Object.values(this._modules).forEach(module => {
+            if (InterfaceIdentifierHelper.isInitializable(module)) {
+                module.setup();
+            }
+        });
+
+        Object.values(this._modules).forEach(module => {
+            if (InterfaceIdentifierHelper.isStateSyncable(module)) {
+                module.syncState(this._modules.state);
+            }
+        });
+
+        Object.values(this._modules).forEach(module => {
+            if (InterfaceIdentifierHelper.isSerializable(module)) {
+                this._modules.session.register(module);
+            }
+        });
+
+        const { text, control, renderer, session } = this._modules;
+
+        session.gameId = this.gameId;
+        session.setShowModalFunction(this._view.showSessionModal.bind(this._view));
+
+        control.setModules(this._modules);
+
+        text.setRendererMetrics(renderer.rendererMetrics);
+
+        this.setupGame();
+        this._initialStateSnapshot.captureInitialState(this);
+
+        this._subscribeSystemControls();
+
+        this._view.bindControls(control);
+    }
+
+    /**
+     * Main draw loop, called by p5.js.
+     * Handles time updates, logic ticks, and rendering.
+     */
+    draw() {
+        if (!this._modules) return;
+
+        const { renderer, grid, time, state } = this._modules;
+
+        renderer.render(grid.getGrid(), this._modules);
+        if (state.isOn()) {
+            if (!state.isStarted()) {
+                this.drawTitleScreen();
+            } else if (state.isPlaying()) {
+                time.update(this._p.deltaTime);
+                // Update time accumulator
+
+                // Process Logic Tick
+                if (time.shouldTick()) {
+                    this.update(this._p.deltaTime);
+
+                    this._modules.session.saveSession();
+                }
+
+                this.render();
+            } else if (state.isPaused()) {
+                this.render();
+            }
+
+            if (state.isGameOver()) {
+                this.drawGameOverScreen();
+            }
+        }
+    }
+
+    /**
+     * Destroys the game instance, cleaning up all event listeners and stopping the loop.
+     * Call this before switching to another game or when the game is no longer needed.
+     */
+    destroy() {
+        this._p.noLoop();
+
+        if (this._modules) {
+            this._modules.control.unbindControls();
+            this._modules.sound.stopAll();
+        }
+    }
+
+    get p() {
+        return this._p;
+    }
+
+    /**
+     * Abstract method for processing game logic.
+     * Called every tick, but ONLY when the game is in the 'playing' state.
+     *
+     * @param {number} deltaTime - Time elapsed since last tick.
+     */
+    abstract update(deltaTime: number): void;
+
+    /**
+     * Abstract method for processing visual frames.
+     * Called every frame (depending on frameInterval).
+     */
+    abstract render(): void;
+
+    /**
+     * Abstract method for setting up the game specific logic.
+     * Called after the game modules are initialized.
+     */
+    abstract setupGame(): void;
+
+    /**
+     * Abstract method for drawing the Title Screen (Welcome).
+     * Called when the game is ON but not yet STARTED.
+     */
+    abstract drawTitleScreen(): void;
+
+    /**
+     * Abstract method for drawing the Game Over Screen.
+     * Called when the game is in GAME OVER state.
+     */
+    abstract drawGameOverScreen(): void;
+
+    private _subscribeSystemControls(): void {
+        const { control, state, grid } = this._modules;
+
+        control.subscribe(ControlKey.POWER, ControlEventType.PRESSED, () => {
+            if (state.isOn()) {
+                state.turnOff();
+                this.modules.sound.stopAll();
+            } else {
+                state.turnOn();
+            }
+        });
+        control.subscribe(ControlKey.SOUND, ControlEventType.PRESSED, () => state.toggleMuted());
+        control.subscribe(ControlKey.COLOR, ControlEventType.PRESSED, () => state.toggleColorEnabled());
+
+        control.subscribe(ControlKey.RESET, ControlEventType.PRESSED, () => {
+            grid.resetGrid();
+            this.modules.score.resetScore();
+            this.modules.score.resetLevel();
+            this.modules.time.reset();
+            this._modules.session.clearSession();
+            state.resetGame();
+            this._initialStateSnapshot.restoreInitialState(this);
+        });
+
+        control.subscribe(ControlKey.EXIT, ControlEventType.PRESSED, () => {
+            this._modules.session.clearSession();
+        });
+
+        control.subscribe(ControlKey.START_PAUSE, ControlEventType.PRESSED, () => {
+            if (!state.isStarted()) {
+                state.startGame();
+            } else if (state.isPlaying()) {
+                state.pause();
+            } else if (state.isPaused()) {
+                state.resume();
+            } else if (state.isGameOver()) {
+                grid.resetGrid();
+                this.modules.score.resetScore();
+                this.modules.score.resetLevel();
+                this.modules.time.reset();
+                this.modules.session.clearSession();
+                this._initialStateSnapshot.restoreInitialState(this);
+                state.resetGameOver();
+            }
+        });
+
+        state.subscribe(StateProperty.ON, isOn => {
+            if (!isOn) {
+                grid.resetGrid();
+                this.modules.score.resetScore();
+                this.modules.score.resetLevel();
+                this.modules.time.reset();
+            }
+        });
+    }
+}

package/src/core/InitialStateSnapshot.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from 'vitest';
+import InitialStateSnapshot from './InitialStateSnapshot';
+
+describe('InitialStateSnapshot', () => {
+    it('should ignore base properties and capture custom client properties using structuredClone', () => {
+        // [ARRANGE]
+        const snapshot = new InitialStateSnapshot();
+        const instance: Record<string, unknown> = {
+            _baseProp: 'base',
+            setupGame: () => {},
+        };
+
+        // [ACT]
+        snapshot.captureBaseProperties(instance);
+        instance.customNumber = 42;
+        instance.customArray = [1, 2, 3];
+        snapshot.captureInitialState(instance);
+
+        instance.customNumber = 100;
+        (instance.customArray as number[]).push(4);
+
+        snapshot.restoreInitialState(instance);
+
+        // [ASSERT]
+        expect(instance.customNumber).toBe(42);
+        expect(instance.customArray).toEqual([1, 2, 3]);
+        expect(instance._baseProp).toBe('base');
+    });
+
+    it('should fallback to reference if structuredClone fails', () => {
+        // [ARRANGE]
+        const snapshot = new InitialStateSnapshot();
+        const instance: Record<string, unknown> = { _base: true };
+        snapshot.captureBaseProperties(instance);
+
+        // Object containing a function throws DataCloneError in structuredClone
+        const uncloneableObj: Record<string, unknown> = { func: () => {} };
+        instance.uncloneable = uncloneableObj;
+
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+        // [ACT]
+        snapshot.captureInitialState(instance);
+
+        // [ASSERT]
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to clone property uncloneable:'), expect.any(Error));
+
+        // Cleanup spy
+        consoleSpy.mockRestore();
+    });
+});

package/src/core/InitialStateSnapshot.ts

@@ -0,0 +1,46 @@
+export default class InitialStateSnapshot {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private _initialState: Map<string, any> = new Map();
+    private _baseProperties: string[] = [];
+
+    /**
+     * Captures the base properties of the instance before any custom client properties are added.
+     * @param instance The object instance to extract keys from.
+     */
+    captureBaseProperties(instance: object): void {
+        this._baseProperties = Object.keys(instance);
+    }
+
+    /**
+     * Stores the initial state of custom client properties.
+     * @param instance The object instance containing custom properties.
+     */
+    captureInitialState(instance: object): void {
+        console.log('capturing initial state for snapshot');
+        Object.entries(instance).forEach(([key, value]) => {
+            if (!this._baseProperties.includes(key) && typeof value !== 'function') {
+                let initialValue = value;
+                try {
+                    initialValue = structuredClone(value);
+                    console.log('capturing property', key, initialValue);
+                } catch (e) {
+                    console.error(`Failed to clone property ${key}:`, e);
+                }
+                this._initialState.set(key, initialValue);
+            }
+        });
+    }
+
+    /**
+     * Restores the captured custom properties back to the instance.
+     * @param instance The object instance to restore properties onto.
+     */
+    restoreInitialState(instance: object): void {
+        console.log('restoring initial snapshot');
+        this._initialState.forEach((value, key) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (instance as any)[key] = value;
+            console.log('restoring property', key, value);
+        });
+    }
+}

package/src/core/helpers/CellHelper.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import CellHelper from './CellHelper';
+import { Color } from '../types/enums';
+
+describe('CellHelper', () => {
+    describe('emptyCell', () => {
+        it('should create an empty cell with value 0 and default color at the given coordinate', () => {
+            // [ARRANGE]
+            const coordinate = { x: 10, y: 20 };
+
+            // [ACT]
+            const result = CellHelper.emptyCell(coordinate);
+
+            // [ASSERT]
+            expect(result).toEqual({
+                value: 0,
+                color: Color.DEFAULT,
+                coordinate: { x: 10, y: 20 },
+            });
+        });
+
+        it('should maintain the reference to the coordinates provided', () => {
+            // [ARRANGE]
+            const coordinate = { x: 5, y: 5 };
+
+            // [ACT]
+            const result = CellHelper.emptyCell(coordinate);
+
+            // [ASSERT]
+            expect(result.coordinate).toBe(coordinate);
+        });
+    });
+});

package/src/core/helpers/CellHelper.ts

@@ -0,0 +1,21 @@
+import { Color } from '../types/enums';
+import { Cell, Coordinate } from '../types/Types';
+
+/**
+ * Utility class for creating and managing grid cells.
+ */
+export default class CellHelper {
+    /**
+     * Creates a new empty cell at the specified coordinate.
+     *
+     * @param {Coordinate} coordinate - The location of the new cell.
+     * @returns {Cell} A new cell object initialized with value 0 and default color.
+     */
+    static emptyCell(coordinate: Coordinate): Cell {
+        return {
+            value: 0,
+            color: Color.DEFAULT,
+            coordinate,
+        };
+    }
+}

package/src/core/helpers/ControlInputHandlerHelper.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import ControlInputHandlerHelper from './ControlInputHandlerHelper';
+import { ControlKey, ControlEventType } from '../types/Types';
+import { Control } from '../types/modules';
+
+// [ARRANGE] Mock configs
+vi.mock('../../config/configs', () => ({
+    default: {
+        buttonHold: {
+            holdDelayMs: 200,
+            holdIntervalMs: 50,
+        },
+    },
+}));
+
+describe('ControlInputHandlerHelper', () => {
+    let handler: ControlInputHandlerHelper;
+    let mockControl: Control;
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        mockControl = {
+            notify: vi.fn(),
+        } as unknown as Control;
+        handler = new ControlInputHandlerHelper(mockControl);
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe('handlePress', () => {
+        it('should notify PRESSED immediately when key is pressed', () => {
+            // [ACT]
+            handler.handlePress(ControlKey.LEFT);
+
+            // [ASSERT]
+            expect(mockControl.notify).toHaveBeenCalledWith(ControlKey.LEFT, ControlEventType.PRESSED);
+        });
+
+        it('should not notify PRESSED if the same key is already active', () => {
+            // [ARRANGE]
+            handler.handlePress(ControlKey.LEFT);
+            vi.mocked(mockControl.notify).mockClear();
+
+            // [ACT]
+            handler.handlePress(ControlKey.LEFT);
+
+            // [ASSERT]
+            expect(mockControl.notify).not.toHaveBeenCalled();
+        });
+
+        it('should start notifying HELD after the hold delay', () => {
+            // [ACT]
+            handler.handlePress(ControlKey.LEFT);
+
+            // Fast-forward past delay
+            vi.advanceTimersByTime(200); // holdDelayMs
+
+            // Fast-forward through one interval
+            vi.advanceTimersByTime(50); // holdIntervalMs
+
+            // [ASSERT]
+            expect(mockControl.notify).toHaveBeenCalledWith(ControlKey.LEFT, ControlEventType.HELD);
+        });
+
+        it('should continue notifying HELD on every interval', () => {
+            // [ACT]
+            handler.handlePress(ControlKey.LEFT);
+            vi.advanceTimersByTime(200); // skip delay
+
+            vi.advanceTimersByTime(150); // 3 intervals
+
+            // [ASSERT]
+            // 1 (PRESSED) + 3 (HELD) = 4 notifications
+            expect(mockControl.notify).toHaveBeenCalledTimes(4);
+            expect(mockControl.notify).toHaveBeenLastCalledWith(ControlKey.LEFT, ControlEventType.HELD);
+        });
+    });
+
+    describe('handleRelease', () => {
+        it('should stop notifications and cleanup when key is released', () => {
+            // [ARRANGE]
+            handler.handlePress(ControlKey.LEFT);
+            vi.advanceTimersByTime(200); // delay
+            vi.advanceTimersByTime(50); // 1 held
+            expect(mockControl.notify).toHaveBeenCalledTimes(2);
+
+            // [ACT]
+            handler.handleRelease(ControlKey.LEFT);
+            vi.advanceTimersByTime(100); // advance time more
+
+            // [ASSERT]
+            expect(mockControl.notify).toHaveBeenCalledTimes(2); // Still 2
+        });
+
+        it('should handle release for a key that was not pressed gracefully', () => {
+            // [ACT & ASSERT]
+            expect(() => handler.handleRelease(ControlKey.RIGHT)).not.toThrow();
+        });
+
+        it('should cancel delay timer if released before it completes', () => {
+            // [ARRANGE]
+            handler.handlePress(ControlKey.LEFT);
+
+            // [ACT]
+            vi.advanceTimersByTime(100); // Half-way through delay
+            handler.handleRelease(ControlKey.LEFT);
+            vi.advanceTimersByTime(200); // Complete what would have been the delay
+
+            // [ASSERT]
+            expect(mockControl.notify).toHaveBeenCalledTimes(1); // Only PRESSED
+            expect(mockControl.notify).not.toHaveBeenCalledWith(ControlKey.LEFT, ControlEventType.HELD);
+        });
+    });
+});

package/src/core/helpers/ControlInputHandlerHelper.ts

@@ -0,0 +1,68 @@
+import { ControlEventType, ControlKey } from '../types/Types';
+import { Control } from '../types/modules';
+import configs from '../../config/configs';
+
+/**
+ * Helper class that standardizes input handling logic.
+ * It manages the distinction between single 'press' events and continuous 'hold' events
+ * for both keyboard and UI button inputs.
+ */
+export default class ControlInputHandlerHelper {
+    private _control: Control;
+    private _activeKeys: Map<ControlKey, { delay: NodeJS.Timeout; hold: NodeJS.Timeout }> = new Map();
+
+    /**
+     * Creates an instance of the input handler.
+     *
+     * @param {Control} control - The control module instance to notify.
+     */
+    constructor(control: Control) {
+        this._control = control;
+    }
+
+    /**
+     * Processes a key down or button press action.
+     * Triggers an immediate {@link ControlEventType.PRESSED} event, and schedules
+     * a {@link ControlEventType.HELD} loop if the key remains active.
+     *
+     * @param {ControlKey} key - The identity of the control key being pressed.
+     */
+    handlePress(key: ControlKey): void {
+        if (this._activeKeys.has(key)) return; // Prevent double handling
+
+        // 1. Notify Pressed
+        this._control.notify(key, ControlEventType.PRESSED);
+
+        // 2. Schedule Hold
+        const delayTimer = setTimeout(() => {
+            const holdTimer = setInterval(() => {
+                this._control.notify(key, ControlEventType.HELD);
+            }, configs.buttonHold.holdIntervalMs);
+
+            // Update map with hold timer
+            const timers = this._activeKeys.get(key);
+            if (timers) {
+                timers.hold = holdTimer;
+            }
+        }, configs.buttonHold.holdDelayMs);
+
+        this._activeKeys.set(key, { delay: delayTimer, hold: null });
+    }
+
+    /**
+     * Processes a key up or button release action.
+     * Cancels any pending hold timers and cleans up the active key state.
+     *
+     * @param {ControlKey} key - The identity of the control key being released.
+     */
+    handleRelease(key: ControlKey): void {
+        const timers = this._activeKeys.get(key);
+        if (timers) {
+            clearTimeout(timers.delay);
+            if (timers.hold) {
+                clearInterval(timers.hold);
+            }
+            this._activeKeys.delete(key);
+        }
+    }
+}