brick-engine-js 1.0.1

package/docs/reference/interfaces/RendererInitializable.adoc

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

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

@@ -0,0 +1,98 @@
+= 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]`).

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

@@ -0,0 +1,411 @@
+= Grid Reference
+:description: Interface defining the behaviors of a 2D grid of cells.
+:keywords: grid, cells, matrix, collision-detection
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Interface defining the behaviors of a 2D grid of cells.
+
+== Properties
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`width` |`number` |The number of columns in the grid.
+|`height` |`number` |The number of rows in the grid.
+|===
+
+== Methods
+
+=== `getGrid(): xref:../../types/Cell.adoc[Cell][][]`
+
+Returns the raw 2D array of `xref:../../types/Cell.adoc[Cell]` objects representing the grid state.
+
+**Returns**
+
+`xref:../../types/Cell.adoc[Cell][][]` - The matrix representing the grid state.
+
+
+'''
+
+=== `resetGrid(): void`
+
+Clears all cell values and resets colors to `xref:../../enums/Color.adoc[DEFAULT]`.
+
+
+'''
+
+=== `forEach(callback: (cell: xref:../../types/Cell.adoc[Cell]) => void): void`
+
+Iterates over every cell in the grid, executing the provided callback.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`callback` |`(cell: xref:../../types/Cell.adoc[Cell]) => void` |Function to execute for each cell.
+|===
+
+
+'''
+
+=== `isValidCoordinate(coordinate: xref:../../types/Coordinate.adoc[Coordinate]): boolean`
+
+Returns `true` if the given coordinate falls within the grid boundaries.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |The `{x, y}` point to validate.
+|===
+
+**Returns**
+
+`boolean` - `true` if valid, `false` otherwise.
+
+
+'''
+
+=== `getCell(coordinate: xref:../../types/Coordinate.adoc[Coordinate]): xref:../../types/Cell.adoc[Cell] | null`
+
+Retrieves the `xref:../../types/Cell.adoc[Cell]` object at the specified coordinate.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |The `{x, y}` position to query.
+|===
+
+**Returns**
+
+`xref:../../types/Cell.adoc[Cell] | null` - The cell object, or `null` if the coordinate is out of bounds.
+
+
+'''
+
+=== `setCellValue(coordinate: xref:../../types/Coordinate.adoc[Coordinate], value: number): void`
+
+Updates the numeric value of the cell at the given coordinate.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Target position.
+|`value` |`number` |New status value (0 for inactive, >0 for active).
+|===
+
+
+'''
+
+=== `setCellColor(coordinate: xref:../../types/Coordinate.adoc[Coordinate], color: xref:../../enums/Color.adoc[Color]): void`
+
+Updates the visual color of the cell at the given coordinate.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Target position.
+|`color` |`xref:../../enums/Color.adoc[Color]` |Enum value representing the new color.
+|===
+
+
+'''
+
+=== `isCellActive(coordinate: xref:../../types/Coordinate.adoc[Coordinate]): boolean`
+
+Returns `true` if the cell's value is greater than `0`.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Point to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if the cell value is greater than 0.
+
+
+'''
+
+=== `isCellInactive(coordinate: xref:../../types/Coordinate.adoc[Coordinate]): boolean`
+
+Returns `true` if the cell's value is `0`.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinate` |`xref:../../types/Coordinate.adoc[Coordinate]` |Point to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if the cell value is exactly 0.
+
+
+'''
+
+=== `isRowFull(y: number): boolean`
+
+Returns `true` if every cell in the specified row `y` is active.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`y` |`number` |Row index to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if full.
+
+
+'''
+
+=== `isRowEmpty(y: number): boolean`
+
+Returns `true` if every cell in the specified row `y` is inactive.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`y` |`number` |Row index to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if empty.
+
+
+'''
+
+=== `clearRow(y: number): void`
+
+Resets all cells in row `y` to their inactive state.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`y` |`number` |Row index to clear.
+|===
+
+
+'''
+
+=== `shiftRowsDown(fromY: number): void`
+
+Moves all rows above (and including) `fromY` down by one position.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`fromY` |`number` |The row index to start shifting from.
+|===
+
+
+'''
+
+=== `shiftRowsUp(fromY: number): void`
+
+Moves all rows below (and including) `fromY` up by one position.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`fromY` |`number` |The row index to start shifting from.
+|===
+
+
+'''
+
+=== `clearFullRows(): number`
+
+Detects, clears, and shifts rows for all full rows in the grid.
+
+**Returns**
+
+`number` - The total count of cleared rows.
+
+
+'''
+
+=== `isColumnFull(x: number): boolean`
+
+Returns `true` if every cell in column `x` is active.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`x` |`number` |Column index to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if full.
+
+
+'''
+
+=== `isColumnEmpty(x: number): boolean`
+
+Returns `true` if every cell in column `x` is inactive.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`x` |`number` |Column index to check.
+|===
+
+**Returns**
+
+`boolean` - `true` if empty.
+
+
+'''
+
+=== `clearColumn(x: number): void`
+
+Resets all cells in column `x` to their inactive state.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`x` |`number` |Column index to clear.
+|===
+
+
+'''
+
+=== `shiftColumnsRight(fromX: number): void`
+
+Moves all columns to the left of `fromX` one position to the right.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`fromX` |`number` |The column index to start shifting from.
+|===
+
+
+'''
+
+=== `shiftColumnsLeft(fromX: number): void`
+
+Moves all columns to the right of `fromX` one position to the left.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`fromX` |`number` |The column index to start shifting from.
+|===
+
+
+'''
+
+=== `clearFullColumns(): number`
+
+Detects and clears all full columns.
+
+**Returns**
+
+`number` - The total count of cleared columns.
+
+
+'''
+
+=== `isAreaOccupied(coordinates: xref:../../types/Coordinate.adoc[Coordinate][]): boolean`
+
+Returns `true` if any of the provided coordinates are already active in the grid. Used for collision detection.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinates` |`xref:../../types/Coordinate.adoc[Coordinate][]` |Array of `{x, y}` points representing a shape or piece.
+|===
+
+**Returns**
+
+`boolean` - `true` if occupied.
+
+
+'''
+
+=== `fillArea(start: xref:../../types/Coordinate.adoc[Coordinate], end: xref:../../types/Coordinate.adoc[Coordinate], value: number, color: xref:../../enums/Color.adoc[Color]): void`
+
+Batch updates a rectangular area defined by `start` and `end` with the given value and color.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`start` |`xref:../../types/Coordinate.adoc[Coordinate]` |Top-left corner of the rectangle.
+|`end` |`xref:../../types/Coordinate.adoc[Coordinate]` |Bottom-right corner of the rectangle.
+|`value` |`number` |Value to apply to all cells in the area.
+|`color` |`xref:../../enums/Color.adoc[Color]` |Color to apply to all cells in the area.
+|===
+
+
+'''
+
+=== `stampPiece(coordinates: xref:../../types/Coordinate.adoc[Coordinate][], value: number, color: xref:../../enums/Color.adoc[Color]): void`
+
+Applies the specified value and color to multiple discrete coordinates simultaneously.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`coordinates` |`xref:../../types/Coordinate.adoc[Coordinate][]` |Points to update.
+|`value` |`number` |New cell value.
+|`color` |`xref:../../enums/Color.adoc[Color]` |New cell color.
+|===
+
+
+== General Usage
+
+The `Grid` interface is implemented by both the main `xref:../../modules/GameGrid.adoc[GameGrid]` and the `xref:../../modules/GameHudGrid.adoc[GameHudGrid]`.

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

@@ -0,0 +1,34 @@
+= Renderer Reference
+:description: Defines the core drawing contract for engine visual layers.
+:keywords: rendering, drawing, graphics, canvas
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Defines the core drawing contract for engine visual layers.
+
+== Methods
+
+=== `render(grid: xref:../../types/Cell.adoc[Cell][][], modules: xref:../GameModules.adoc[GameModules]): void`
+
+Executes the drawing logic for a single frame.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`grid` |`xref:../../types/Cell.adoc[Cell][][]` |The current state of the game grid.
+|`modules` |`xref:../GameModules.adoc[GameModules]` |Registry of all game modules.
+|===
+
+== General Usage
+
+Implemented by `xref:../../modules/DisplayRenderer.adoc[DisplayRenderer]` and `xref:../../modules/HudRenderer.adoc[HudRenderer]`. The engine's composite renderer iterates through all registered `Renderer` implementations and calls their `render` method 60 times per second.

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

@@ -0,0 +1,57 @@
+= RendererComposite Reference
+:description: An advanced renderer that manages a collection of individual layers.
+:keywords: renderer, composite, layers, graphics, canvas
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+An advanced renderer that manages a collection of individual layers.
+
+== Properties
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`rendererMetrics` |xref:../../types/RendererMetrics.adoc[RendererMetrics] |The geometric source of truth.
+|===
+
+== Methods
+
+=== `addRenderer(renderer: xref:Renderer.adoc[Renderer]): void`
+
+Attaches a new visual layer.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`renderer` |`xref:Renderer.adoc[Renderer]` |The renderer instance to add (e.g., Grid, HUD).
+|===
+
+
+'''
+
+=== `render(grid: xref:../../types/Cell.adoc[Cell][][], modules: xref:../GameModules.adoc[GameModules]): void`
+
+Orchestrates the rendering call for all layers.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`grid` |`xref:../../types/Cell.adoc[Cell][][]` |The current state of the game grid.
+|`modules` |`xref:../GameModules.adoc[GameModules]` |Registry of all game modules.
+|===
+
+== General Usage
+
+This interface is the entry point for the visual system. It ensures that the background, the game grid, and the HUD are drawn in the correct order and with synchronized metrics.