brick-engine-js 1.0.1 → 1.0.2

package/src/core/Game.ts

@@ -1,307 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,116 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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);
-        }
-    }
-}