brick-engine-js 1.0.1

package/docs/publishing.adoc

@@ -0,0 +1,58 @@
+= Publishing Your Game
+:description: Guide on how to bundle and publish your game to the Brick Engine library.
+:keywords: publish, cli, bundle, deployment
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+
+This guide explains how to use the **Brick Engine CLI** `publish` command to bundle your game and submit it to the central repository, making it available for everyone in the main engine menu.
+
+== Prerequisites
+
+Before you can publish your game, ensure you have:
+* **Completed Development**: Your game should be fully playable and tested locally (`npm start`).
+* **Author Details**: Ensure you know the author email you want associated with this publication.
+
+== The `publish` Command
+
+The `publish` command connects your local project to the central Brick Engine repository.
+
+Run the following command in the root of your project directory:
+
+[source,bash]
+----
+npx brick-engine-cli publish
+----
+
+=== What happens during `publish`?
+
+When you run the publish command, the CLI will automatically perform the following steps:
+
+1.  **Build**: It executes `npm run build:bundle` to generate a production-ready, optimized JavaScript bundle of your game in the `dist/` directory.
+2.  **Prompt for Details**: It will ask for the developer's email address. This is used to notify you about the status of your publication request.
+3.  **Upload**: The CLI securely uploads your generated `game.bundle.js` to Supabase Storage.
+4.  **Registration**: It creates a database entry linking your bundle URL with your game's metadata (extracted from `package.json`, including name and version).
+
+== The Review Process
+
+After a successful upload, your game is placed in a **Pending** status.
+
+1.  **Approval Required**: To ensure the quality and safety of the central library, all games must be manually reviewed before they appear in the public menu.
+2.  **Notification**: You will receive an email (at the address you provided during the prompt) once your game has been reviewed. This email will confirm if the game was approved and is now live, or if it was rejected with feedback.
+
+== Troubleshooting Publish Errors
+
+=== Duplicate Publication
+
+If you attempt to publish the exact same version of a game that is already published or pending, the CLI will reject the upload.
+
+**Solution**: If you made changes, increment the `version` field in your `package.json` before running the publish command again.
+
+=== Build Failures
+
+If the `npm run build:bundle` step fails, the publish process will abort.
+
+**Solution**: Check your terminal output for TypeScript or Webpack errors. Fix these issues and ensure that `npm run build:bundle` executes successfully on its own before trying to publish again.

package/docs/reference/enums/Color.adoc

@@ -0,0 +1,35 @@
+= Color Reference
+:description: Defines the available visual theme colors for grid cells and text.
+:keywords: color, theme, grid, retro, display
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Defines the available visual theme colors for grid cells and text.
+
+== Values
+
+[cols="1,2"]
+|===
+|Value |Description
+|`DEFAULT` |The background color of an empty cell.
+|`BLUE` |Standard blue brick color.
+|`CYAN` |Bright cyan brick color.
+|`GRAY` |Neutral gray color.
+|`GREEN` |Standard green brick color.
+|`PURPLE` |Vibrant purple brick color.
+|`RED` |Warning or obstacle red color.
+|`YELLOW` |Gold/Yellow brick color.
+|`INACTIVE` |Faded color for background/ghost elements.
+|===
+
+== General Usage
+
+Colors are used throughout the engine to theme the `xref:../modules/GameGrid.adoc[GameGrid]` and the `HUD`. Use these constants when calling methods like `grid.setCellColor(coord, Color.RED)`.

package/docs/reference/enums/ControlEventType.adoc

@@ -0,0 +1,28 @@
+= ControlEventType Reference
+:description: Enumerates the different ways an input can be triggered.
+:keywords: control, events, input, interaction
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Enumerates the different ways an input can be triggered.
+
+== Values
+
+[cols="1,2"]
+|===
+|Value |Description
+|`PRESSED` |Triggered exactly once when the key is first engaged.
+|`HELD` |Triggered repeatedly at a fixed interval while the key remains engaged.
+|===
+
+== General Usage
+
+Crucial for distinguishing between actions like "Rotate Once" (`xref:../enums/ControlEventType.adoc[PRESSED]`) and "Move Continuously" (`xref:../enums/ControlEventType.adoc[HELD]`). Used in subscription filters: `xref:../modules/GameControl.adoc[modules.control].subscribe(key, ControlEventType.HELD, callback)`.

package/docs/reference/enums/ControlKey.adoc

@@ -0,0 +1,34 @@
+= ControlKey Reference
+:description: Abstraction layer mapping hardware inputs to logical engine actions.
+:keywords: input, keys, mapping, control
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Abstraction layer mapping hardware inputs to logical engine actions.
+
+== Values
+
+[cols="1,2"]
+|===
+|Value |Description
+|`UP`, `DOWN`, `LEFT`, `RIGHT` |Directional navigation for players and menus.
+|`ACTION` |Primary interaction button (e.g., jump, rotate, shoot).
+|`START_PAUSE` |Toggles the gameplay state between `PLAYING` and `PAUSED`.
+|`POWER` |Main system toggle (ON/OFF).
+|`RESET` |Triggers a full game session reset.
+|`SOUND` |Mutes or unmutes the audio system.
+|`EXIT` |Exits the current game session back to the menu.
+|`COLOR` |Toggles visual rendering modes.
+|===
+
+== General Usage
+
+`ControlKey` is used when subscribing to input events via `xref:../modules/GameControl.adoc[GameControl].subscribe()` and when checking the `key` property of a `xref:../types/GameEvent.adoc[GameEvent]`.

package/docs/reference/enums/FontAlignment.adoc

@@ -0,0 +1,43 @@
+= Font Alignment Reference
+:description: Enums defining the text anchor points on the canvas.
+:keywords: font, alignment, text, display, layout
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Enums defining the text anchor points on the canvas.
+
+== `FontAlign`
+
+Horizontal alignment of the text block.
+
+[cols="1,3"]
+|===
+|Value |Description
+|`LEFT` |Text starts at the provided X coordinate.
+|`CENTER` |Text is centered relative to X.
+|`RIGHT` |Text ends at the provided X coordinate.
+|===
+
+== `FontVerticalAlign`
+
+Vertical alignment of the text block.
+
+[cols="1,3"]
+|===
+|Value |Description
+|`TOP` |Text top edge aligns with Y.
+|`CENTER` |Text is centered relative to Y.
+|`BOTTOM` |Text bottom edge aligns with Y.
+|===
+
+== General Usage
+
+Used when calling `xref:../modules/GameText.adoc[GameText].setTextAlign()`.

package/docs/reference/enums/FontSize.adoc

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

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

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

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

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

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

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

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

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

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