brick-engine-js 1.0.9 → 1.0.11

package/docs/reference/interfaces/modules/State.adoc

@@ -1,290 +0,0 @@
-= State Reference
-:description: Interface for managing global game lifecycle flags, persistence, and preferences.
-:keywords: state, lifecycle, persistence, preferences
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Interface for managing global game lifecycle flags, persistence, and preferences.
-
-== Methods
-
-=== `isOn(): boolean`
-
-Returns `true` if the engine is "powered on".
-
-**Returns**
-
-`boolean` - `true` if on.
-
-
-'''
-
-=== `isOff(): boolean`
-
-Returns `true` if the engine is "powered off".
-
-**Returns**
-
-`boolean` - `true` if off.
-
-
-'''
-
-=== `isStarted(): boolean`
-
-Returns `true` if a game session has been initialized.
-
-**Returns**
-
-`boolean` - `true` if started.
-
-
-'''
-
-=== `isPlaying(): boolean`
-
-Returns `true` if the game is active and logic ticks are flowing.
-
-**Returns**
-
-`boolean` - `true` if playing.
-
-
-'''
-
-=== `isPaused(): boolean`
-
-Returns `true` if the game is started but currently paused.
-
-**Returns**
-
-`boolean` - `true` if paused.
-
-
-'''
-
-=== `isGameOver(): boolean`
-
-Returns `true` if the current session has ended in defeat.
-
-**Returns**
-
-`boolean` - `true` if game over.
-
-
-'''
-
-=== `isColorEnabled(): boolean`
-
-Returns `true` if themed color rendering is active.
-
-**Returns**
-
-`boolean` - `true` if color is enabled.
-
-
-'''
-
-=== `setColorEnabled(value: boolean): void`
-
-Manually sets the color rendering preference.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`value` |`boolean` |`true` to enable colors, `false` for monochrome/grayscale.
-|===
-
-
-'''
-
-=== `isMuted(): boolean`
-
-Returns `true` if the audio system is suppressed.
-
-**Returns**
-
-`boolean` - `true` if muted.
-
-
-'''
-
-=== `setMuted(value: boolean): void`
-
-Manually sets the audio suppression preference.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`value` |`boolean` |`true` to mute, `false` to unmute.
-|===
-
-
-'''
-
-=== `getHighScore(): number`
-
-Retrieves the persistent high score for the current game.
-
-**Returns**
-
-`number` - The current high score.
-
-
-'''
-
-=== `setHighScore(value: number): void`
-
-Updates the persistent high score.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`value` |`number` |The new high score to save.
-|===
-
-
-'''
-
-=== `subscribe(property: xref:../../enums/StateProperty.adoc[StateProperty], callback: (value: boolean | number) => void): void`
-
-Registers a listener for changes to a specific state property.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`property` |`xref:../../enums/StateProperty.adoc[StateProperty]` |The property to watch.
-|`callback` |`(value: boolean \| number) => void` |Function called when the property changes.
-|===
-
-
-'''
-
-=== `unsubscribe(property: xref:../../enums/StateProperty.adoc[StateProperty], callback: (value: boolean | number) => void): void`
-
-Removes a previously registered property listener.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`property` |`xref:../../enums/StateProperty.adoc[StateProperty]` |The property being watched.
-|`callback` |`(value: boolean \| number) => void` |The function to remove.
-|===
-
-
-'''
-
-=== `turnOn(): void`
-
-Powers up the engine.
-
-
-'''
-
-=== `turnOff(): void`
-
-Powers down the engine and saves state.
-
-
-'''
-
-=== `startGame(): void`
-
-Transitions from the menu to an active game session.
-
-
-'''
-
-=== `exitGame(): void`
-
-Ends the current game session and returns to the menu.
-
-
-'''
-
-=== `pause(): void`
-
-Toggles the gameplay state to paused.
-
-
-'''
-
-=== `resume(): void`
-
-Toggles the gameplay state back to playing.
-
-
-'''
-
-=== `triggerGameOver(): void`
-
-Transitions to the game over screen.
-
-
-'''
-
-=== `resetGame(): void`
-
-Resets session-specific state (score, grids) while maintaining high score and preferences.
-
-
-'''
-
-=== `toggleColorEnabled(): void`
-
-Flips the current `colorEnabled` flag.
-
-
-'''
-
-=== `toggleMuted(): void`
-
-Flips the current `muted` flag.
-
-
-'''
-
-=== `setPersistenceKey(key: string): void`
-
-Sets the unique namespace used for `localStorage`.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |`string` |The unique key prefix.
-|===
-
-
-'''
-
-=== `getPersistenceKey(): string`
-
-Returns the active namespace prefix.
-
-**Returns**
-
-`string` - The persistence key.
-
-== General Usage
-
-Implemented by `xref:../../modules/GameState.adoc[GameState]`. It serves as the single source of truth for the engine's behavior tree.

package/docs/reference/interfaces/modules/Text.adoc

@@ -1,110 +0,0 @@
-= Text Reference
-:description: Interface for drawing pixelated, responsive typography.
-:keywords: text, typography, rendering, display, retro
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Interface for drawing pixelated, responsive typography.
-
-== Methods
-
-=== `setTextSize(fontSize: xref:../../enums/FontSize.adoc[FontSize]): void`
-
-Sets the scale of the subsequent text operations.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fontSize` |`xref:../../enums/FontSize.adoc[FontSize]` |Enum value for text size (SMALL, MEDIUM, LARGE).
-|===
-
-
-'''
-
-=== `setTextAlign(fontAlign: xref:../../enums/FontAlignment.adoc[FontAlignment], fontVerticalAlign: xref:../../enums/FontAlignment.adoc[FontAlignment]): void`
-
-Sets both horizontal and vertical anchor points.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fontAlign` |`xref:../../enums/FontAlignment.adoc[FontAlignment]` |Horizontal alignment (LEFT, CENTER, RIGHT).
-|`fontVerticalAlign` |`xref:../../enums/FontAlignment.adoc[FontAlignment]` |Vertical alignment (TOP, CENTER, BOTTOM).
-|===
-
-
-'''
-
-=== `textOnHud(text: string, coordinate: xref:../../types/Coordinate.adoc[Coordinate]): void`
-
-Renders a string within the HUD area at the specified normalized coordinate (0.0 to 1.0 relative to HUD bounds).
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`text` |`string` |The string content to display.
-|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Normalized position `{x, y}`.
-|===
-
-
-'''
-
-=== `textOnDisplay(text: string, coordinate: xref:../../types/Coordinate.adoc[Coordinate]): void`
-
-Renders a string within the main game area at the specified normalized coordinate (0.0 to 1.0 relative to display bounds).
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`text` |`string` |The string content to display.
-|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Normalized position `{x, y}`.
-|===
-
-
-'''
-
-=== `setRendererMetrics(rendererMetrics: xref:../../types/RendererMetrics.adoc[RendererMetrics]): void`
-
-Internal setup method to provide the pixel-to-grid mapping data.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`rendererMetrics` |`xref:../../types/RendererMetrics.adoc[RendererMetrics]` |The calculated display dimensions.
-|===
-
-
-'''
-
-=== `setActiveText(): void`
-
-Sets the text rendering style to "active" (high contrast).
-
-
-'''
-
-=== `setInactiveText(): void`
-
-Sets the text rendering style to "inactive" (low contrast, background effect).
-
-== General Usage
-
-Implemented by `xref:../../modules/GameText.adoc[GameText]`. Used to display scores, labels, and title screen messages across different engine layers.

package/docs/reference/interfaces/modules/Time.adoc

@@ -1,119 +0,0 @@
-= Time Reference
-:description: Interface for managing the game's logical clock and update frequency.
-:keywords: time, clock, tick, interval, game-loop
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Interface for managing the game's logical clock and update frequency.
-
-== Properties
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`tickInterval` |`number` |The duration in milliseconds between logic updates.
-|===
-
-== Methods
-
-=== `update(deltaTime: number): void`
-
-Adds elapsed time to the internal accumulator. Called every frame.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`deltaTime` |`number` |Time in milliseconds since last frame.
-|===
-
-
-'''
-
-=== `shouldTick(): boolean`
-
-Returns `true` if the accumulator has exceeded the `tickInterval`, indicating a logic update is due.
-
-**Returns**
-
-`boolean` - `true` if a tick should occur.
-
-
-'''
-
-=== `reset(): void`
-
-Clears the time accumulator. Useful during game restarts.
-
-
-'''
-
-=== `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).
-|===
-
-== General Usage
-
-Implemented by `xref:../../modules/GameTime.adoc[GameTime]`. This module ensures that game logic (like falling pieces) runs at a consistent speed regardless of the render frame rate.

package/docs/reference/modules/Debugger.adoc

@@ -1,71 +0,0 @@
-= 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

@@ -1,55 +0,0 @@
-= 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.
-
-