brick-engine-js 1.0.1

package/src/core/module/renderer/HudRenderer.ts

@@ -0,0 +1,203 @@
+import { Renderer } from '../../types/modules';
+import { Cell, Coordinate, GameModules, RendererMetrics } from '../../types/Types';
+import p5 from 'p5';
+import { Color, FontAlign, FontSize, FontVerticalAlign } from '../../types/enums';
+import CoordinateHelper from '../../helpers/CoordinateHelper';
+import configs from '../../../config/configs';
+import RelativeValuesHelper from '../../helpers/RelativeValuesHelper';
+
+/**
+ * Responsible for rendering the Heads-Up Display (HUD).
+ * Displays game information like Score, High Score, Level, and the Next Piece Preview.
+ */
+export default class HudRenderer implements Renderer {
+    private _p: p5;
+
+    private _gridOrigin: Coordinate;
+
+    private _cellSize: number;
+
+    private _hudBorderRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+
+    /**
+     * Creates an instance of HudRenderer.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5) {
+        this._p = p;
+    }
+
+    /**
+     * Initializes the HUD with calculated metrics.
+     * Sets up the grid origin and border rectangle for the "next piece" preview area.
+     *
+     * @param {RendererMetrics} rendererMetrics - The shared renderer metrics.
+     */
+    setup(rendererMetrics: RendererMetrics): void {
+        this._cellSize = rendererMetrics.cell.size;
+        this._gridOrigin = {
+            x: CoordinateHelper.getHudPosX(this._p, 0.078, rendererMetrics.display.width),
+            y: CoordinateHelper.getHudPosY(this._p, 0.375, rendererMetrics.display.height),
+        };
+
+        this._hudBorderRect = {
+            x: this._gridOrigin.x - RelativeValuesHelper.getRelativeWidth(this._p, 0.005),
+            y: this._gridOrigin.y - RelativeValuesHelper.getRelativeHeight(this._p, 0.005),
+            w: this._cellSize * 4 + RelativeValuesHelper.getRelativeWidth(this._p, 0.01),
+            h: this._cellSize * 4 + RelativeValuesHelper.getRelativeHeight(this._p, 0.01),
+        };
+    }
+
+    /**
+     * Renders all HUD elements.
+     *
+     * @param {Cell[][]} grid - The main game grid (unused in HUD, but required by interface).
+     * @param {GameModules} modules - The game modules for retrieving state and score.
+     */
+    render(grid: Cell[][], modules: GameModules): void {
+        this._renderHud(modules);
+        this._drawHudGrid(modules);
+    }
+
+    /**
+     * Renders the text-based HUD elements (Score, Level, Status).
+     *
+     * @param {GameModules} modules - The game modules.
+     */
+    private _renderHud(modules: GameModules): void {
+        const { text, state, score } = modules;
+
+        this._p.push();
+
+        text.setTextSize(FontSize.SMALL);
+        text.setInactiveText();
+        text.setTextAlign(FontAlign.LEFT, FontVerticalAlign.BOTTOM);
+
+        //Placeholders text
+        text.textOnHud('88888888', { x: 0.05, y: 0.13 });
+        text.textOnHud('88888888', { x: 0.05, y: 0.3 });
+        text.textOnHud('88 - 88', { x: 0.05, y: 0.8 });
+
+        if (state.isOn()) {
+            text.setActiveText();
+        }
+
+        //Score text
+        text.textOnHud('Score', { x: 0.05, y: 0.06 });
+        text.textOnHud(score.score.toString(), { x: 0.05, y: 0.13 });
+
+        //Hi-Score text
+        text.textOnHud('Hi-Score', { x: 0.05, y: 0.23 });
+        text.textOnHud(score.highScore.toString(), { x: 0.05, y: 0.3 });
+
+        //Level text
+        text.textOnHud('Level', { x: 0.05, y: 0.72 });
+        const levelValue = `${score.level < 10 ? '0' + score.level : score.level} - ${score.maxLevel}`;
+        text.textOnHud(levelValue, { x: 0.05, y: 0.8 });
+
+        text.setTextAlign(FontAlign.CENTER, FontVerticalAlign.BOTTOM);
+
+        //Paused text
+        if (state.isPaused()) {
+            text.setActiveText();
+        } else {
+            text.setInactiveText();
+        }
+        text.textOnHud('Paused', { x: 0.5, y: 0.9 });
+
+        //Muted text
+        if (state.isOn() && state.isMuted()) {
+            text.setActiveText();
+        } else {
+            text.setInactiveText();
+        }
+        text.textOnHud('Muted', { x: 0.5, y: 0.97 });
+
+        this._p.pop();
+
+        this._drawHudGrid(modules);
+    }
+
+    /**
+     * Renders the preview grid for the next piece.
+     *
+     * @param {GameModules} modules - The game modules.
+     */
+    private _drawHudGrid(modules: GameModules): void {
+        const { hudGrid, state } = modules;
+
+        this._p.push();
+
+        hudGrid.forEach(cell => {
+            const { x, y } = cell.coordinate;
+
+            if (state.isOff() && !state.isPlaying()) {
+                cell.value = 0;
+            }
+
+            let color = cell.value !== 0 ? Color.DEFAULT : Color.INACTIVE;
+
+            if (state.isColorEnabled() && cell.value !== 0) {
+                color = cell.color;
+            }
+
+            this.drawCellElement({
+                w: this._cellSize,
+                h: this._cellSize,
+                posX: this._gridOrigin.x + this._cellSize * x,
+                posY: this._gridOrigin.y + this._cellSize * y,
+                color,
+            });
+        });
+
+        this._p.noFill();
+        this._p.stroke(state.isOn() ? Color.DEFAULT : Color.INACTIVE);
+
+        this._p.rect(this._hudBorderRect.x, this._hudBorderRect.y, this._hudBorderRect.w, this._hudBorderRect.h);
+
+        this._p.pop();
+    }
+
+    /**
+     * Helper method to draw a single cell on the HUD.
+     * Identical in logic to DisplayRenderer's cell drawing but localized for HUD.
+     *
+     * @param {object} params - The drawing parameters.
+     * @param {number} params.w - Width of the cell.
+     * @param {number} params.posX - Absolute X position.
+     * @param {number} params.posY - Absolute Y position.
+     * @param {Color} params.color - Color of the cell.
+     */
+    private drawCellElement({ w, posX, posY, color }: { w: number; h: number; posX: number; posY: number; color: Color }): void {
+        const { margin: cellMargin, padding: cellPadding, strokeWeight: cellStrokeWeight } = configs.screenLayout.cell;
+
+        const innerOffset = cellMargin * w;
+        const innerSize = w - cellMargin * w * 2;
+        const paddingOffset = cellPadding * w;
+        const paddingSize = w - cellPadding * w * 2;
+        const strokeWeight = cellStrokeWeight * w;
+
+        this._p.push();
+
+        this._p.translate(posX, posY);
+
+        this._p.strokeWeight(strokeWeight);
+        this._p.stroke(color);
+
+        // Outer Box
+        this._p.noFill();
+        this._p.rect(innerOffset, innerOffset, innerSize, innerSize);
+
+        // Inner Fill
+        this._p.fill(color);
+        this._p.rect(paddingOffset, paddingOffset, paddingSize, paddingSize);
+
+        this._p.pop();
+    }
+}

package/src/core/module/score/GameScore.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import GameScore from './GameScore';
+
+describe('GameScore', () => {
+    let gameScore: GameScore;
+
+    beforeEach(() => {
+        vi.stubGlobal('localStorage', {
+            getItem: vi.fn().mockReturnValue('100'),
+            setItem: vi.fn(),
+        });
+
+        gameScore = new GameScore();
+        gameScore.setup();
+    });
+
+    describe('increaseScore', () => {
+        it('should increase score by base amount * multiplier', () => {
+            // [ARRANGE]
+            gameScore.multiplier = 2;
+
+            // [ACT]
+            gameScore.increaseScore(50);
+
+            // [ASSERT]
+            expect(gameScore.score).toBe(100);
+        });
+
+        it('should update high score if current score exceeds it', () => {
+            // [ACT]
+            gameScore.increaseScore(150);
+
+            // [ASSERT]
+            expect(localStorage.setItem).toHaveBeenCalledWith('highScore', '150');
+            expect(gameScore.highScore).toBe(150);
+        });
+
+        it('should NOT update high score if current score is lower than high score', () => {
+            // [ACT]
+            gameScore.increaseScore(50);
+
+            // [ASSERT]
+            expect(localStorage.setItem).not.toHaveBeenCalled();
+            expect(gameScore.highScore).toBe(100);
+        });
+    });
+
+    describe('formatting', () => {
+        it('should return score padded with zeros', () => {
+            // [ARRANGE]
+            gameScore.increaseScore(123); // multiplier is 1 by default
+
+            // [ACT]
+            const formatted = gameScore.getFormattedScore(6);
+
+            // [ASSERT]
+            expect(formatted).toBe('000123');
+        });
+    });
+
+    describe('Level Management', () => {
+        it('should increase and reset level', () => {
+            // [ACT]
+            gameScore.increaseLevel(2);
+            expect(gameScore.level).toBe(3);
+
+            gameScore.resetLevel();
+            expect(gameScore.level).toBe(1);
+        });
+    });
+});

package/src/core/module/score/GameScore.ts

@@ -0,0 +1,188 @@
+import { Debuggable } from '../../types/Interfaces';
+import { Score } from '../../types/modules';
+import { Serializable } from '../../types/Interfaces';
+
+/**
+ * Manages game scoring, levels, and high score tracking.
+ * Acts as the authority for the game's `highScore`, persisting it directly to `LocalStorage`.
+ * Handles multipliers and supports Session serialization out of the box.
+ */
+export default class GameScore implements Score, Debuggable, Serializable {
+    private _score: number = 0;
+    private _multiplier: number = 1;
+    private _level: number = 1;
+    private _maxLevel: number = 10;
+    private _highScore: number = 0;
+
+    serialId: string = 'score';
+
+    /**
+     * Initializes the score module.
+     * Currently a no-op but required by interface.
+     */
+    setup(): void {
+        this._highScore = Number(localStorage.getItem('highScore'));
+    }
+
+    /**
+     * Increases the score by the given amount, applying the current multiplier.
+     * Automatically checks for high score updates.
+     *
+     * @param {number} amount - The base amount to increase by.
+     */
+    increaseScore(amount: number): void {
+        this._score += amount * this._multiplier;
+        if (this._score > this._highScore) {
+            this.highScore = this._score;
+        }
+    }
+
+    /**
+     * Resets the current score to 0.
+     */
+    resetScore(): void {
+        this._score = 0;
+    }
+
+    /**
+     * Formats the current score as a string with leading zeros.
+     *
+     * @param {number} [digits=6] - The total number of digits to display.
+     * @returns {string} The formatted score string (e.g., "000150").
+     */
+    getFormattedScore(digits: number = 6): string {
+        return this._score.toString().padStart(digits, '0');
+    }
+
+    /**
+     * Increases the game level by a specific amount.
+     *
+     * @param {number} amount - The number of levels to add.
+     */
+    increaseLevel(amount: number): void {
+        this._level += amount;
+    }
+
+    /**
+     * Resets the game level back to 1.
+     */
+    resetLevel(): void {
+        this._level = 1;
+    }
+
+    /**
+     * Gets the current score multiplier.
+     *
+     * @returns {number} The active multiplier.
+     */
+    get multiplier(): number {
+        return this._multiplier;
+    }
+
+    /**
+     * Sets the score multiplier.
+     *
+     * @param {number} value - The new multiplier value.
+     */
+    set multiplier(value: number) {
+        this._multiplier = value;
+    }
+
+    /**
+     * Gets the current level.
+     *
+     * @returns {number} The current level.
+     */
+    get level(): number {
+        return this._level;
+    }
+
+    /**
+     * Gets the current raw score.
+     *
+     * @returns {number} The current score value.
+     */
+    get score(): number {
+        return this._score;
+    }
+
+    /**
+     * Gets the maximum achievable level (if defined).
+     *
+     * @returns {number} The max level.
+     */
+    get maxLevel(): number {
+        return this._maxLevel;
+    }
+
+    /**
+     * Sets the maximum game level.
+     *
+     * @param {number} value - The max level cap.
+     */
+    set maxLevel(value: number) {
+        this._maxLevel = value;
+    }
+
+    /**
+     * Gets the current high score.
+     *
+     * @returns {number} The current high score.
+     */
+    get highScore(): number {
+        return this._highScore;
+    }
+
+    /**
+     * Sets the high score.
+     *
+     * @param {number} value - The new high score.
+     */
+    set highScore(value: number) {
+        this._highScore = value;
+        localStorage.setItem('highScore', value.toString());
+    }
+
+    /**
+     * Retrieves debug information about the score status.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean> {
+        return {
+            score: this._score,
+            multiplier: this._multiplier,
+            level: this._level,
+            max_level: this._maxLevel,
+        };
+    }
+
+    /**
+     * Serializes the current score and level progress into a JSON string.
+     * This is used by the SessionManager to save transient state.
+     *
+     * @returns {string} The serialized JSON data.
+     */
+    serialize(): string {
+        return JSON.stringify({
+            score: this._score,
+            multiplier: this._multiplier,
+            level: this._level,
+            max_level: this._maxLevel,
+        });
+    }
+
+    /**
+     * Restores score and level progress from a serialized JSON string.
+     * Used by the SessionManager when recovering an active session.
+     *
+     * @param {string} data - The JSON string containing the saved session data.
+     */
+    deserialize(data: string): void {
+        const parsed = JSON.parse(data);
+        this._score = parsed.score;
+        this._multiplier = parsed.multiplier;
+        this._level = parsed.level;
+        this._maxLevel = parsed.max_level;
+    }
+}

package/src/core/module/session/GameSession.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach, Mock } from 'vitest';
+import GameSession from './GameSession';
+import { State } from '../../types/modules';
+import { Serializable } from '../../types/Interfaces';
+import { StateProperty } from '../../types/enums';
+
+const localStorageMock = (() => {
+    let store: Record<string, string> = {};
+    return {
+        getItem: vi.fn((key: string) => store[key] || null),
+        setItem: vi.fn((key: string, value: string) => {
+            store[key] = value.toString();
+        }),
+        removeItem: vi.fn((key: string) => {
+            delete store[key];
+        }),
+        clear: vi.fn(() => {
+            store = {};
+        }),
+    };
+})();
+
+vi.stubGlobal('localStorage', localStorageMock);
+
+describe('GameSession', () => {
+    let session: GameSession;
+    let mockState: State;
+    let mockSerializable: Serializable;
+    let showModalMock: Mock;
+    let stateSubscriptions: Record<string, (val: boolean) => void>;
+
+    beforeEach(() => {
+        // [ARRANGE]
+        localStorageMock.clear();
+        vi.clearAllMocks();
+
+        stateSubscriptions = {};
+        mockState = {
+            subscribe: vi.fn((property: StateProperty, callback: (val: boolean) => void) => {
+                stateSubscriptions[property] = callback;
+            }),
+        } as unknown as State;
+
+        mockSerializable = {
+            serialId: 'test-serial',
+            serialize: vi.fn().mockReturnValue('serialized-data'),
+            deserialize: vi.fn(),
+        } as unknown as Serializable;
+
+        showModalMock = vi.fn();
+
+        session = new GameSession();
+        session.gameId = 'test-game';
+        session.setShowModalFunction(showModalMock);
+        session.register(mockSerializable);
+    });
+
+    describe('saveSession', () => {
+        it('should return early and not save if modal is not closed', () => {
+            // [ACT]
+            session.saveSession();
+
+            // [ASSERT]
+            expect(localStorageMock.setItem).not.toHaveBeenCalled();
+        });
+
+        it('should return early and not save if it is game-menu instance', () => {
+            // [ARRANGE]
+            session.gameId = 'game-menu';
+            session.syncState(mockState);
+            // Simulate playing state with no previous session, which closes the modal automatically
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+
+            // [ACT]
+            session.saveSession();
+
+            // [ASSERT]
+            expect(localStorageMock.setItem).not.toHaveBeenCalled();
+        });
+
+        it('should save session when modal is closed and game is not menu', () => {
+            // [ARRANGE]
+            session.syncState(mockState);
+            // Close the modal automatically since no session exists
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+
+            // [ACT]
+            session.saveSession();
+
+            // [ASSERT]
+            expect(localStorageMock.setItem).toHaveBeenCalledWith('test-game::test-serial', 'serialized-data');
+        });
+    });
+
+    describe('syncState', () => {
+        it('should automatically close modal and not show when there is no session', () => {
+            // [ARRANGE]
+            session.syncState(mockState);
+
+            // [ACT]
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+
+            // [ASSERT]
+            expect(showModalMock).not.toHaveBeenCalled();
+            // Verify _isModalClosed is true internally by verifying if it can save now
+            session.saveSession();
+            expect(localStorageMock.setItem).toHaveBeenCalled();
+        });
+
+        it('should automatically close modal and not show when it is a game-menu instance', () => {
+            // [ARRANGE]
+            session.gameId = 'game-menu';
+            // Simulate existing session
+            localStorageMock.setItem('game-menu::test-serial', 'some-data');
+            session.syncState(mockState);
+
+            // [ACT]
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+
+            // [ASSERT]
+            expect(showModalMock).not.toHaveBeenCalled();
+        });
+
+        it('should show session modal when playing, has session, and is not game-menu', () => {
+            // [ARRANGE]
+            localStorageMock.setItem('test-game::test-serial', 'some-data');
+            session.syncState(mockState);
+
+            // [ACT]
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+
+            // [ASSERT]
+            expect(showModalMock).toHaveBeenCalledTimes(1);
+        });
+
+        it('should load session when modal is confirmed and a session exists', () => {
+            // [ARRANGE]
+            localStorageMock.setItem('test-game::test-serial', 'some-data');
+            session.syncState(mockState);
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+            const onConfirm = showModalMock.mock.calls[0][0] as () => void;
+
+            // [ACT]
+            onConfirm();
+
+            // [ASSERT]
+            expect(mockSerializable.deserialize).toHaveBeenCalledWith('some-data');
+        });
+
+        it('should destroy session when modal is canceled', () => {
+            // [ARRANGE]
+            localStorageMock.setItem('test-game::test-serial', 'some-data');
+            session.syncState(mockState);
+            stateSubscriptions[StateProperty.PLAYING]?.(true);
+            const onCancel = showModalMock.mock.calls[0][1] as () => void;
+
+            // [ACT]
+            onCancel();
+
+            // [ASSERT]
+            expect(localStorageMock.removeItem).toHaveBeenCalledWith('test-game::test-serial');
+        });
+
+        it('should destroy session when game is over', () => {
+            // [ARRANGE]
+            localStorageMock.setItem('test-game::test-serial', 'some-data');
+            session.syncState(mockState);
+
+            // [ACT]
+            stateSubscriptions[StateProperty.GAME_OVER]?.(true);
+
+            // [ASSERT]
+            expect(localStorageMock.removeItem).toHaveBeenCalledWith('test-game::test-serial');
+        });
+    });
+});