brick-engine-js 1.0.21 → 1.0.23

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

@@ -1,5 +1,14 @@
 import { Serializable } from '../../types/Interfaces';
 import { Session, State } from '../../types/modules';
+/**
+ * Core module orchestrating state synchronization and transient game data persistence.
+ *
+ * Implements the {@link Session} interface to establish a single secure boundary
+ * between the active engine states and physical local storage limits. It intercepts
+ * the startup engine flows to ensure all registered {@link Serializable} modules
+ * correctly pause initialization safely inside a modal window until a human resolves
+ * the conflict (restoring or clearing).
+ */
 export default class GameSession implements Session {
     _state: State;
     gameId: string;
@@ -9,17 +18,64 @@ export default class GameSession implements Session {
     private _showSessionModal;
     private _resetFn;
     private _serializables;
+    /**
+     * Registers an external module to be actively tracked and persisted during session events.
+     *
+     * @param {Serializable} serializable - The compliant module instance exposing standard serialization capabilities.
+     * @returns {void} Returns nothing.
+     */
     register(serializable: Serializable): void;
+    /**
+     * Extracts and physically persists the current state payload of all registered modules to browser storage.
+     * Silently aborts if the session has not completed the restoration resolution flow or is disabled.
+     *
+     * @returns {void} Returns nothing.
+     */
     saveSession(): void;
+    /**
+     * Irreversibly wipes all transient saved module data mapped under this session's namespace.
+     *
+     * @returns {void} Returns nothing.
+     */
     clearSession(): void;
+    /**
+     * Injects the visual modal resolution closure implemented upstream.
+     *
+     * @param {Function} showModal - The asynchronous UI closure designed to ask the player to reload or reset the session.
+     * @returns {void} Returns nothing.
+     */
     setShowModalFunction(showModal: (onConfirm: () => void, onCancel: () => void) => void): void;
+    /**
+     * Injects the explicit game restoration sequence to execute when a session is aborted.
+     *
+     * @param {Function} resetFn - The recovery routine triggering a clean slate reset.
+     * @returns {void} Returns nothing.
+     */
     setResetFunction(resetFn: () => void): void;
+    /**
+     * Hard-toggles whether the session recovery mechanism evaluates at startup.
+     *
+     * @param {boolean} enabled - True to enforce session monitoring, false to skip entirely.
+     * @returns {void} Returns nothing.
+     */
     setSessionEnabled(enabled: boolean): void;
     isModalOpen(): boolean;
     isSessionResolved(): boolean;
     private _hasSession;
     private _loadSession;
+    /**
+     * Hooks into the global single source of truth state listener.
+     * Triggers the UI recovery workflow explicitly when the engine switches to the PLAYING state.
+     *
+     * @param {State} state - The authoritative lifecycle hub object to observe securely.
+     * @returns {void} Returns nothing.
+     */
     syncState(state: State): void;
+    /**
+     * Aggregates live metadata properties intended strictly for Development Dashboards.
+     *
+     * @returns {Record<string, string | number | boolean>} A shallow payload of the session tracker statuses.
+     */
     getDebugData(): Record<string, string | number | boolean>;
     private _key;
 }

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

@@ -2,8 +2,12 @@ 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.
+ * Module responsible for managing non-blocking audio playback and preloading sound effects.
+ *
+ * It decouples the raw Web Audio API context management away from generic gameplay
+ * components. By abstracting buffer decoding, volume/gain adjustments, and muting, it
+ * allows systems to simply request `play(Sound.BEEP)` without managing individual audio nodes.
+ * Implements {@link StateSyncable} to actively listen to mute changes from the global state.
  */
 export default class GameSound implements SoundModule, StateSyncable, Debuggable {
     muted: boolean;
@@ -30,56 +34,68 @@ export default class GameSound implements SoundModule, StateSyncable, Debuggable
     private _volume;
     _state: State;
     /**
-     * Initializes the sound system.
-     * Creates the AudioContext, sets up the master gain node, and starts loading sounds.
+     * Initializes the sound system and buffer caching.
+     * Creates the core standard `AudioContext`, sets up the master audio routing
+     * `GainNode` for volume adjustment, and kicks off asynchronous background downloading
+     * of all game sound assets.
+     *
+     * @returns {void} Returns nothing.
      */
     setup(): void;
     /**
-     * Plays a specific sound effect.
-     * Creates a new source node for each playback instance.
+     * Instantiates an active playback stream for a specific preloaded sound effect.
+     *
+     * To prevent overlapping audio collision, this creates a new `BufferSource` node
+     * for every individual playback call.
      *
-     * @param {Sound} sound - The sound identifier/URL to play.
-     * @returns {Promise<void>}
+     * @param {Sound} sound - The precise enum identity of the targeted soundtrack/effect file to trigger.
+     * @returns {Promise<void>} An asynchronous void promise that resolves immediately upon commanding the API.
      */
     play(sound: Sound): Promise<void>;
     /**
-     * Stops all instances of a specific sound.
+     * Purges and forcefully stops all active playback instances of a specific sound.
      *
-     * @param {Sound} sound - The sound to stop.
-     * @returns {Promise<void>}
+     * @param {Sound} sound - The exact enum identity of the looping audio channel to abruptly halt.
+     * @returns {Promise<void>} An asynchronous void promise resolving upon completion.
      */
     stop(sound: Sound): Promise<void>;
     /**
-     * Stops all currently playing sounds.
+     * A global panic method that physically stops every localized sound immediately
+     * looping in the actively managed list.
      *
-     * @returns {Promise<void>}
+     * @returns {Promise<void>} An asynchronous void promise resolving after mass stopping concludes.
      */
     stopAll(): Promise<void>;
     /**
-     * Updates the master volume based on the muted state.
+     * Internal utility to update the master audio routing node based on active configuration limits.
+     *
+     * @returns {void} Returns nothing.
      */
     private _updateGain;
     /**
-     * Loads all sound assets defined in the Sound enum.
-     * Fetches, buffers, and decodes the audio data.
+     * Preloads and decodes binary chunks for all physical asset bundles defined in the `Sound` configuration.
+     *
+     * @returns {Promise<void>} An asynchronous void promise resolving upon resolving all fetch requests.
      */
     private _loadAll;
     /**
-     * Toggles the mute state of the game.
-     * Updates the state module and the audio gain.
+     * Public proxy bound cleanly to the internal UI to swap the active muting preference stringent rule.
+     *
+     * @returns {void} Returns nothing.
      */
     toggleMute(): void;
     /**
-     * Receives the shared game state module.
-     * Subscribes to mute state changes.
+     * Hook implemented to attach contextual state triggers immediately after standard `setup` completes.
+     * Subscribes to the single source of truth {@link GameState} to actively track the `MUTED` flag.
      *
-     * @param {State} state - The game state module.
+     * @param {State} state - The injected active singleton logic state context instance to observe securely.
+     * @returns {void} Returns nothing.
      */
     syncState(state: State): void;
     /**
-     * Retrieves debug information about the audio system.
+     * Collects and exposes internal mapping metrics required by the Engine's Real-time Development Monitor.
      *
-     * @returns {Record<string, string | number | boolean>} The debug data.
+     * @returns {Record<string, string | number | boolean>} A shallow payload containing current buffering counts and audio scaling rules.
      */
     getDebugData(): Record<string, string | number | boolean>;
 }

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

@@ -2,40 +2,46 @@ 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.
+ * Central module representing the singleton source of truth for the game lifecycle and persistent user preferences.
  *
- * Provides a central hub for tracking game lifecycle states (on, running, gameOver)
- * and user preferences (color enabled).
+ * Implements the {@link State} and {@link Debuggable} interfaces. Providing a central hub
+ * for tracking high-level system states (ON, PLAYING, PAUSED, GAME_OVER) and user
+ * configurations (Color and Mute toggles).
  *
- *
- * **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).
+ * It is designated as the sole entity responsible for interacting with the browser's
+ * LocalStorage to persist player preferences across distinct engine sessions. It explicitly
+ * delegates transient session states to `GameSession`, keeping its scope strictly bounding
+ * global lifecycles and physical preferences.
  */
 export default class GameState implements State, Debuggable {
     private _state;
     /**
      * Initializes the state module.
-     * Sets default values for all state properties and loads persisted data.
+     * Sets default values for all {@link StateProperty} elements and loads persisted user settings.
+     *
+     * @returns {void} Returns nothing.
      */
     setup(): void;
     /**
-     * Loads persistent state from LocalStorage.
+     * Internal utility that loads persistent state configurations directly from `LocalStorage`.
+     *
+     * @returns {void} Returns nothing.
      */
     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.
+     * @param {StateProperty} property - The exact property enum key to assign.
+     * @param {boolean | number} value - The primitive value to set.
+     * @returns {void} Returns nothing.
      */
     private _set;
     /**
-     * Notifies all subscribers of a property change.
+     * Notifies all subscribers of a property change via the {@link EventEmitter}.
      * Dispatches to the base property channel and state-specific context channels.
      *
-     * @param {StateProperty} property - The property that changed.
+     * @param {StateProperty} property - The property enum string that dictates the notification channel.
+     * @returns {void} Returns nothing.
      */
     notify(property: StateProperty): void;
     /**
@@ -78,24 +84,34 @@ export default class GameState implements State, Debuggable {
     /**
      * Powers on the game machine.
      * Resets all session states (start, playing, game over).
+     *
+     * @returns {void} Returns nothing.
      */
     turnOn(): void;
     /**
      * Powers off the game machine.
      * Resets all states.
+     *
+     * @returns {void} Returns nothing.
      */
     turnOff(): void;
     /**
      * Starts a new game session.
      * Only works if the machine is powered on.
+     *
+     * @returns {void} Returns nothing.
      */
     startGame(): void;
     /**
      * Resets the game over state and starts the game again.
+     *
+     * @returns {void} Returns nothing.
      */
     resetGameOver(): void;
     /**
      * Exits the current game session, returning to the "On" state.
+     *
+     * @returns {void} Returns nothing.
      */
     exitGame(): void;
     /**
@@ -113,6 +129,8 @@ export default class GameState implements State, Debuggable {
     triggerGameOver(): void;
     /**
      * Resets the game to the initial state (restarts).
+     *
+     * @returns {void} Returns nothing.
      */
     resetGame(): void;
     /**
@@ -125,6 +143,7 @@ export default class GameState implements State, Debuggable {
      * Enables or disables color mode.
      *
      * @param {boolean} value - True to enable, false to disable.
+     * @returns {void} Returns nothing.
      */
     setColorEnabled(value: boolean): void;
     /**
@@ -137,14 +156,19 @@ export default class GameState implements State, Debuggable {
      * Mutes or unmutes the audio.
      *
      * @param {boolean} value - True to mute, false to unmute.
+     * @returns {void} Returns nothing.
      */
     setMuted(value: boolean): void;
     /**
      * Toggles the color enabled state.
+     *
+     * @returns {void} Returns nothing.
      */
     toggleColorEnabled(): void;
     /**
      * Toggles the muted state.
+     *
+     * @returns {void} Returns nothing.
      */
     toggleMuted(): void;
     subscribe(property: StateProperty, callback: (value: boolean | number) => void): void;

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

@@ -3,10 +3,13 @@ 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.
+ * Core text rendering module bridging engine abstractions to specific pixel scaling.
  *
- * This class orchestrates font initialization, sizing, alignment, and
- * provides methods to render text on specific areas (HUD or Display).
+ * Implements the {@link Text} interface to separate font computation logic from
+ * actual grid and view rendering processes. By pre-calculating relative font dimensions
+ * and actively calculating spatial positions against the display canvas at runtime, it
+ * guarantees that all text objects are purely responsive without causing continuous layout
+ * recalculations on the primary engine CPU loop.
  */
 export default class GameText implements Text, Debuggable {
     /** The default font family used for game text. */
@@ -16,63 +19,75 @@ export default class GameText implements Text, Debuggable {
     /** Stores the current display metrics for relative positioning. */
     private _rendererMetrics;
     /**
-     * Setup the font and pre-calculates relative font sizes.
+     * Setups the active font-family and pre-calculates the array of relative font sizes.
      *
-     * Uses configuration values to define a set of pixel-perfect font sizes
-     * based on current container width.
+     * Extracts values from the local environment to pre-define deterministic font scales
+     * based on the container width to eliminate parsing loops later.
+     *
+     * @returns {void} Returns nothing.
      */
     setup(): void;
     /**
-     * Sets the display metrics used for relative text positioning.
+     * Injects the active bounding box metrics used for relative text alignments.
      *
-     * @param {RendererMetrics} rendererMetrics - The current renderer dimensions and origin.
+     * @param {RendererMetrics} rendererMetrics - The extracted immutable origin definitions.
+     * @returns {void} Returns nothing.
      */
     setRendererMetrics(rendererMetrics: RendererMetrics): void;
     /**
-     * Sets the fill color of the text based on its state.
+     * Internal utility method swapping the drawing context paint buckets directly.
      *
-     * @param {boolean} state - Whether the text should use the active or inactive color.
+     * @param {boolean} state - Flag evaluating to true for active and false for inactive coloring themes.
+     * @returns {void} Returns nothing.
      */
     protected setTextState(state: boolean): void;
     /**
-     * Sets the text color to the active theme color.
+     * Sets the context canvas text stroke/fill strictly to the active color theme.
+     *
+     * @returns {void} Returns nothing.
      */
     setActiveText(): void;
     /**
-     * Sets the text color to the inactive theme color.
+     * Sets the context canvas text stroke/fill strictly to the inactive/faded color theme.
+     *
+     * @returns {void} Returns nothing.
      */
     setInactiveText(): void;
     /**
-     * Sets the current font size from predefined values.
+     * Assigns the drawing bounds scalar based on pre-compiled values.
      *
-     * @param {FontSize} fontSize - The enum value representing the desired size.
+     * @param {FontSize} fontSize - The enum target corresponding to an active dictionary size entry.
+     * @returns {void} Returns nothing.
      */
     setTextSize(fontSize: FontSize): void;
     /**
-     * Configures horizontal and vertical text alignment.
+     * Direct wrapper defining the geometric justification rules inside a bounded region.
      *
-     * @param {FontAlign} fontAlign - Horizontal alignment value.
-     * @param {FontVerticalAlign} fontVerticalAlign - Vertical alignment value.
+     * @param {FontAlign} fontAlign - Horizontal alignment orientation vector.
+     * @param {FontVerticalAlign} fontVerticalAlign - Vertical alignment position plane.
+     * @returns {void} Returns nothing.
      */
     setTextAlign(fontAlign: FontAlign, fontVerticalAlign: FontVerticalAlign): void;
     /**
-     * Renders text on the HUD area using relative coordinates.
+     * Calculates relative coordinates and natively projects text bounds towards the HUD zone.
      *
-     * @param {string} text - The string to be rendered.
-     * @param {Coordinate} coordinate - Normalized coordinates (0 to 1) within the HUD area.
+     * @param {string} text - The raw formatted string.
+     * @param {Coordinate} coordinate - Float coordinate vectors from 0.0 to 1.0 restricted to the HUD bounds.
+     * @returns {void} Returns nothing.
      */
     textOnHud(text: string, coordinate: Coordinate): void;
     /**
-     * Renders text on the main display area using relative coordinates.
+     * Calculates relative coordinates and natively projects text bounds towards the Main Display zone.
      *
-     * @param {string} text - The string to be rendered.
-     * @param {Coordinate} coordinate - Normalized coordinates (0 to 1) within the display area.
+     * @param {string} text - The raw formatted string sequence.
+     * @param {Coordinate} coordinate - Float coordinate vectors from 0.0 to 1.0 referencing the Main Display bounds.
+     * @returns {void} Returns nothing.
      */
     textOnDisplay(text: string, coordinate: Coordinate): void;
     /**
-     * Retrieves debug information about the text system.
+     * Aggregates configuration details requested by the engine's Debugging Dashboard hook.
      *
-     * @returns {Record<string, string | number | boolean>} The debug data.
+     * @returns {Record<string, string | number | boolean>} A shallow payload of visual metrics dictating memory cache state.
      */
     getDebugData(): Record<string, string | number | boolean>;
 }

package/dist/types/core/module/time/GameTime.d.ts

@@ -2,30 +2,39 @@ import { Debuggable } from '../../types/Interfaces';
 import { Time } from '../../types/modules';
 import { Serializable } from '../../types/Interfaces';
 /**
- * Manages game time, frame rates, and tick intervals.
- * Handles the game loop timing and debug statistics (FPS, TPS).
+ * Module responsible for managing the logical engine clock, hardware frame rates, and tick intervals.
+ *
+ * It decouples the deterministic game logic "ticks" from the unpredictable visual frame rate
+ * of the browser canvas. By separating `update` loops from visual rendering, it ensures
+ * consistent gameplay speed calculations (like difficulty progression) regardless of the
+ * host device's performance capabilities.
  */
 export default class GameTime implements Time, Debuggable, Serializable {
-    protected _accumulatedTime: number;
+    protected _tickAccumulator: number;
     /** The tick interval at the start of the game session. Used for resets. */
-    protected _initialTickInterval: number;
-    protected _minTickInterval: number;
-    protected _tickInterval: number;
-    protected _fps: number;
-    protected _tps: number;
-    protected _tickCounter: number;
-    protected _timeSinceLastTpsUpdate: number;
+    private _initialTickInterval;
+    private _minTickInterval;
+    private _tickInterval;
+    private _fps;
+    private _tps;
+    private _tickCounter;
+    private _totalTicks;
+    private _timeSinceLastTpsUpdate;
+    private _totalElapsedTime;
     serialId: string;
     /**
-     * Initializes the time module.
-     * Resets all timers and counters.
+     * Initializes the time module's core state.
+     * Resets all internal timers and statistical accumulators securely.
+     *
+     * @returns {void} Returns nothing.
      */
     setup(): void;
     /**
-     * Updates the time accumulator and calculates FPS/TPS.
-     * Should be called once per frame.
+     * Updates the internal time accumulator and calculates physical FPS/TPS.
+     * Must be invoked strictly once per hardware visual frame.
      *
-     * @param {number} deltaTime - Time elapsed since last frame in milliseconds.
+     * @param {number} deltaTime - Time physically elapsed since the last rendering frame in milliseconds.
+     * @returns {void} Returns nothing.
      */
     update(deltaTime: number): void;
     /**
@@ -36,7 +45,9 @@ export default class GameTime implements Time, Debuggable, Serializable {
      */
     shouldTick(): boolean;
     /**
-     * Resets the time accumulator and debug counters.
+     * Safely resets the time accumulator and all debug statistical counters.
+     *
+     * @returns {void} Returns nothing.
      */
     reset(): void;
     /**
@@ -75,8 +86,31 @@ export default class GameTime implements Time, Debuggable, Serializable {
     setTickInterval(interval: number): void;
     setMinTickInterval(interval: number): void;
     /**
-     * Captures the current tick interval as the initial state.
-     * This is useful for restoring the game speed on reset.
+     * Gets the total number of ticks since the game started.
+     *
+     * @returns {number} Total tick count.
+     */
+    get totalTicks(): number;
+    /**
+     * Gets the total elapsed time in milliseconds.
+     *
+     * @returns {number} Elapsed time in ms.
+     */
+    get elapsedTime(): number;
+    /**
+     * Checks if the current total tick count is a multiple of the provided interval.
+     *
+     * @param {number} interval - The tick interval to check.
+     * @returns {boolean} True if the current tick is a multiple of the interval.
+     */
+    isTickEvery(interval: number): boolean;
+    /**
+     * Captures the current tick interval as the deterministic initial baseline state.
+     *
+     * This is useful for restoring the intended baseline game speed on session
+     * resets rather than reverting to the engine's hardcoded default.
+     *
+     * @returns {void} Returns nothing.
      */
     captureInitialState(): void;
 }

package/dist/types/core/types/Interfaces.d.ts

@@ -7,6 +7,8 @@ export interface Initializable {
     /**
      * Initializes the module.
      * Should be called after the instance is created and dependencies are injected.
+     *
+     * @returns {void} Returns nothing.
      */
     setup(): void;
 }
@@ -21,6 +23,7 @@ export interface StateSyncable {
      * Binds the module to the game state.
      *
      * @param {State} state - The game state instance to sync with.
+     * @returns {void} Returns nothing.
      */
     syncState(state: State): void;
 }
@@ -32,6 +35,7 @@ export interface RendererInitializable {
      * Initializes the renderer with calculated screen metrics.
      *
      * @param {RendererMetrics} rendererMetrics - The layout metrics (dimensions, origins).
+     * @returns {void} Returns nothing.
      */
     setup(rendererMetrics: RendererMetrics): void;
 }
@@ -48,6 +52,17 @@ export interface Debuggable {
 }
 export interface Serializable {
     serialId: string;
+    /**
+     * Serializes the object state into a string.
+     *
+     * @returns {string} The serialized string payload.
+     */
     serialize(): string;
+    /**
+     * Deserializes the object state from a string payload.
+     *
+     * @param {string} data - The string payload.
+     * @returns {void} Returns nothing.
+     */
     deserialize(data: string): void;
 }

package/dist/types/core/types/Types.d.ts

@@ -110,5 +110,6 @@ export interface GameEvent {
  * Callback function type for handling input events.
  *
  * @param {GameEvent} event - The event data containing key, type, and module access.
+ * @returns {void} Returns nothing.
  */
 export type ControlCallback = (event: GameEvent) => void;

package/dist/types/core/types/enums.d.ts

@@ -10,7 +10,8 @@ export declare enum Color {
     PURPLE = "rgb(128, 0, 128)",
     RED = "rgb(128, 0, 0)",
     YELLOW = "rgb(128, 128, 0)",
-    INACTIVE = "rgb(166, 183, 165)"
+    INACTIVE = "rgb(166, 183, 165)",
+    SHADOW = "rgb(93, 105, 92)"
 }
 /**
  * Enumerates all available horizontal text alignments.