brick-engine-js 1.0.1

package/docs/reference/modules/GameState.adoc

@@ -0,0 +1,318 @@
+= GameState Module Reference
+:description: Single source of truth for the game lifecycle and persistent user preferences.
+:keywords: state, lifecycle, persistence, localstorage
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameState` module acts as the central, single source of truth for the game's lifecycle and user preferences. It handles persistence to `LocalStorage` for settings and high scores.
+
+== Centralized Persistence
+
+As defined in the Architectural Patterns, `GameState` is responsible for all `LocalStorage` logic. Other modules (like `xref:GameSound.adoc[GameSound]`) must sync their internal state with this module via the `xref:../interfaces/StateSyncable.adoc[StateSyncable]` interface.
+
+== Persistence vs. Session
+
+It is important to understand the boundary between `GameState` persistence and the `Game` Session management:
+
+*   **GameState Persistence**: Manages **long-term, cross-session** data. It persists user preferences (like `muted`, `colorEnabled`) to `LocalStorage`. This data remains even after a Game Over or when completely restarting the engine.
+*   **Game Session**: Managed by the `xref:Game.adoc[Game]` class utilizing a `SessionManager` and `Serializable` modules. A Session saves the **transient, intra-session** progress (e.g., the active grid layout, the current score, the current level). Session data is automatically cleared when the game reaches a `GAME_OVER` state, when the `RESET` button is pressed, or when the player manually uses the `EXIT` control.
+
+== API Reference
+
+=== `isOn(): boolean`
+
+Checks if the game system is powered up.
+
+**Returns**
+
+`boolean` - `true` if system is on.
+
+
+'''
+
+=== `isOff(): boolean`
+
+Checks if the game system is powered down.
+
+**Returns**
+
+`boolean` - `true` if system is off.
+
+
+'''
+
+=== `isStarted(): boolean`
+
+Checks if a game session is active (passed the title screen).
+
+**Returns**
+
+`boolean` - `true` if the game has started.
+
+
+'''
+
+=== `isPlaying(): boolean`
+
+Checks if the game loop is actively updating logic.
+
+**Returns**
+
+`boolean` - `true` if gameplay is active and not paused.
+
+
+'''
+
+=== `isPaused(): boolean`
+
+Checks if the game is currently paused.
+
+**Returns**
+
+`boolean` - `true` if the game is started but halted.
+
+
+'''
+
+=== `isGameOver(): boolean`
+
+Checks if the current session has ended in a Game Over.
+
+**Returns**
+
+`boolean` - `true` if player has lost.
+
+
+'''
+
+=== `turnOn(): void`
+
+Powers on the game system.
+
+**Behavior**
+
+Sets the `on` property to true and ensures `start`, `playing`, and `gameOver` are initialized to false.
+
+
+'''
+
+=== `turnOff(): void`
+
+Powers off the game system.
+
+**Behavior**
+
+Sets the `on` property to false and wipes transient state.
+
+
+'''
+
+=== `startGame(): void`
+
+Initiates gameplay from the title screen.
+
+**Behavior**
+
+Sets `start` and `playing` to true. This method only has effect if the system is already `on`.
+
+
+'''
+
+=== `exitGame(): void`
+
+Ends the session and returns to the title screen.
+
+**Behavior**
+
+Resets `start`, `playing`, and `gameOver` to false.
+
+
+'''
+
+=== `pause(): void`
+
+Halts gameplay logic.
+
+**Behavior**
+
+Sets `playing` to false. Only works if the game is already started.
+
+
+'''
+
+=== `resume(): void`
+
+Restarts gameplay logic from a paused state.
+
+**Behavior**
+
+Sets `playing` to true.
+
+
+'''
+
+=== `triggerGameOver(): void`
+
+Forces the game into a Game Over state.
+
+**Behavior**
+
+Sets `playing` to false and `gameOver` to true.
+
+
+'''
+
+=== `resetGame(): void`
+
+Prepares the state for a new round (hard restart).
+
+**Behavior**
+
+Clears the `gameOver` flag and resumes `playing` status. Unlike `resetGameOver`, this is intended for a complete session reset from any state.
+
+
+'''
+
+=== `resetGameOver(): void`
+
+Resets the state specifically after a Game Over to allow immediate restart.
+
+**Behavior**
+
+Sets `gameOver` to false and `playing` to true. This is the recommended way to handle "Try Again" scenarios.
+
+
+'''
+
+=== `isColorEnabled(): boolean`
+
+Checks if theme color mode is active.
+
+**Returns**
+
+`boolean` - `true` if color mode is on.
+
+
+'''
+
+=== `setColorEnabled(value: boolean): void`
+
+Sets the color mode preference.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`value` |`boolean` |New color mode status.
+|===
+
+**Behavior**
+
+Updates the property and automatically persists the value to `LocalStorage`.
+
+
+'''
+
+=== `toggleColorEnabled(): void`
+
+Toggles the current color mode.
+
+
+'''
+
+=== `isMuted(): boolean`
+
+Checks if master audio is muted.
+
+**Returns**
+
+`boolean` - `true` if sound is disabled.
+
+
+'''
+
+=== `setMuted(value: boolean): void`
+
+Sets the master mute status.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`value` |`boolean` |New mute status.
+|===
+
+**Behavior**
+
+Updates the property and persists it to `LocalStorage`.
+
+
+'''
+
+=== `toggleMuted(): void`
+
+Toggles the master mute status.
+
+
+'''
+
+
+
+=== `subscribe(property: StateProperty, callback: (value: boolean | number) => void): void`
+
+Registers a listener for state changes.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`property` |`xref:../enums/StateProperty.adoc[StateProperty]` |The specific property to monitor.
+|`callback` |`Function` |The function to execute on change.
+|===
+
+**Example**
+
+[source,typescript]
+----
+state.subscribe(StateProperty.GAME_OVER, (isOver) => {
+    if (isOver) {
+        this.modules.sound.play(Sound.GAMEOVER);
+    }
+});
+----
+
+
+'''
+
+=== `unsubscribe(property: StateProperty, callback: (value: boolean | number) => void): void`
+
+Removes a state change listener.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`property` |`xref:../enums/StateProperty.adoc[StateProperty]` |The property being monitored.
+|`callback` |`Function` |The reference to the callback to remove.
+|===
+
+
+'''
+
+
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.

package/docs/reference/modules/GameText.adoc

@@ -0,0 +1,139 @@
+= GameText Module Reference
+:description: Handles rendering of pixelated text on the game display and HUD.
+:keywords: text, typography, rendering, display, retro
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameText` module handles rendering pixelated text on the game display. It manages font initialization, sizing, and ensures text is scaled correctly relative to the canvas size.
+
+== API Reference
+
+=== `setTextSize(size: FontSize): void`
+
+Sets the current font size from predefined responsive values.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`size` |`xref:../enums/FontSize.adoc[FontSize]` |Enum value (`EXTRA_SMALL` to `EXTRA_LARGE`).
+|===
+
+**Behavior**
+
+Applies the pre-calculated pixel size to the P5.js context based on the current container dimensions.
+
+**Example**
+
+[source,typescript]
+----
+this.modules.text.setTextSize(FontSize.LARGE);
+----
+
+
+'''
+
+=== `setTextAlign(align: FontAlign, verticalAlign: FontVerticalAlign): void`
+
+Configures the alignment of rendered text.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`align` |`xref:../enums/FontAlignment.adoc[FontAlign]` |Horizontal alignment (LEFT, CENTER, RIGHT).
+|`verticalAlign` |`xref:../enums/FontAlignment.adoc[FontVerticalAlign]` |Vertical alignment (TOP, CENTER, BOTTOM).
+|===
+
+
+'''
+
+=== `setActiveText(): void`
+
+Sets the text fill color to the active theme color.
+
+
+'''
+
+=== `setInactiveText(): void`
+
+Sets the text fill color to the inactive theme color.
+
+
+'''
+
+=== `textOnDisplay(text: string, coordinate: Coordinate): void`
+
+Renders text on the main game display area.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`text` |`string` |The message to display.
+|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Normalized coordinates (0.0 to 1.0) within the game grid area.
+|===
+
+**Example**
+
+[source,typescript]
+----
+text.textOnDisplay('PAUSED', { x: 0.5, y: 0.5 });
+----
+
+
+'''
+
+=== `textOnHud(text: string, coordinate: Coordinate): void`
+
+Renders text on the side HUD area.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`text` |`string` |The message to display.
+|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Normalized coordinates (0.0 to 1.0) within the HUD container.
+|===
+
+
+'''
+
+=== `setRendererMetrics(metrics: RendererMetrics): void`
+
+Updates the coordinate conversion reference.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`metrics` |`xref:../types/RendererMetrics.adoc[RendererMetrics]` |The updated renderer dimensions and origins.
+|===
+
+**Behavior**
+
+Called by the engine during initialization. These metrics are used by `textOnHud` and `textOnDisplay` to calculate absolute pixel positions.
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.
+
+**Returns**
+
+`Record<string, string | number | boolean>` - Object containing the current font family and pre-calculated size count.

package/docs/reference/modules/GameTime.adoc

@@ -0,0 +1,141 @@
+= GameTime Module Reference
+:description: Manages the engine's logical clock, decoupling game logic ticks from the visual frame rate.
+:keywords: time, clock, tick, interval, game-loop
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameTime` module manages the engine's logical clock. It decouples game logic "ticks" from the visual frame rate, ensuring consistent gameplay speed regardless of the device's performance.
+
+== API Reference
+
+=== `tickInterval: number`
+
+Getter/Setter for the game logic speed in milliseconds.
+
+**Returns**
+
+`number` - The current time between logic ticks.
+
+**Behavior**
+
+Lowering this value makes the game run faster (e.g., used for difficulty progression).
+
+
+'''
+
+=== `shouldTick(): boolean`
+
+Determines if a logic update should be executed.
+
+**Returns**
+
+`boolean` - `true` if the internal accumulator has exceeded the `tickInterval`.
+
+**Behavior**
+
+Called by the main loop. If it returns true, it automatically subtracts the `tickInterval` from the accumulator to maintain a stable clock.
+
+
+'''
+
+=== `update(deltaTime: number): void`
+
+Advances the internal time accumulator.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`deltaTime` |`number` |Time elapsed since the last render frame (in milliseconds).
+|===
+
+
+'''
+
+=== `reset(): void`
+
+Clears the time accumulator.
+
+**Behavior**
+
+Prevents a "burst" of logic updates after resuming from a long pause or game restart.
+
+
+'''
+
+=== `incrementTickInterval(amount: number): void`
+
+Slows down the game by increasing the time between ticks.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |Milliseconds to add to the interval.
+|===
+
+
+'''
+
+=== `decrementTickInterval(amount: number): void`
+
+Speeds up the game by decreasing the time between ticks.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |Milliseconds to subtract from the interval.
+|===
+
+
+'''
+
+=== `setTickInterval(interval: number): void`
+
+Sets the tick interval exactly to the specified value.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`interval` |`number` |The new interval between logic updates (in milliseconds).
+|===
+
+
+'''
+
+=== `setMinTickInterval(interval: number): void`
+
+Sets the minimum limit for the tick interval, preventing the game from speeding up beyond this point.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`interval` |`number` |The minimum interval allowed (in milliseconds).
+|===
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.
+
+**Returns**
+
+`Record<string, string | number | boolean>` - Object containing `fps` (Frames Per Second) and `tps` (Ticks Per Second).

package/docs/reference/modules/HudRenderer.adoc

@@ -0,0 +1,56 @@
+= HudRenderer Module Reference
+:description: Manages the visualization of the Head-Up Display, including scores, levels, and system status.
+:keywords: hud, rendering, ui, display, graphics
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `HudRenderer` manages the visualization of the Head-Up Display, including scores, levels, system status, and the specialized HUD grid. It implements the standard `xref:../interfaces/modules/Renderer.adoc[Renderer]` interface and is managed by the `xref:GameRenderer.adoc[GameRenderer]`.
+
+== API Reference
+
+=== `setup(rendererMetrics: RendererMetrics): void`
+
+Pre-calculates static HUD geometry.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`rendererMetrics` |`xref:../types/RendererMetrics.adoc[RendererMetrics]` |The layout metrics calculated by `xref:GameRenderer.adoc[GameRenderer]`.
+|===
+
+**Behavior**
+
+Calculates and caches the absolute pixel positions for HUD borders and grid cells. This ensures that the HUD remains perfectly aligned regardless of the display resolution.
+
+
+'''
+
+=== `render(grid: Cell[][], modules: GameModules): void`
+
+Main HUD drawing orchestration.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`grid` |`xref:../types/Cell.adoc[Cell][][]` |The main game grid (unused, but required by interface).
+|`modules` |`xref:../interfaces/GameModules.adoc[GameModules]` |Access to all modules (Text, Score, State, etc.) for dynamic data extraction.
+|===
+
+**Behavior**
+
+1.  Clears the HUD area.
+2.  Renders the pre-cached static borders.
+3.  Draws the dynamic content (current score, high score, level, and game state messages).
+4.  Renders the 4x4 HUD grid state.

package/docs/reference/modules/InitialStateSnapshot.adoc

@@ -0,0 +1,47 @@
+= InitialStateSnapshot Reference
+:description: Utility class responsible for capturing and restoring the initial state of custom client properties in the Game.
+:keywords: state, snapshot, cache, memory, reset
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:idprefix:
+:idseparator: -
+
+The `InitialStateSnapshot` class manages the transparent caching of a game's state. It is an internal orchestrator utilized by the `Game` base class to capture the properties added by the developer during `setupGame()` and allows restoring them when the game is reset.
+
+== Methods
+
+=== `captureBaseProperties`
+
+Captures the base properties of the instance before any custom client properties are added. In the engine's architecture, this should be called at the very end of the base `Game` constructor, establishing the baseline for what should be ignored during the snapshot phase automatically.
+
+[cols="1,1,3", options="header"]
+|===
+|Parameter |Type |Description
+|`instance` |`object` |The object instance to extract keys from.
+|===
+
+'''
+
+=== `captureInitialState`
+
+Stores the initial state of custom client properties. It selectively clones properties that were not present in the base properties and are not functions, using deep copying (`structuredClone`) with a fallback to referencing.
+
+[cols="1,1,3", options="header"]
+|===
+|Parameter |Type |Description
+|`instance` |`object` |The object instance containing custom properties.
+|===
+
+'''
+
+=== `restoreInitialState`
+
+Restores the captured custom properties back to the instance, effectively resetting the client's state.
+
+[cols="1,1,3", options="header"]
+|===
+|Parameter |Type |Description
+|`instance` |`object` |The object instance to restore properties onto.
+|===