brick-engine-js 1.0.9 → 1.0.11

package/docs/reference/enums/FontSize.adoc

@@ -1,31 +0,0 @@
-= FontSize Reference
-:description: Predefined logic scales for the retro pixelated typography.
-:keywords: font, size, typography, display
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Predefined logic scales for the retro pixelated typography.
-
-== Values
-
-[cols="1,3"]
-|===
-|Value |Level
-|`EXTRA_SMALL` |Metrics, fine print, or detailed debug data.
-|`SMALL` |Secondary labels.
-|`MEDIUM` |Standard size for interactive elements and messages.
-|`LARGE` |High-visibility status (e.g., "GET READY").
-|`EXTRA_LARGE` |Main titles and "GAME OVER" announcements.
-|===
-
-== General Usage
-
-Set the active font size via `xref:../modules/GameText.adoc[GameText].setTextSize(FontSize.LARGE)`. The engine automatically handles the scaling based on the display resolution.

package/docs/reference/enums/Sound.adoc

@@ -1,42 +0,0 @@
-= Sound Reference
-:description: Maps sound identifiers to their relative asset paths.
-:keywords: sound, audio, assets, game-events
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Maps sound identifiers to their relative asset paths.
-
-== Values
-
-[cols="1,2"]
-|===
-|Value |Asset Path
-|`SPAWN` |`./sounds/sound_01.wav`
-|`SCORE_1` |`./sounds/sound_15.wav`
-|`SCORE_2` |`./sounds/sound_03.wav`
-|`SCORE_3` |`./sounds/sound_02.wav`
-|`KEY_PRESS` |`./sounds/sound_14.wav`
-|`ACTION_1` |`./sounds/sound_05.wav`
-|`ACTION_2` |`./sounds/sound_13.wav`
-|`HIT_1` |`./sounds/sound_06.wav`
-|`HIT_2` |`./sounds/sound_08.wav`
-|`DODGE` |`./sounds/sound_07.wav`
-|`DROP` |`./sounds/sound_11.wav`
-|`EXPLOSION` |`./sounds/sound_09.wav`
-|`GAME_START` |`./sounds/sound_04.wav`
-|`SHOT` |`./sounds/sound_12.wav`
-|`START_THEME` |`./sounds/sound_10.wav`
-|===
-
-== General Usage
-
-Use these constants to trigger audio effects via the `xref:../modules/GameSound.adoc[GameSound]` module.
-Example: `modules.sound.play(Sound.EXPLOSION)`.

package/docs/reference/enums/StateProperty.adoc

@@ -1,33 +0,0 @@
-= StateProperty Reference
-:description: Enumerates all observable and persistent properties of the game system.
-:keywords: state, persistence, properties, observability
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Enumerates all observable and persistent properties of the game system.
-
-== Values
-
-[cols="1,3"]
-|===
-|Value |Description
-|`ON` |Boolean flag for engine power state.
-|`START` |Boolean flag for game session start.
-|`PLAYING` |Boolean flag for active gameplay logic.
-|`GAME_OVER` |Boolean flag for end-of-game state.
-|`COLOR_ENABLED` |Boolean flag for themed rendering.
-|`MUTED` |Boolean flag for audio suppression.
-|`HIGH_SCORE` |Numeric property for the persistent record.
-|===
-
-== General Usage
-
-Used identifying which property changed in the `xref:../modules/GameState.adoc[GameState].subscribe()` callback.

package/docs/reference/helpers/CellHelper.adoc

@@ -1,37 +0,0 @@
-= CellHelper Reference
-:description: Static factory methods for creating and initializing Cell objects consistently.
-:keywords: cell, factory, grid, helper
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-The `CellHelper` provides static factory methods for creating and initializing `Cell` objects consistently.
-
-== Methods
-
-=== `emptyCell(coordinate: xref:../types/Coordinate.adoc[Coordinate]): xref:../types/Cell.adoc[Cell]`
-
-Creates a new cell with default "OFF" state values.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |xref:../types/Coordinate.adoc[Coordinate] |The `{x, y}` position to assign to the new cell.
-|===
-
-**Returns**
-
-`Cell` - A cell object with `value: 0` and `xref:../enums/Color.adoc[Color].DEFAULT`.
-
-**Behavior**
-
-This is used primarily by `xref:../modules/GameGrid.adoc[GameGrid]` to populate the initial matrix during allocation or when resetting a row/column.

package/docs/reference/helpers/ControlInputHandlerHelper.adoc

@@ -1,57 +0,0 @@
-= ControlInputHandlerHelper Reference
-:description: Utilities for normalizing raw hardware keyboard events into abstract ControlKey actions.
-:keywords: input, handler, keyboard, normalization, helper
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-The `ControlInputHandlerHelper` manages the complexity of input timing, such as identifying the difference between a quick "press" and a sustained "hold".
-
-== Usage
-
-This helper is used by the `xref:../modules/GameControl.adoc[GameControl]` module to normalize raw hardware events (like `keydown` and `keyup`) into engine-specific events.
-
-== Methods
-
-=== `handlePress(key: xref:../enums/ControlKey.adoc[ControlKey]): void`
-
-Processes a new interaction with a specific key.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |xref:../enums/ControlKey.adoc[ControlKey] |The virtual key being interacted with.
-|===
-
-**Behavior**
-
-1.  Triggers the `xref:../enums/ControlEventType.adoc[PRESSED]` event immediately.
-2.  Starts a timer based on `configs.buttonHold.holdDelayMs`.
-3.  If the key is still active after the delay, it starts an interval that repeatedly triggers the `xref:../enums/ControlEventType.adoc[HELD]` event.
-
-'''
-
-=== `handleRelease(key: xref:../enums/ControlKey.adoc[ControlKey]): void`
-
-Stops tracking an active interaction.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |xref:../enums/ControlKey.adoc[ControlKey] |The key that was released.
-|===
-
-**Behavior**
-
-Clears all active timers (delay and interval) for the specified key to stop `xref:../enums/ControlEventType.adoc[HELD]` events from firing.

package/docs/reference/helpers/CoordinateHelper.adoc

@@ -1,118 +0,0 @@
-= CoordinateHelper Reference
-:description: Specialized math utilities for converting between Grid, Display, and Pixel coordinate systems.
-:keywords: coordinates, math, grid, display, conversion, helper
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-The `CoordinateHelper` is a static utility class that handles translations between different coordinate systems: the logical xref:../modules/GameGrid.adoc[Game Grid], the normalized Display area, and absolute pixel positions.
-
-== API Reference
-
-=== `getRelativeCoordinate(p: p5, coordinate: xref:../types/Coordinate.adoc[Coordinate]): xref:../types/Coordinate.adoc[Coordinate]`
-
-Converts a pixel-based coordinate into a normalized relative coordinate (0.0 to 1.0).
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`coordinate` |xref:../types/Coordinate.adoc[Coordinate] |The absolute pixel coordinate.
-|===
-
-**Returns**
-
-`xref:../types/Coordinate.adoc[Coordinate]` - The normalized `{x, y}` point.
-
-
-'''
-
-=== `getDisplayPosX(p: p5, x: number, displayWidth: number): number`
-
-Calculates the absolute X pixel position on the main game display.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`x` |`number` |Normalized horizontal position (0.0 to 1.0).
-|`displayWidth` |`number` |The total width of the display area.
-|===
-
-**Returns**
-
-`number` - The absolute horizontal pixel position.
-
-
-'''
-
-=== `getDisplayPosY(p: p5, y: number, displayHeight: number): number`
-
-Calculates the absolute Y pixel position on the main game display.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`y` |`number` |Normalized vertical position (0.0 to 1.0).
-|`displayHeight` |`number` |The total height of the display area.
-|===
-
-**Returns**
-
-`number` - The absolute vertical pixel position.
-
-
-'''
-
-=== `getHudPosX(p: p5, x: number, displayWidth: number): number`
-
-Calculates the absolute X pixel position within the HUD area.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`x` |`number` |Normalized horizontal position (0.0 to 1.0) relative to the HUD area.
-|`displayWidth` |`number` |The width of the main display (used to calculate the HUD offset).
-|===
-
-**Returns**
-
-`number` - The absolute horizontal pixel position within the HUD.
-
-
-'''
-
-=== `getHudPosY(p: p5, y: number, displayHeight: number): number`
-
-Calculates the absolute Y pixel position within the HUD area.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`y` |`number` |Normalized vertical position (0.0 to 1.0) relative to the HUD area.
-|`displayHeight` |`number` |The total height of the display area.
-|===
-
-**Returns**
-
-`number` - The absolute vertical pixel position within the HUD.

package/docs/reference/helpers/RelativeValuesHelper.adoc

@@ -1,53 +0,0 @@
-= RelativeValuesHelper Reference
-:description: Generic utilities for calculating relative sizes and positions within containers.
-:keywords: relative, sizing, positioning, layout, helper
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-The `RelativeValuesHelper` provides conversion utilities for scaling absolute sizes to the current canvas dimensions, enabling responsive layouts.
-
-== Methods
-
-=== `getRelativeWidth(p: p5, size: number): number`
-
-Calculates a pixel width based on a normalized percentage.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`size` |`number` |A float between 0.0 and 1.0 representing percentage of width.
-|===
-
-**Returns**
-
-`number` - The calculated absolute pixel width.
-
-'''
-
-=== `getRelativeHeight(p: p5, size: number): number`
-
-Calculates a pixel height based on a normalized percentage.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`p` |`p5` |The P5.js instance.
-|`size` |`number` |A float between 0.0 and 1.0 representing percentage of height.
-|===
-
-**Returns**
-
-`number` - The calculated absolute pixel height.

package/docs/reference/interfaces/Debuggable.adoc

@@ -1,29 +0,0 @@
-= Debuggable Reference
-:description: Contract for modules that provide transparency to the developer.
-:keywords: debug, interface, transparency, metrics
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Contract for modules that provide transparency to the developer.
-
-== Methods
-
-=== `getDebugData(): Record<string, string | number | boolean>`
-
-Returns a dictionary of internal metrics for real-time inspection.
-
-**Returns**
-
-`Record<string, string | number | boolean>` - Key-value pairs of debug information.
-
-== General Usage
-
-When implemented, the xref:../modules/Debugger.adoc[Debugger] module will automatically create a UI section for the component and refresh its data every logic tick.

package/docs/reference/interfaces/GameModules.adoc

@@ -1,35 +0,0 @@
-= GameModules Reference
-:description: The central hub providing component-to-component visibility.
-:keywords: architecture, dependency-injection, registry, modules
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-The central hub providing component-to-component visibility.
-
-== Properties
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`grid` |xref:modules/Grid.adoc[Grid] |Main game field manager.
-|`hudGrid` |xref:modules/Grid.adoc[Grid] |Secondary 4x4 grid for HUD elements.
-|`state` |xref:modules/State.adoc[State] |Single source of truth for game flags.
-|`control` |xref:modules/Control.adoc[Control] |Input handling service.
-|`text` |xref:modules/Text.adoc[Text] |Canvas typography service.
-|`time` |xref:modules/Time.adoc[Time] |Logical clock manager.
-|`sound` |xref:Sound.adoc[Sound] |Audio playback service.
-|`score` |xref:modules/Score.adoc[Score] |Session performance tracker.
-|`renderer` |xref:modules/RendererComposite.adoc[RendererComposite] |The visual orchestration layer.
-|===
-
-== General Usage
-
-This registry is passed to almost every lifecycle method (`update`, `render`, `ControlCallback`). It allows modules to interact without tight coupling. For example, the `xref:modules/Sound.adoc[Sound]` module uses it to play sounds via `modules.sound.play()`.

package/docs/reference/interfaces/Initializable.adoc

@@ -1,24 +0,0 @@
-= Initializable Reference
-:description: A fundamental contract for modules that require an assembly phase.
-:keywords: lifecycle, initialization, setup, bootstrap
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-A fundamental contract for modules that require an assembly phase.
-
-== Methods
-
-=== `setup(): void`
-Invoked once by the engine after all modules are constructed.
-
-== General Usage
-
-Modules implementing `Initializable` use the `setup()` phase to establish internal buffers, bind event listeners, or perform calculations that depend on final configuration values.

package/docs/reference/interfaces/RendererInitializable.adoc

@@ -1,33 +0,0 @@
-= RendererInitializable Reference
-:description: Extension of Initializable specifically for rendering components.
-:keywords: rendering, initialization, layout, metrics
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Extension of `xref:Initializable.adoc[Initializable]` specifically for rendering components.
-
-== Methods
-
-=== `setup(rendererMetrics: xref:../types/RendererMetrics.adoc[RendererMetrics]): void`
-
-Invoked with live geometric metrics for the current session.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`rendererMetrics` |`xref:../types/RendererMetrics.adoc[RendererMetrics]` |The calculated display dimensions and offsets.
-|===
-
-== General Usage
-
-Implemented by components like `xref:../modules/DisplayRenderer.adoc[DisplayRenderer]` to receive pre-calculated X/Y origins and cell sizes before the first frame is drawn.

package/docs/reference/interfaces/StateSyncable.adoc

@@ -1,41 +0,0 @@
-= StateSyncable Reference
-:description: Contract for modules that must react to global state changes.
-:keywords: state, reactivity, synchronization, events
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Contract for modules that must react to global state changes.
-
-== Properties
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`_state` |`State` |Internal reference to the state module.
-|===
-
-== Methods
-
-=== `syncState(state: xref:modules/State.adoc[State]): void`
-
-Links the module instance and allows it to subscribe to properties.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`state` |`xref:modules/State.adoc[State]` |The global state manager.
-|===
-
-== General Usage
-
-Implemented by `xref:../modules/GameSound.adoc[GameSound]` and `xref:../modules/GameScore.adoc[GameScore]`. During the start-up sequence, the engine calls `syncState()` on these modules to ensure they have the latest references to `muted` flags and `highScore` data.

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

@@ -1,98 +0,0 @@
-= Control Reference
-:description: Interface for input handling and event-driven control distribution.
-:keywords: control, input, subscription, events
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-
-Interface for input handling and event-driven control distribution.
-
-== Methods
-
-=== `notify(key: xref:../../enums/ControlKey.adoc[ControlKey], type: xref:../../enums/ControlEventType.adoc[ControlEventType]): void`
-
-Triggers an event manually. Usually called by hardware drivers (like Keyboard listeners).
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |`xref:../../enums/ControlKey.adoc[ControlKey]` |The control key to simulate.
-|`type` |`xref:../../enums/ControlEventType.adoc[ControlEventType]` |The type of event (press/release).
-|===
-
-
-'''
-
-=== `setModules(modules: xref:../GameModules.adoc[GameModules]): void`
-
-Provides the context registry required for `xref:../../types/GameEvent.adoc[GameEvent]` construction.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`modules` |`xref:../GameModules.adoc[GameModules]` |Registry of all game modules.
-|===
-
-
-'''
-
-=== `subscribe(key: xref:../../enums/ControlKey.adoc[ControlKey], type: xref:../../enums/ControlEventType.adoc[ControlEventType], callback: xref:../../types/ControlCallback.adoc[ControlCallback]): void`
-
-Registers a function to be executed when the specified input occurs.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |`xref:../../enums/ControlKey.adoc[ControlKey]` |The key to listen for.
-|`type` |`xref:../../enums/ControlEventType.adoc[ControlEventType]` |The event type (pressed/held/released).
-|`callback` |`xref:../../types/ControlCallback.adoc[ControlCallback]` |Function to execute when triggered.
-|===
-
-
-'''
-
-=== `unsubscribe(key: xref:../../enums/ControlKey.adoc[ControlKey], type: xref:../../enums/ControlEventType.adoc[ControlEventType], callback: xref:../../types/ControlCallback.adoc[ControlCallback]): void`
-
-Detaches a previously registered input listener.
-
-**Parameters**
-
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`key` |`xref:../../enums/ControlKey.adoc[ControlKey]` |The key to unsubscribe from.
-|`type` |`xref:../../enums/ControlEventType.adoc[ControlEventType]` |The event type.
-|`callback` |`xref:../../types/ControlCallback.adoc[ControlCallback]` |The specific function to remove.
-|===
-
-
-'''
-
-=== `unbindControls(): void`
-
-Temporarily disables all input listeners.
-
-
-'''
-
-=== `bindControls(): void`
-
-Re-enables input listeners.
-
-
-== General Usage
-
-Implemented by `xref:../../modules/GameControl.adoc[GameControl]`. Games use this to react to player movements (`xref:../../enums/ControlKey.adoc[LEFT]`, `xref:../../enums/ControlKey.adoc[RIGHT]`) or actions (`xref:../../enums/ControlKey.adoc[ACTION]`).