brick-engine-js 1.0.1

package/dist/core/module/renderer/GameRenderer.d.ts

@@ -0,0 +1,59 @@
+import p5 from 'p5';
+import { Cell, GameModules, RendererMetrics } from '../../types/Types';
+import { Debuggable } from '../../types/Interfaces';
+import { Renderer } from '../../types/modules';
+import { RendererComposite } from '../../types/modules';
+/**
+ * Composite renderer that manages multiple sub-renderers.
+ * Orchestrates the rendering of the main display and the HUD.
+ * Handles the calculation of shared rendering metrics (sizes, positions) to ensure consistency.
+ */
+export default class GameRenderer implements RendererComposite, Debuggable {
+    private _p;
+    private _renderers;
+    private _displayRenderer;
+    private _hudRenderer;
+    private _rendererMetrics;
+    /**
+     * Creates an instance of GameRenderer.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5);
+    /**
+     * Adds a sub-renderer to the composition.
+     *
+     * @param {Renderer} renderer - The renderer to add.
+     */
+    addRenderer(renderer: Renderer): void;
+    /**
+     * Initializes all sub-renderers and calculates layout metrics.
+     * This method must be called before rendering begins.
+     */
+    setup(): void;
+    /**
+     * Calculates the layout dimensions for the display and HUD.
+     * Based on screen configuration and relative values.
+     */
+    private _calculateMetrics;
+    /**
+     * Delegating render method.
+     * Calls render on all registered sub-renderers.
+     *
+     * @param {Cell[][]} grid - The main game grid.
+     * @param {GameModules} modules - The game modules collection.
+     */
+    render(grid: Cell[][], modules: GameModules): void;
+    /**
+     * Retrieves the calculated renderer metrics.
+     *
+     * @returns {RendererMetrics} The metrics object.
+     */
+    get rendererMetrics(): RendererMetrics;
+    /**
+     * Retrieves debug information about the renderer's calculated metrics.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}

package/dist/core/module/renderer/GameRenderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/renderer/HudRenderer.d.ts

@@ -0,0 +1,56 @@
+import { Renderer } from '../../types/modules';
+import { Cell, GameModules, RendererMetrics } from '../../types/Types';
+import p5 from 'p5';
+/**
+ * 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;
+    private _gridOrigin;
+    private _cellSize;
+    private _hudBorderRect;
+    /**
+     * Creates an instance of HudRenderer.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Renders the text-based HUD elements (Score, Level, Status).
+     *
+     * @param {GameModules} modules - The game modules.
+     */
+    private _renderHud;
+    /**
+     * Renders the preview grid for the next piece.
+     *
+     * @param {GameModules} modules - The game modules.
+     */
+    private _drawHudGrid;
+    /**
+     * 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;
+}

package/dist/core/module/renderer/HudRenderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/score/GameScore.d.ts

@@ -0,0 +1,117 @@
+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;
+    private _multiplier;
+    private _level;
+    private _maxLevel;
+    private _highScore;
+    serialId: string;
+    /**
+     * Initializes the score module.
+     * Currently a no-op but required by interface.
+     */
+    setup(): void;
+    /**
+     * 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;
+    /**
+     * Resets the current score to 0.
+     */
+    resetScore(): void;
+    /**
+     * 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): string;
+    /**
+     * Increases the game level by a specific amount.
+     *
+     * @param {number} amount - The number of levels to add.
+     */
+    increaseLevel(amount: number): void;
+    /**
+     * Resets the game level back to 1.
+     */
+    resetLevel(): void;
+    /**
+     * Gets the current score multiplier.
+     *
+     * @returns {number} The active multiplier.
+     */
+    get multiplier(): number;
+    /**
+     * Sets the score multiplier.
+     *
+     * @param {number} value - The new multiplier value.
+     */
+    set multiplier(value: number);
+    /**
+     * Gets the current level.
+     *
+     * @returns {number} The current level.
+     */
+    get level(): number;
+    /**
+     * Gets the current raw score.
+     *
+     * @returns {number} The current score value.
+     */
+    get score(): number;
+    /**
+     * Gets the maximum achievable level (if defined).
+     *
+     * @returns {number} The max level.
+     */
+    get maxLevel(): number;
+    /**
+     * Sets the maximum game level.
+     *
+     * @param {number} value - The max level cap.
+     */
+    set maxLevel(value: number);
+    /**
+     * Gets the current high score.
+     *
+     * @returns {number} The current high score.
+     */
+    get highScore(): number;
+    /**
+     * Sets the high score.
+     *
+     * @param {number} value - The new high score.
+     */
+    set highScore(value: number);
+    /**
+     * Retrieves debug information about the score status.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/core/module/score/GameScore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/session/GameSession.d.ts

@@ -0,0 +1,20 @@
+import { Serializable } from '../../types/Interfaces';
+import { Session, State } from '../../types/modules';
+export default class GameSession implements Session {
+    _state: State;
+    gameId: string;
+    private _isModalClosed;
+    private _showSessionModal;
+    private _serializables;
+    register(serializable: Serializable): void;
+    saveSession(): void;
+    clearSession(): void;
+    setShowModalFunction(showModal: (onConfirm: () => void, onCancel: () => void) => void): void;
+    private _isGameMenuInstance;
+    private _hasSession;
+    private _loadSession;
+    private _destroySession;
+    syncState(state: State): void;
+    getDebugData(): Record<string, string | number | boolean>;
+    private _key;
+}

package/dist/core/module/session/GameSession.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/sound/GameSound.d.ts

@@ -0,0 +1,85 @@
+import { Sound } from '../../types/enums';
+import { Debuggable, StateSyncable } from '../../types/Interfaces';
+import { SoundModule, State } from '../../types/modules';
+/**
+ * Manages audio playback and sound effects.
+ * Handles the Web Audio API context, loading sound buffers, and managing volume/muting.
+ */
+export default class GameSound implements SoundModule, StateSyncable, Debuggable {
+    muted: boolean;
+    /**
+     * The AudioContext is the primary "audio engine" for the browser.
+     * It manages all sound creation and playback.
+     */
+    private _audioContext;
+    /**
+     * The GainNode controls the volume (gain) of the audio.
+     * All sounds pass through this node before reaching the destination (speakers).
+     */
+    private _gainNode;
+    /**
+     * Stores loaded sound buffers in memory.
+     * AudioBuffer contains the decoded audio data ready for playback.
+     */
+    private _buffers;
+    /**
+     * Tracks currently playing sound sources.
+     * Required to stop specific sounds (like background music or loops).
+     */
+    private _activeSources;
+    private _volume;
+    _state: State;
+    /**
+     * Initializes the sound system.
+     * Creates the AudioContext, sets up the master gain node, and starts loading sounds.
+     */
+    setup(): void;
+    /**
+     * Plays a specific sound effect.
+     * Creates a new source node for each playback instance.
+     *
+     * @param {Sound} sound - The sound identifier/URL to play.
+     * @returns {Promise<void>}
+     */
+    play(sound: Sound): Promise<void>;
+    /**
+     * Stops all instances of a specific sound.
+     *
+     * @param {Sound} sound - The sound to stop.
+     * @returns {Promise<void>}
+     */
+    stop(sound: Sound): Promise<void>;
+    /**
+     * Stops all currently playing sounds.
+     *
+     * @returns {Promise<void>}
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Updates the master volume based on the muted state.
+     */
+    private _updateGain;
+    /**
+     * Loads all sound assets defined in the Sound enum.
+     * Fetches, buffers, and decodes the audio data.
+     */
+    private _loadAll;
+    /**
+     * Toggles the mute state of the game.
+     * Updates the state module and the audio gain.
+     */
+    toggleMute(): void;
+    /**
+     * Receives the shared game state module.
+     * Subscribes to mute state changes.
+     *
+     * @param {State} state - The game state module.
+     */
+    syncState(state: State): void;
+    /**
+     * Retrieves debug information about the audio system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}

package/dist/core/module/sound/GameSound.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/state/GameState.d.ts

@@ -0,0 +1,172 @@
+import { Debuggable } from '../../types/Interfaces';
+import { State } from '../../types/modules';
+import { StateProperty } from '../../types/Types';
+/**
+ * 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 to store property names and their associated subscription callbacks. */
+    private _subscribers;
+    /**
+     * Initializes the state module.
+     * Sets default values for all state properties and loads persisted data.
+     */
+    setup(): void;
+    /**
+     * Loads persistent state from LocalStorage.
+     */
+    private _loadPersistentState;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Checks if the game machine is powered on.
+     *
+     * @returns {boolean} True if powered on.
+     */
+    isOn(): boolean;
+    /**
+     * Checks if the game machine is powered off.
+     *
+     * @returns {boolean} True if powered off.
+     */
+    isOff(): boolean;
+    /**
+     * 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;
+    /**
+     * Checks if the game is currently running (not paused, not game over).
+     *
+     * @returns {boolean} True if gameplay is active.
+     */
+    isPlaying(): boolean;
+    /**
+     * Checks if the game is paused.
+     *
+     * @returns {boolean} True if the game is started but not playing (and not game over).
+     */
+    isPaused(): boolean;
+    /**
+     * Checks if the game is in a "Game Over" state.
+     *
+     * @returns {boolean} True if the game is over.
+     */
+    isGameOver(): boolean;
+    /**
+     * Powers on the game machine.
+     * Resets all session states (start, playing, game over).
+     */
+    turnOn(): void;
+    /**
+     * Powers off the game machine.
+     * Resets all states.
+     */
+    turnOff(): void;
+    /**
+     * Starts a new game session.
+     * Only works if the machine is powered on.
+     */
+    startGame(): void;
+    /**
+     * Resets the game over state and starts the game again.
+     */
+    resetGameOver(): void;
+    /**
+     * Exits the current game session, returning to the "On" state.
+     */
+    exitGame(): void;
+    /**
+     * Pauses the current game.
+     */
+    pause(): void;
+    /**
+     * Resumes the game from a paused state.
+     */
+    resume(): void;
+    /**
+     * Triggers the "Game Over" state.
+     * Stops gameplay.
+     */
+    triggerGameOver(): void;
+    /**
+     * Resets the game to the initial state (restarts).
+     */
+    resetGame(): void;
+    /**
+     * Checks if color mode is enabled.
+     *
+     * @returns {boolean} True if color is enabled.
+     */
+    isColorEnabled(): boolean;
+    /**
+     * Enables or disables color mode.
+     *
+     * @param {boolean} value - True to enable, false to disable.
+     */
+    setColorEnabled(value: boolean): void;
+    /**
+     * Checks if audio is muted.
+     *
+     * @returns {boolean} True if muted.
+     */
+    isMuted(): boolean;
+    /**
+     * Mutes or unmutes the audio.
+     *
+     * @param {boolean} value - True to mute, false to unmute.
+     */
+    setMuted(value: boolean): void;
+    /**
+     * Toggles the color enabled state.
+     */
+    toggleColorEnabled(): void;
+    /**
+     * Toggles the muted state.
+     */
+    toggleMuted(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Retrieves debug information about the game state.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}

package/dist/core/module/state/GameState.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/text/GameText.d.ts

@@ -0,0 +1,87 @@
+import p5 from 'p5';
+import { FontSize, FontAlign, FontVerticalAlign } from '../../types/enums';
+import { Coordinate, RendererMetrics } from '../../types/Types';
+import { Debuggable } from '../../types/Interfaces';
+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;
+    /** Array containing pre-calculated font sizes in pixels. */
+    private fontSizes;
+    /** Stores the current display metrics for relative positioning. */
+    private _rendererMetrics;
+    /** The p5 instance used for rendering. */
+    private _p;
+    /**
+     * Creates an instance of GameText.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5);
+    /**
+     * 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;
+    /**
+     * Sets the display metrics used for relative text positioning.
+     *
+     * @param {RendererMetrics} rendererMetrics - The current renderer dimensions and origin.
+     */
+    setRendererMetrics(rendererMetrics: RendererMetrics): void;
+    /**
+     * 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;
+    /**
+     * Sets the text color to the active theme color.
+     */
+    setActiveText(): void;
+    /**
+     * Sets the text color to the inactive theme color.
+     */
+    setInactiveText(): void;
+    /**
+     * Sets the current font size from predefined values.
+     *
+     * @param {FontSize} fontSize - The enum value representing the desired size.
+     */
+    setTextSize(fontSize: FontSize): void;
+    /**
+     * Configures horizontal and vertical text alignment.
+     *
+     * @param {FontAlign} fontAlign - Horizontal alignment value.
+     * @param {FontVerticalAlign} fontVerticalAlign - Vertical alignment value.
+     */
+    setTextAlign(fontAlign: FontAlign, fontVerticalAlign: FontVerticalAlign): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Retrieves debug information about the text system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}

package/dist/core/module/text/GameText.test.d.ts

@@ -0,0 +1 @@
+export {};