brick-engine-js 1.0.1

package/src/core/module/state/GameState.ts

@@ -0,0 +1,339 @@
+import { Debuggable } from '../../types/Interfaces';
+import { State } from '../../types/modules';
+import { StateProperty } from '../../types/Types';
+
+type StateMetadata = {
+    defaultValue: boolean | number;
+    storageKey?: string;
+};
+
+// prettier-ignore
+const STATE_CONFIG: Record<StateProperty, StateMetadata> = {
+    [StateProperty.ON]              : { defaultValue: false },
+    [StateProperty.START]           : { defaultValue: false },
+    [StateProperty.PLAYING]         : { defaultValue: false },
+    [StateProperty.GAME_OVER]       : { defaultValue: false },
+    [StateProperty.COLOR_ENABLED]   : { defaultValue: true   , storageKey: 'colorEnabled' },
+    [StateProperty.MUTED]           : { defaultValue: false  , storageKey: 'muted'        },
+};
+
+/**
+ * Manages the core boolean states of the game and handles state-change events.
+ *
+ * Provides a central hub for tracking game lifecycle states (on, running, gameOver)
+ * and user preferences (color enabled).
+ *
+ *
+ * **Persistence Responsibility:**
+ * This class is the SOLE responsible for persisting and loading generic, cross-session
+ * player preferences (like mute settings and color toggle) from LocalStorage.
+ * It does NOT handle transient session data (GameSession) or specific scoring logic (GameScore).
+ */
+export default class GameState implements State, Debuggable {
+    private _state: Map<StateProperty, boolean | number> = new Map();
+
+    /** Map to store property names and their associated subscription callbacks. */
+
+    private _subscribers: Map<StateProperty, Array<(value: boolean | number) => void>> = new Map();
+
+    /**
+     * Initializes the state module.
+     * Sets default values for all state properties and loads persisted data.
+     */
+    setup(): void {
+        // Initialize default values
+        Object.values(StateProperty).forEach(property => {
+            const config = STATE_CONFIG[property];
+            this._state.set(property, config.defaultValue);
+        });
+
+        this._loadPersistentState();
+    }
+
+    /**
+     * Loads persistent state from LocalStorage.
+     */
+    private _loadPersistentState(): void {
+        Object.values(StateProperty).forEach(property => {
+            const config = STATE_CONFIG[property];
+            if (config.storageKey) {
+                const storedValue = localStorage.getItem(config.storageKey);
+                if (storedValue !== null) {
+                    this._state.set(property, JSON.parse(storedValue));
+                }
+            }
+        });
+    }
+
+    /**
+     * Sets a state property value, handling persistence and notification.
+     *
+     * @param {StateProperty} property - The property to set.
+     * @param {boolean | number} value - The value to set.
+     */
+    private _set(property: StateProperty, value: boolean | number): void {
+        const currentValue = this._state.get(property);
+        if (currentValue !== value) {
+            this._state.set(property, value);
+
+            const config = STATE_CONFIG[property];
+            if (config.storageKey) {
+                localStorage.setItem(config.storageKey, JSON.stringify(value));
+            }
+
+            this._notify(property, value);
+        }
+    }
+
+    /**
+     * Notifies all subscribers of a property change.
+     *
+     * @param {StateProperty} property - The property that changed.
+     * @param {boolean | number} value - The new value of the property.
+     */
+    private _notify(property: StateProperty, value: boolean | number): void {
+        const callbacks = this._subscribers.get(property);
+        if (callbacks) {
+            callbacks.forEach(callback => callback(value));
+        }
+    }
+
+    /**
+     * Checks if the game machine is powered on.
+     *
+     * @returns {boolean} True if powered on.
+     */
+    isOn(): boolean {
+        return this._state.get(StateProperty.ON) as boolean;
+    }
+
+    /**
+     * Checks if the game machine is powered off.
+     *
+     * @returns {boolean} True if powered off.
+     */
+    isOff(): boolean {
+        return !this.isOn();
+    }
+
+    /**
+     * Checks if a game session has currently started.
+     * This includes both playing and paused states.
+     *
+     * @returns {boolean} True if a game is active.
+     */
+    isStarted(): boolean {
+        return this._state.get(StateProperty.START) as boolean;
+    }
+
+    /**
+     * Checks if the game is currently running (not paused, not game over).
+     *
+     * @returns {boolean} True if gameplay is active.
+     */
+    isPlaying(): boolean {
+        return this._state.get(StateProperty.PLAYING) as boolean;
+    }
+
+    /**
+     * Checks if the game is paused.
+     *
+     * @returns {boolean} True if the game is started but not playing (and not game over).
+     */
+    isPaused(): boolean {
+        return this.isStarted() && !this.isPlaying() && !this.isGameOver();
+    }
+
+    /**
+     * Checks if the game is in a "Game Over" state.
+     *
+     * @returns {boolean} True if the game is over.
+     */
+    isGameOver(): boolean {
+        return this._state.get(StateProperty.GAME_OVER) as boolean;
+    }
+
+    /**
+     * Powers on the game machine.
+     * Resets all session states (start, playing, game over).
+     */
+    turnOn(): void {
+        this._set(StateProperty.ON, true);
+        this._set(StateProperty.START, false);
+        this._set(StateProperty.PLAYING, false);
+        this._set(StateProperty.GAME_OVER, false);
+    }
+
+    /**
+     * Powers off the game machine.
+     * Resets all states.
+     */
+    turnOff(): void {
+        this._set(StateProperty.ON, false);
+        this._set(StateProperty.START, false);
+        this._set(StateProperty.PLAYING, false);
+        this._set(StateProperty.GAME_OVER, false);
+    }
+
+    /**
+     * Starts a new game session.
+     * Only works if the machine is powered on.
+     */
+    startGame(): void {
+        if (!this.isOn()) return;
+        this._set(StateProperty.START, true);
+        this._set(StateProperty.PLAYING, true);
+        this._set(StateProperty.GAME_OVER, false);
+    }
+
+    /**
+     * Resets the game over state and starts the game again.
+     */
+    resetGameOver(): void {
+        this._set(StateProperty.GAME_OVER, false);
+        this._set(StateProperty.START, true);
+        this._set(StateProperty.PLAYING, true);
+    }
+
+    /**
+     * Exits the current game session, returning to the "On" state.
+     */
+    exitGame(): void {
+        this._set(StateProperty.START, false);
+        this._set(StateProperty.PLAYING, false);
+        this._set(StateProperty.GAME_OVER, false);
+    }
+
+    /**
+     * Pauses the current game.
+     */
+    pause(): void {
+        if (this.isStarted() && !this.isGameOver()) {
+            this._set(StateProperty.PLAYING, false);
+        }
+    }
+
+    /**
+     * Resumes the game from a paused state.
+     */
+    resume(): void {
+        if (this.isStarted() && !this.isGameOver()) {
+            this._set(StateProperty.PLAYING, true);
+        }
+    }
+
+    /**
+     * Triggers the "Game Over" state.
+     * Stops gameplay.
+     */
+    triggerGameOver(): void {
+        this._set(StateProperty.PLAYING, false);
+        this._set(StateProperty.GAME_OVER, true);
+    }
+
+    /**
+     * Resets the game to the initial state (restarts).
+     */
+    resetGame(): void {
+        if (!this.isOn()) return;
+        this._set(StateProperty.GAME_OVER, false);
+        this._set(StateProperty.START, true);
+        this._set(StateProperty.PLAYING, true);
+    }
+
+    /**
+     * Checks if color mode is enabled.
+     *
+     * @returns {boolean} True if color is enabled.
+     */
+    isColorEnabled(): boolean {
+        return this._state.get(StateProperty.COLOR_ENABLED) as boolean;
+    }
+
+    /**
+     * Enables or disables color mode.
+     *
+     * @param {boolean} value - True to enable, false to disable.
+     */
+    setColorEnabled(value: boolean): void {
+        this._set(StateProperty.COLOR_ENABLED, value);
+    }
+
+    /**
+     * Checks if audio is muted.
+     *
+     * @returns {boolean} True if muted.
+     */
+    isMuted(): boolean {
+        return this._state.get(StateProperty.MUTED) as boolean;
+    }
+
+    /**
+     * Mutes or unmutes the audio.
+     *
+     * @param {boolean} value - True to mute, false to unmute.
+     */
+    setMuted(value: boolean): void {
+        this._set(StateProperty.MUTED, value);
+    }
+
+    /**
+     * Toggles the color enabled state.
+     */
+    toggleColorEnabled(): void {
+        this.setColorEnabled(!this.isColorEnabled());
+    }
+
+    /**
+     * Toggles the muted state.
+     */
+    toggleMuted(): void {
+        this.setMuted(!this.isMuted());
+    }
+
+    /**
+     * Subscribes to changes in specific state properties.
+     *
+     * @param {StateProperty} property - The state property to monitor.
+     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     */
+    subscribe(property: StateProperty, callback: (value: boolean | number) => void): void {
+        if (!this._subscribers.has(property)) {
+            this._subscribers.set(property, []);
+        }
+        this._subscribers.get(property)?.push(callback);
+    }
+
+    /**
+     * Unsubscribes from changes in specific state properties.
+     *
+     * @param {StateProperty} property - The state property to monitor.
+     * @param {function(boolean | number): void} callback - The function to remove.
+     */
+    unsubscribe(property: StateProperty, callback: (value: boolean | number) => void): void {
+        const callbacks = this._subscribers.get(property);
+        if (callbacks) {
+            this._subscribers.set(
+                property,
+                callbacks.filter(cb => cb !== callback),
+            );
+        }
+    }
+
+    /**
+     * Retrieves debug information about the game state.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean> {
+        return {
+            on: this.isOn(),
+            start: this.isStarted(),
+            playing: this.isPlaying(),
+            paused: this.isPaused(),
+            game_over: this.isGameOver(),
+            color_enabled: this.isColorEnabled(),
+            muted: this.isMuted(),
+        };
+    }
+}

package/src/core/module/text/GameText.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import GameText from './GameText';
+import p5 from 'p5';
+import { FontSize, FontAlign, FontVerticalAlign } from '../../types/enums';
+import CoordinateHelper from '../../helpers/CoordinateHelper';
+
+// [ARRANGE] Mock CoordinateHelper
+vi.mock('../../helpers/CoordinateHelper', () => ({
+    default: {
+        getHudPosX: vi.fn().mockReturnValue(10),
+        getHudPosY: vi.fn().mockReturnValue(20),
+        getDisplayPosX: vi.fn().mockReturnValue(30),
+        getDisplayPosY: vi.fn().mockReturnValue(40),
+    },
+}));
+
+describe('GameText', () => {
+    let gameText: GameText;
+    let mockP5: p5;
+
+    beforeEach(() => {
+        mockP5 = {
+            textFont: vi.fn(),
+            fill: vi.fn(),
+            textSize: vi.fn(),
+            textAlign: vi.fn(),
+            text: vi.fn(),
+            width: 1000,
+            height: 1000,
+        } as unknown as p5;
+
+        gameText = new GameText(mockP5);
+        gameText.setRendererMetrics({
+            display: { width: 600, height: 900, origin: { x: 0, y: 0 } },
+            hud: { width: 400, height: 900, origin: { x: 600, y: 0 } },
+            cell: { size: 50 },
+        });
+    });
+
+    describe('setup', () => {
+        it('should set font and calculate font sizes', () => {
+            // [ACT]
+            gameText.setup();
+
+            // [ASSERT]
+            expect(mockP5.textFont).toHaveBeenCalledWith('retro-gamming');
+            // Check if some sizes were set (e.g. textSize(FontSize.MEDIUM))
+            gameText.setTextSize(FontSize.MEDIUM);
+            expect(mockP5.textSize).toHaveBeenCalled();
+        });
+    });
+
+    describe('Rendering positions', () => {
+        beforeEach(() => {
+            gameText.setup();
+        });
+
+        it('should call CoordinateHelper.getHudPos and p5.text for HUD text', () => {
+            // [ACT]
+            gameText.textOnHud('Hello', { x: 0.5, y: 0.5 });
+
+            // [ASSERT]
+            expect(CoordinateHelper.getHudPosX).toHaveBeenCalled();
+            expect(mockP5.text).toHaveBeenCalledWith('Hello', 10, 20);
+        });
+
+        it('should call CoordinateHelper.getDisplayPos and p5.text for Display text', () => {
+            // [ACT]
+            gameText.textOnDisplay('Score', { x: 0.1, y: 0.1 });
+
+            // [ASSERT]
+            expect(CoordinateHelper.getDisplayPosX).toHaveBeenCalled();
+            expect(mockP5.text).toHaveBeenCalledWith('Score', 30, 40);
+        });
+    });
+
+    describe('Alignment & Sizing', () => {
+        it('should delegate to p5.textAlign and p5.textSize', () => {
+            // [ACT]
+            gameText.setTextAlign(FontAlign.CENTER, FontVerticalAlign.CENTER);
+            gameText.setTextSize(FontSize.LARGE);
+
+            // [ASSERT]
+            expect(mockP5.textAlign).toHaveBeenCalledWith(FontAlign.CENTER, FontVerticalAlign.CENTER);
+        });
+    });
+});

package/src/core/module/text/GameText.ts

@@ -0,0 +1,150 @@
+import p5 from 'p5';
+import configs from '../../../config/configs';
+import { FontSize, FontAlign, FontVerticalAlign } from '../../types/enums';
+import { Coordinate, RendererMetrics } from '../../types/Types';
+import { Debuggable } from '../../types/Interfaces';
+import CoordinateHelper from '../../helpers/CoordinateHelper';
+import RelativeValuesHelper from '../../helpers/RelativeValuesHelper';
+import { Text } from '../../types/modules';
+
+/**
+ * Handles text rendering and font management within the game.
+ *
+ * This class orchestrates font initialization, sizing, alignment, and
+ * provides methods to render text on specific areas (HUD or Display).
+ */
+export default class GameText implements Text, Debuggable {
+    /** The default font family used for game text. */
+    protected defaultFontFamily: string = 'retro-gamming';
+
+    /** Array containing pre-calculated font sizes in pixels. */
+    private fontSizes: number[] = [0];
+
+    /** Stores the current display metrics for relative positioning. */
+    private _rendererMetrics: RendererMetrics;
+
+    /** The p5 instance used for rendering. */
+    private _p: p5;
+
+    /**
+     * Creates an instance of GameText.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5) {
+        this._p = p;
+    }
+
+    // prettier-ignore
+    /**
+     * Setup the font and pre-calculates relative font sizes.
+     *
+     * Uses configuration values to define a set of pixel-perfect font sizes
+     * based on current container width.
+     */
+    setup(): void {
+        const { extraSmall, small, medium, large, extraLarge } = configs.screenLayout.fontSize;
+
+        this._p.textFont(this.defaultFontFamily);
+
+        // Define font sizes
+        this.fontSizes = [];
+
+        this.fontSizes[FontSize.EXTRA_SMALL] = RelativeValuesHelper.getRelativeWidth(this._p, extraSmall);
+        this.fontSizes[FontSize.SMALL]       = RelativeValuesHelper.getRelativeWidth(this._p, small);
+        this.fontSizes[FontSize.MEDIUM]      = RelativeValuesHelper.getRelativeWidth(this._p, medium);
+        this.fontSizes[FontSize.LARGE]       = RelativeValuesHelper.getRelativeWidth(this._p, large);
+        this.fontSizes[FontSize.EXTRA_LARGE] = RelativeValuesHelper.getRelativeWidth(this._p, extraLarge);
+    }
+
+    /**
+     * Sets the display metrics used for relative text positioning.
+     *
+     * @param {RendererMetrics} rendererMetrics - The current renderer dimensions and origin.
+     */
+    setRendererMetrics(rendererMetrics: RendererMetrics): void {
+        this._rendererMetrics = rendererMetrics;
+    }
+
+    /**
+     * Sets the fill color of the text based on its state.
+     *
+     * @param {boolean} state - Whether the text should use the active or inactive color.
+     */
+    protected setTextState(state: boolean): void {
+        const { active, inactive } = configs.colors;
+        this._p.fill(state ? active : inactive);
+    }
+
+    /**
+     * Sets the text color to the active theme color.
+     */
+    setActiveText(): void {
+        this.setTextState(true);
+    }
+
+    /**
+     * Sets the text color to the inactive theme color.
+     */
+    setInactiveText(): void {
+        this.setTextState(false);
+    }
+
+    /**
+     * Sets the current font size from predefined values.
+     *
+     * @param {FontSize} fontSize - The enum value representing the desired size.
+     */
+    setTextSize(fontSize: FontSize): void {
+        this._p.textSize(this.fontSizes[fontSize]);
+    }
+
+    /**
+     * Configures horizontal and vertical text alignment.
+     *
+     * @param {FontAlign} fontAlign - Horizontal alignment value.
+     * @param {FontVerticalAlign} fontVerticalAlign - Vertical alignment value.
+     */
+    setTextAlign(fontAlign: FontAlign, fontVerticalAlign: FontVerticalAlign): void {
+        this._p.textAlign(fontAlign, fontVerticalAlign);
+    }
+
+    /**
+     * Renders text on the HUD area using relative coordinates.
+     *
+     * @param {string} text - The string to be rendered.
+     * @param {Coordinate} coordinate - Normalized coordinates (0 to 1) within the HUD area.
+     */
+    textOnHud(text: string, coordinate: Coordinate): void {
+        const x = CoordinateHelper.getHudPosX(this._p, coordinate.x, this._rendererMetrics.display.width);
+        const y = CoordinateHelper.getHudPosY(this._p, coordinate.y, this._rendererMetrics.display.height);
+
+        this._p.text(text, x, y);
+    }
+
+    /**
+     * Renders text on the main display area using relative coordinates.
+     *
+     * @param {string} text - The string to be rendered.
+     * @param {Coordinate} coordinate - Normalized coordinates (0 to 1) within the display area.
+     */
+    textOnDisplay(text: string, coordinate: Coordinate): void {
+        // Fixed argument order: (p, x, displayWidth)
+        const x = CoordinateHelper.getDisplayPosX(this._p, coordinate.x, this._rendererMetrics.display.width);
+        const y = CoordinateHelper.getDisplayPosY(this._p, coordinate.y, this._rendererMetrics.display.height);
+
+        this._p.text(text, x, y);
+    }
+
+    /**
+     * Retrieves debug information about the text system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean> {
+        return {
+            current_font_family: this.defaultFontFamily,
+            font_sizes_count: this.fontSizes.length,
+        };
+    }
+}

package/src/core/module/time/GameTime.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import GameTime from './GameTime';
+
+describe('GameTime', () => {
+    let gameTime: GameTime;
+
+    beforeEach(() => {
+        gameTime = new GameTime();
+        gameTime.setup();
+        gameTime.setTickInterval(100);
+        gameTime.setMinTickInterval(10);
+    });
+
+    describe('update & shouldTick', () => {
+        it('should accumulate time and trigger tick when interval is reached', () => {
+            // [ACT]
+            gameTime.update(50);
+            const firstCheck = gameTime.shouldTick();
+
+            gameTime.update(50);
+            const secondCheck = gameTime.shouldTick();
+
+            // [ASSERT]
+            expect(firstCheck).toBe(false);
+            expect(secondCheck).toBe(true);
+        });
+
+        it('should handle multiple ticks in one large update', () => {
+            // [ACT]
+            gameTime.update(250);
+
+            const tick1 = gameTime.shouldTick(); // consumes 100, rem 150
+            const tick2 = gameTime.shouldTick(); // consumes 100, rem 50
+            const tick3 = gameTime.shouldTick();
+
+            // [ASSERT]
+            expect(tick1).toBe(true);
+            expect(tick2).toBe(true);
+            expect(tick3).toBe(false);
+        });
+    });
+
+    describe('FPS & TPS calculation', () => {
+        it('should calculate FPS correctly', () => {
+            // [ACT]
+            gameTime.update(16.666); // roughly 60fps
+
+            // [ASSERT]
+            const debug = gameTime.getDebugData();
+            expect(debug.fps).toBe(60);
+        });
+
+        it('should update TPS every 1000ms', () => {
+            // [ARRANGE] Trigger 5 ticks
+            for (let i = 0; i < 5; i++) {
+                gameTime.update(100);
+                gameTime.shouldTick();
+            }
+
+            // [ACT]
+            gameTime.update(500); // 5*100 + 500 = 1000ms elapsed
+
+            // [ASSERT]
+            const debug = gameTime.getDebugData();
+            expect(debug.tps).toBe(5);
+        });
+    });
+
+    describe('Interval management', () => {
+        it('should decrement interval but stay above minimum', () => {
+            // [ACT]
+            gameTime.decrementTickInterval(200);
+
+            // [ASSERT]
+            expect(gameTime.tickInterval).toBe(10);
+        });
+
+        it('should increment interval', () => {
+            // [ACT]
+            gameTime.incrementTickInterval(50);
+
+            // [ASSERT]
+            expect(gameTime.tickInterval).toBe(150);
+        });
+    });
+});