brick-engine-js 1.0.1

package/docs/reference/modules/GameHudGrid.adoc

@@ -0,0 +1,38 @@
+= GameHudGrid Reference
+:description: Specialized 4x4 grid implementation for HUD elements and meta-information.
+:keywords: hud, grid, ui, display
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameHudGrid` is a specialized implementation of the `GameGrid` class. It is hard-coded to a **4x4** dimension and is intended for use in the HUD area to display meta-information, such as "Next Piece" in a Tetris-style game.
+
+== Inheritance
+
+`GameHudGrid` extends xref:GameGrid.adoc[GameGrid]. It inherits all methods for filling areas, stamping pieces, and checking occupancy.
+
+== Usage
+
+Accessible via `modules.hudGrid`.
+
+[source,typescript]
+----
+const { hudGrid } = this.modules;
+
+// Reset HUD grid for a new piece
+hudGrid.resetGrid();
+
+// Stamp the "Next Piece" into the 4x4 HUD grid
+hudGrid.stampPiece(nextPieceCoords, 1, Color.BLUE);
+----
+
+== Implementation Specifics
+
+The `GameHudGrid` overrides the dimensions provided in the global configuration, strictly enforcing a 4x4 matrix. This ensures consistency for HUD-specific rendering logic.

package/docs/reference/modules/GameMenu.adoc

@@ -0,0 +1,39 @@
+= GameMenu Module Reference
+:description: Represents the orchestrator entry state, allowing navigation between games.
+:keywords: menu, selection, entry point, root
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+
+The `GameMenu` is a concrete implementation of `xref:Game.adoc[Game]`. It serves as the primary gateway or entry screen for players, allowing them to browse and select which logic/game module to initialize from the central `GameRepository`.
+
+== Initialization & Configuration
+
+=== `setupGame(): void`
+
+Adjusts formatting and presentation logic specific to the menu's state (e.g., Font setup). Unbinds standard game inputs and hooks into UP/DOWN/ENTER for menu navigation.
+
+=== `gameId` Property
+
+Set to `game-menu` upon instantiation. This ensures the menu state is intentionally ignored by the `xref:GameSession.adoc[GameSession]` mechanism, averting logic conflicts that would try to parse the "menu" as a playable state.
+
+== Rendering
+
+=== `drawTitleScreen(): void`
+
+Renders the interactive menu. Reads from `GameRepository` and formats the available games interactively according to the internal active pointer value (`_gameSelectionPointer`). Updates dynamically when UP/DOWN are pressed.
+
+=== `drawGameOverScreen(): void`
+
+The `GameMenu` does not have a Game Over logic screen hook. Attempting to enter the `GAME_OVER` state will have no visual effect.
+
+== Event Handling
+
+=== Menu Controls
+
+- **UP**: Decrements the selection pointer.
+- **DOWN**: Increments the selection pointer.
+- **START_PAUSE** (Enter): Instantiates the game at the current selection pointer and invokes `this.switchGame()` to seamlessly hand over control.
+- **EXIT**: In the context of the menu, it does not apply switching behaviors.

package/docs/reference/modules/GameRenderer.adoc

@@ -0,0 +1,79 @@
+= GameRenderer Module Reference
+:description: Orchestrates multiple specialized renderers to draw the game grid, background, and HUD.
+:keywords: rendering, orchestration, graphics, canvas, layers
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameRenderer` module is the visual engine of the application. It orchestrates multiple specialized renderers to draw the game grid, background, borders, and HUD elements on the HTML5 canvas.
+
+== API Reference
+
+=== `rendererMetrics: RendererMetrics`
+
+Read-only property containing the calculated dimensions and origins for all UI components.
+
+**Returns**
+
+`xref:../types/RendererMetrics.adoc[RendererMetrics]` - An object containing geometric data for `display`, `hud`, and individual `cells`.
+
+**Behavior**
+
+Calculates metrics once during initialization based on the current canvas size and configuration. These values are used by all other modules (like `xref:GameText.adoc[GameText]`) to ensure pixel-perfect alignment.
+
+
+'''
+
+=== `addRenderer(renderer: Renderer): void`
+
+Registers a new rendering layer.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`renderer` |`xref:../interfaces/modules/Renderer.adoc[Renderer]` |An implementation of the `xref:../interfaces/modules/Renderer.adoc[Renderer]` interface (e.g., `xref:DisplayRenderer.adoc[DisplayRenderer]`).
+|===
+
+**Behavior**
+
+Adds the renderer to an internal stack. Layers are executed in the order they are added.
+
+
+'''
+
+=== `render(grid: Cell[][], modules: GameModules): void`
+
+The main drawing execution call.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`grid` |`xref:../types/Cell.adoc[Cell][][]` |The current 2D matrix of cells to visualize.
+|`modules` |`xref:../interfaces/GameModules.adoc[GameModules]` |Reference to all available modules for context-aware rendering.
+|===
+
+**Behavior**
+
+Called by the engine's main loop. It iterates through all registered renderers and executes their specific `render` logic.
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.
+
+**Returns**
+
+`Record<string, string | number | boolean>` - Object containing `display_width`, `display_height`, `hud_width`, `hud_height`, and `cell_size`.

package/docs/reference/modules/GameScore.adoc

@@ -0,0 +1,138 @@
+= GameScore Module Reference
+:description: Tracks session player performance, including score, levels, and point multipliers.
+:keywords: score, tracking, levels, multipliers, metrics
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameScore` module tracks player performance during a session. It manages the current score, game levels, multipliers, and acts as the authority for the game's `highScore`, persisting it directly to `LocalStorage`. It also fully supports Session serialization out of the box.
+
+== API Reference
+
+=== `score: number`
+
+Read-only property returning the current session's points.
+
+
+'''
+
+=== `level: number`
+
+Read-only property returning the current difficulty level.
+
+
+'''
+
+=== `multiplier: number`
+
+Read and Write property for the current points multiplier.
+
+
+'''
+
+=== `highScore: number`
+
+Read and Write property for the highest overall score achieved.
+
+**Behavior**
+
+When set, it automatically persists the value directly to `LocalStorage` under the `highScore` key. It does not use `GameState` for this persistence.
+
+
+'''
+
+=== `increaseScore(amount: number): void`
+
+Adds points to the current session.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |Base points to add.
+|===
+
+**Behavior**
+
+Increases the score by `amount * multiplier`. Automatically compares the new score against the internal `highScore` property and updates it if a new record is reached (which in turn persists the new record to `LocalStorage`).
+
+
+'''
+
+=== `resetScore(): void`
+
+Resets the session score to zero.
+
+
+'''
+
+=== `increaseLevel(amount: number): void`
+
+Increases the game difficulty level.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |Number of levels to add.
+|===
+
+
+'''
+
+=== `resetLevel(): void`
+
+Resets the level counter to 1.
+
+
+'''
+
+=== `getFormattedScore(digits: number): string`
+
+Returns the score as a padded string suitable for HUD display.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`digits` |`number` |Total length of the string (e.g., 6 for "000150").
+|===
+
+**Returns**
+
+`string` - The zero-padded score string.
+
+
+'''
+
+=== `serialize(): string`
+
+**Behavior**
+
+Implements `xref:../interfaces/Serializable.adoc[Serializable]`. Packs the current `score`, `level`, `max_level`, `multiplier`, and `highScore` into a JSON string to be managed by the active game session.
+
+
+'''
+
+=== `deserialize(data: string): void`
+
+**Behavior**
+
+Implements `xref:../interfaces/Serializable.adoc[Serializable]`. Restores all progress from a saved session string.
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.

package/docs/reference/modules/GameSession.adoc

@@ -0,0 +1,43 @@
+= GameSession Module Reference
+:description: Core implementation of the session interface, orchestrating the state synchronization for game persistence.
+:keywords: session, GameSession, state sync, persistence
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+
+The `GameSession` module implements the `xref:../interfaces/modules/Session.adoc[Session]` interface. It acts as the default engine implementation for persistence lifecycle hooks.
+
+== Session Management
+
+=== `saveSession(): void`
+
+Creates or updates the session. Early returns if the `GameID` belongs to the main menu (`game-menu`) or if the `SessionModal` (if existing) has not been confirmed/rejected yet.
+
+=== `clearSession(): void`
+
+Removes the saved instances from `localStorage`.
+
+=== `syncState(state: State): void`
+
+Subscribes to `xref:GameState.adoc[GameState]` interactions.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`state` |`xref:../interfaces/modules/State.adoc[State]` |The game state orchestrator.
+|===
+
+**Behavior**
+
+Reacts to:
+- `PLAYING`: If a session for the current `gameId` exists, is NOT the game menu, and the modal hasn't been closed, it invokes the modal via `_showSessionModal`. If accepted, calls deserialize on all registered targets. If canceled or if no previous session exists, proceeds normally. The modal state is tracked to prevent re-triggering during the same power cycle.
+- `ON` (when false): Resets the modal state tracking closure, allowing the session modal to appear again after the device is powered back on.
+- `GAME_OVER`: Clears active session entirely.
+
+== Internals
+
+The system scopes data internally via the `${gameId}::${serialId}` key pattern within the `localStorage`. Under the hood, the engine identifies instances that implements the `xref:../interfaces/Serializable.adoc[Serializable]` capability and registers them here implicitly during the bootstrap.

package/docs/reference/modules/GameSound.adoc

@@ -0,0 +1,111 @@
+= GameSound Module Reference
+:description: Manages audio playback using the Web Audio API for low-latency sound effects.
+:keywords: sound, audio, web-audio, effects, mute
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The `GameSound` module manages audio playback for the engine using the **Web Audio API**. It provides low-latency sound effects and automatic synchronization with the game's mute state.
+
+== API Reference
+
+=== `play(sound: Sound): Promise<void>`
+
+Plays a preloaded sound effect.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`sound` |`xref:../enums/Sound.adoc[Sound]` |The enum identifier of the sound to play.
+|===
+
+**Returns**
+
+`Promise<void>` - Resolves when the sound starts playing.
+
+**Behavior**
+
+Automatically resumes the `AudioContext` if it was suspended by the browser. Multiple overlapping instances of the same sound are supported (e.g., rapid-fire effects).
+
+**Example**
+
+[source,typescript]
+----
+this.modules.sound.play(Sound.ACTION_1);
+----
+
+
+'''
+
+=== `stop(sound: Sound): void`
+
+Stops all active instances of a specific sound.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`sound` |`xref:../enums/Sound.adoc[Sound]` |The enum identifier of the sound to stop.
+|===
+
+**Behavior**
+
+Iterates through all currently playing sources of the specified type and stops them immediately.
+
+
+'''
+
+=== `stopAll(): void`
+
+Stops every sound currently playing in the engine.
+
+
+'''
+
+=== `toggleMute(): void`
+
+Toggles the master mute status.
+
+**Behavior**
+
+Inverts the `muted` property in `xref:GameState.adoc[GameState]`. This change is automatically persisted to `LocalStorage` and reflected in the audio output.
+
+
+'''
+
+=== `syncState(state: State): void`
+
+Synchronizes audio settings with the global game state.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`state` |`xref:../interfaces/modules/State.adoc[State]` |The `xref:GameState.adoc[GameState]` instance to link with.
+|===
+
+**Behavior**
+
+Implements the `xref:../interfaces/StateSyncable.adoc[StateSyncable]` interface. Subscribes to changes in the `MUTED` property of the provided state and updates the master gain node accordingly.
+
+
+'''
+
+=== `getDebugData(): Record<string, string | number | boolean>`
+
+Returns metadata for the real-time debugger.
+
+**Returns**
+
+`Record<string, string | number | boolean>` - Object containing `muted`, `active_sources`, and `loaded_buffers`.