brick-engine-js 1.0.1

package/docs/reference/modules/Debugger.adoc

@@ -0,0 +1,71 @@
+= Debugger Class Reference
+:description: Real-time, HTML-based overlay for monitoring the state of all engine modules.
+:keywords: debug, monitoring, overlay, diagnostics
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `Debugger` class provides a real-time, HTML-based overlay for monitoring the state of all engine modules. It automatically identifies and extracts data from any module that implements the `xref:../interfaces/Debuggable.adoc[Debuggable]` interface.
+
+== API Reference
+
+=== `setup(): void`
+
+Initializes the debugger's DOM structure.
+
+**Behavior**
+
+Creates the main debugger container (`<details id="debugger">`) and appends it to the document body. It scans all registered `xref:../interfaces/GameModules.adoc[GameModules]` and prepares the UI sections for those that expose debug information via `getDebugData`.
+
+'''
+
+=== `setGameModules(gameModules: GameModules): void`
+
+Updates the active game modules being monitored by the debugger.
+
+**Parameters**
+
+[cols="1,1,3", options="header"]
+|===
+|Name |Type |Description
+|`gameModules` |`xref:../interfaces/GameModules.adoc[GameModules]` | The new instance of game modules to track.
+|===
+
+**Behavior**
+
+When switching games or game states, this method replaces the internal module references and automatically triggers a UI rebuild by calling `setup()`. Importantly, it preserves the `open` state of any currently expanded module details (`<details>` tags) so the layout does not unexpectedly collapse when the new modules load.
+
+'''
+
+=== `update(): Promise<void>`
+
+Refreshes the overlay with new data from the modules.
+
+**Behavior**
+
+Executes at a frequency controlled by `configs.game.debugger.msInterval`. It fetches the latest metrics from all `Debuggable` modules and updates the corresponding UI nodes. To maintain performance, it uses a precise timing check and caches DOM references.
+
+== Configuration
+
+The debugger behavior is controlled via the main `configs.ts` file:
+
+*   `configs.game.debugger.enabled`: Global toggle to enable/disable the overlay.
+*   `configs.game.debugger.msInterval`: The refresh rate (in milliseconds). Higher values reduce CPU usage.
+
+== Implementation
+
+Modules wishing to appear in the debugger must implement the `Debuggable` interface:
+
+[source,typescript]
+----
+interface Debuggable {
+  getDebugData(): Record<string, string | number | boolean>;
+}
+----

package/docs/reference/modules/DisplayRenderer.adoc

@@ -0,0 +1,55 @@
+= DisplayRenderer Module Reference
+:description: Responsible for drawing the main game grid and active bricks.
+:keywords: rendering, display, grid, graphics
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `DisplayRenderer` is responsible for drawing the main game grid and the active bricks. 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`
+
+Initializes the renderer and pre-calculates the static scene.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`rendererMetrics` |`xref:../types/RendererMetrics.adoc[RendererMetrics]` |The layout metrics calculated by `xref:GameRenderer.adoc[GameRenderer]`.
+|===
+
+**Behavior**
+
+Stores the layout metrics for use during drawing. It also initializes an off-screen graphics buffer to pre-render the static background and borders, significantly improving performance by avoiding redundant draw calls every frame.
+
+
+'''
+
+=== `render(grid: Cell[][]): void`
+
+Executes the main display drawing logic.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`grid` |`xref:../types/Cell.adoc[Cell][][]` |The current matrix of game cells.
+|===
+
+**Behavior**
+
+1.  Renders the pre-cached static background.
+2.  Iterates through the active `grid` state and draws each occupied cell using the previously stored metric offsets.
+
+

package/docs/reference/modules/Game.adoc

@@ -0,0 +1,256 @@
+= Game Class Reference
+:description: The heart of the application, managing the game loop and orchestration of modules.
+:keywords: core, game-loop, architecture, orchestration
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `Game` class is the heart of your application. It manages the game loop (ticks and frames), initialization of core modules, session restoration, and integration with P5.js. All games must extend this class.
+
+== Properties
+
+[cols="1,1,2"]
+|===
+|Property |Type |Description
+|`gameId` |`string` |Unique identifier for the specific game implementation. Used as a namespace for local storage and other session-specific requirements logic.
+|`modules` |`xref:../interfaces/GameModules.adoc[GameModules]` |Access to all engine modules (grid, control, state, etc.).
+|===
+
+== API Reference
+
+
+'''
+
+=== `addSerializable(serializable: Serializable): void`
+
+Registers a custom object or module for session persistence.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`serializable` |`xref:../interfaces/Serializable.adoc[Serializable]` |The custom object to be saved in the active session.
+|===
+
+**Behavior**
+
+This method serves to add new custom serializables of the game being developed. This allows the game to save custom properties (like specific player power-ups or puzzle progress) in the browser session. These properties can be automatically restored if the user leaves and returns, continuing the game from the `PLAYING` state. Note that engine modules implementing `Serializable` are automatically detected and added.
+
+
+'''
+
+=== `update(deltaTime: number): void`
+
+Abstract method for processing game logic.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`deltaTime` |`number` |Time elapsed since the last tick (in milliseconds).
+|===
+
+'''
+
+=== `setSwitchHandler(handler: (newGame: Game) => void): void`
+
+Registers the callback to be used when a game requests to switch to another game.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|`handler` |`Function` |The callback function receiving the target `xref:../modules/Game.adoc[Game]` instance.
+|===
+
+**Behavior**
+
+This method is used by the engine orchestrator (typically in `main.ts`) to define how game switches should be handled (e.g., re-binding controls, resetting the debugger). It allows the `Game` class to remain decoupled from the specific implementation of the menu or other games.
+
+'''
+
+=== `propagateSwitchHandler(game: Game): void`
+
+Copies the active switch handler from one game instance to another.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`game` |`xref:../modules/Game.adoc[Game]` |The source game instance providing the handler.
+|===
+
+**Behavior**
+
+Ensures continuity of the orchestration logic during a switch. When a new game is instantiated and about to become active, this method is called to pass the `_switchHandler` from the current `activeGame` to the new one.
+
+'''
+
+=== `update(deltaTime: number): void`
+
+Abstract method for processing game logic.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`deltaTime` |`number` |Time elapsed since the last tick (in milliseconds).
+|===
+
+**Behavior**
+
+Called by the engine on every game logic tick, but **only** when the game state is `playing`. The tick frequency is controlled by `configs.game.tickInterval`.
+
+**Example**
+
+[source,typescript]
+----
+update(deltaTime: number): void {
+    const { grid } = this.modules;
+    grid.shiftRowsDown(1);
+}
+----
+
+
+'''
+
+=== `render(): void`
+
+Abstract method for processing visual frames.
+
+**Behavior**
+
+Called by the engine on every render frame (based on browser refresh rate, typically 60fps). Use this for animations, particles, or visual effects that do not affect the logical game state.
+
+**Example**
+
+[source,typescript]
+----
+render(): void {
+    // Logic for smooth animations
+}
+----
+
+
+'''
+
+=== `setupGame(): void`
+
+Abstract method for setting up the specific game instance.
+
+**Behavior**
+
+Called once after all engine modules are initialized and linked. Use this to set initial player state, subscribe to custom controls, or prepare level data.
+
+**Example**
+
+[source,typescript]
+----
+setupGame(): void {
+    this.modules.text.setTextSize(FontSize.MEDIUM);
+}
+----
+
+
+'''
+
+
+
+=== `drawTitleScreen(): void`
+
+Abstract method for rendering the game's welcome screen.
+
+**Behavior**
+
+Called when the engine is powered ON but the game has not yet been started. Executed during the main draw loop instead of `update` and `render`.
+
+
+'''
+
+=== `drawGameOverScreen(): void`
+
+Abstract method for rendering the screen after a game ends.
+
+**Behavior**
+
+Called when the game state is `gameOver`. Executed as the primary rendering logic during Game Over, replacing the standard `render()` call to allow for clean menus or high-score displays.
+
+
+'''
+
+=== `switchGame(newGame: Game): void`
+
+Switches execution to a new game instance.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`newGame` |`Game` |The instance of the new game class to load.
+|===
+
+**Behavior**
+
+Destroys the current game instance (cleaning up listeners and stopping sound) and passes the new instance to the registered `_switchHandler`. This is the core mechanism for moving between different games or menus.
+
+> [!NOTE]
+> The switch handler must be set or propagated before calling this method, otherwise an error will be logged.
+
+**Example**
+
+[source,typescript]
+----
+this.switchGame(new MyOtherGame(this.p, this.view));
+----
+
+
+'''
+
+=== `destroy(): void`
+
+Cleans up the game instance.
+
+**Behavior**
+
+Stops the P5.js loop, unbinds all control event listeners, and stops all playing sounds. Use this before disposing of a game instance to prevent memory leaks.
+
+== Session Management
+
+The `Game` base class automatically orchestrates gameplay sessions by subscribing to system-level `xref:GameState.adoc[GameState]` events:
+
+*   **Restoring Sessions**: When the state changes to `PLAYING`, the `Game` checks if there are any active sessions stored for its registered `Serializable` instances. If an active session is detected, it triggers a UI modal asking the user if they wish to resume their previous session.
+*   **Clearing Sessions**: The active session is automatically wiped when the state changes to `GAME_OVER`, ensuring that players do not resume a lost game.
+
+== Client State Snapshot (Reset)
+
+To provide a seamless developer experience, the `Game` class implements an internal mechanism to transparently cache and restore custom client properties. 
+
+When a game is instantiated and its `setupGame()` method is invoked, the base `Game` orchestrates a capture of the client's custom properties using the `xref:InitialStateSnapshot.adoc[InitialStateSnapshot]` utility. This ensures that any attributes added by the developer (e.g., player lives, custom counters) are saved in memory without requiring manual implementation.
+
+When the user triggers a **RESET** action, the `Game` class automatically uses this internal snapshot to restore the custom properties back to their original values, eliminating the need for developers to manually reset their own state variables.
+
+== Automated System Controls
+
+The `Game` base class automatically registers listeners for system-level buttons:
+
+*   **POWER**: Toggles engine state.
+*   **SOUND**: Toggles master mute.
+*   **COLOR**: Toggles theme color mode.
+*   **RESET**: Resets the grid, score, clears the active session, and resets the game state.
+*   **START_PAUSE**: Manages the game lifecycle:
+** Starts the game from the Title Screen.
+** Toggles pause during gameplay.
+** Restarts the game immediately if in a Game Over state (via `resetGameOver`), and clears the active session.
+*   **EXIT**: Clears the active session and performs a hard stop of the draw loop. In server mode, the orchestrator typically uses the switch handler to return to the `GameMenu`.

package/docs/reference/modules/GameControl.adoc

@@ -0,0 +1,139 @@
+= GameControl Module Reference
+:description: Handles user input from physical keyboards and virtual buttons.
+:keywords: input, control, keyboard, interaction
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameControl` module handles user input from physical keyboards and virtual buttons. It provides an event-based system for reacting to player actions.
+
+== Supported Keys (`ControlKey`)
+
+The engine maps physical keys to virtual engine keys:
+
+*   `xref:../enums/ControlKey.adoc[UP]` / `xref:../enums/ControlKey.adoc[DOWN]` / `xref:../enums/ControlKey.adoc[LEFT]` / `xref:../enums/ControlKey.adoc[RIGHT]`: Directional controls.
+*   `xref:../enums/ControlKey.adoc[ACTION]`: Primary action button.
+*   `xref:../enums/ControlKey.adoc[START_PAUSE]`: Toggles game start/pause.
+*   `xref:../enums/ControlKey.adoc[RESET]`: Soft reset of the game session.
+*   `xref:../enums/ControlKey.adoc[SOUND]`: Toggles master audio mute.
+*   `xref:../enums/ControlKey.adoc[COLOR]`: Toggles theme color mode.
+*   `xref:../enums/ControlKey.adoc[POWER]`: Main engine power toggle.
+*   `xref:../enums/ControlKey.adoc[EXIT]`: Hard stop of the engine.
+
+== API Reference
+
+=== `subscribe(key: ControlKey, type: ControlEventType, callback: ControlCallback): void`
+
+Registers a callback for a specific input event.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`key` |`xref:../enums/ControlKey.adoc[ControlKey]` |The virtual key to monitor (e.g., `ControlKey.ACTION`).
+|`type` |`xref:../enums/ControlEventType.adoc[ControlEventType]` |The type of trigger (`PRESSED` or `HELD`).
+|`callback` |`xref:../types/ControlCallback.adoc[ControlCallback]` |The function to execute when the event occurs.
+|===
+
+**Behavior**
+
+Adds the callback to the internal subscription list. Multiple callbacks can be registered for the same key/type combination.
+
+**Example**
+
+[source,typescript]
+----
+control.subscribe(ControlKey.ACTION, ControlEventType.PRESSED, (event) => {
+    console.log('Action button pressed!');
+});
+----
+
+
+'''
+
+=== `unsubscribe(key: ControlKey, type: ControlEventType, callback: ControlCallback): void`
+
+Removes an existing subscription.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`key` |`xref:../enums/ControlKey.adoc[ControlKey]` |The virtual key.
+|`type` |`xref:../enums/ControlEventType.adoc[ControlEventType]` |The trigger type.
+|`callback` |`xref:../types/ControlCallback.adoc[ControlCallback]` |The reference to the function to remove.
+|===
+
+**Behavior**
+
+Removes the specified callback from the list. If the callback is not found, the operation does nothing.
+
+
+'''
+
+=== `bindControls(): void`
+
+Attaches low-level event listeners to the environment.
+
+**Behavior**
+
+Enables keyboard and button listeners. This is called automatically by the engine during setup.
+
+
+'''
+
+=== `unbindControls(): void`
+
+Detaches all input listeners and clears subscriptions.
+
+**Behavior**
+
+Removes all low-level event listeners and wipes the internal subscription map. Called automatically during engine destruction.
+
+
+'''
+
+=== `notify(key: ControlKey, type: ControlEventType): void`
+
+Manually triggers an input event.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`key` |`xref:../enums/ControlKey.adoc[ControlKey]` |The key to notify.
+|`type` |`xref:../enums/ControlEventType.adoc[ControlEventType]` |The trigger type to simulate.
+|===
+
+**Behavior**
+
+Executes all callbacks associated with the given key and event type, subject to the following state-based rules:
+
+*   **System Off (`isOff()`)**: Only the `xref:../enums/ControlKey.adoc[POWER]` key is processed. All other keys are ignored.
+*   **Active States (`!isStarted() || isPlaying() || isGameOver()`)**: All keys are processed normally.
+*   **Paused State (`isPaused()`)**: Only system keys (e.g., `START_PAUSE`, `SOUND`, `COLOR`, `RESET`, `EXIT`) are processed. Gameplay keys are ignored.
+
+*Throws an error* if the game modules have not been initialized. It is primarily used internally by the input handler but can be used for automated testing or input simulation.
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.
+
+**Returns**
+
+`Record<string, string | number | boolean>` - Object containing the number of `total_subscribers` and `tracked_keys`.
+
+