brick-engine-js 1.0.1

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

@@ -0,0 +1,107 @@
+= Score Reference
+:description: Interface for tracking session performance, multipliers, and levels.
+:keywords: score, tracking, levels, metrics, multipliers
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Interface for tracking session performance, multipliers, and levels.
+
+== Properties
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`score` |`number` |The current total score for the session.
+|`multiplier` |`number` |The current points multiplier.
+|`level` |`number` |The current game difficulty level.
+|`maxLevel` |`number` |The maximum level achievable.
+|===
+
+== Methods
+
+=== `increaseScore(amount: number): void`
+
+Adds points to the total, automatically applying any active multipliers.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |The base points to add before multiplier.
+|===
+
+
+'''
+
+=== `resetScore(): void`
+
+Resets the session score to `0`.
+
+
+'''
+
+=== `getFormattedScore(digits?: number): string`
+
+Returns a string representation of the score padded with leading zeros (defaulting to 6 digits).
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`digits` |`number` |(Optional) The total length of the string. Defaults to 6.
+|===
+
+**Returns**
+
+`string` - The formatted score (e.g., "001500").
+
+
+'''
+
+=== `increaseLevel(amount: number): void`
+
+Increments the current game level up to `maxLevel`.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`amount` |`number` |Levels to increase by.
+|===
+
+
+'''
+
+=== `resetLevel(): void`
+
+Resets the game difficulty level to its initial value.
+
+
+'''
+
+=== `setState(state: xref:State.adoc[State]): void`
+
+Internal setup method to link the score module with high-score persistence logic.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`state` |`xref:State.adoc[State]` |The global state manager.
+|===
+
+== General Usage
+
+Implemented by `xref:../../modules/GameScore.adoc[GameScore]`. It handles the numeric progression of the game and formats the data for display on the HUD.

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

@@ -0,0 +1,66 @@
+= Session Interface Reference
+:description: Defines the contract for the module responsible for managing game sessions and restoring serializable data.
+:keywords: interface, session, storage, save, serialization
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+
+The `Session` interface defines the core contract for the game's session orchestration. It handles restoring persistent `xref:../Serializable.adoc[Serializable]` data (such as progressive scores or active level states) and presenting UI mechanisms to the user when playing an existing session.
+
+This module is a core part of the `xref:GameModules.adoc[GameModules]` composite.
+
+== Attributes / Properties / Values
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`gameId` |`string` |The unique identifier of the game, provided by `xref:../../modules/Game.adoc[Game.gameId]`, used to prefix the LocalStorage entries.
+|===
+
+== API Reference
+
+'''
+
+=== `register(serializable: Serializable): void`
+
+Appends a module or instance that implements `Serializable` to the session's watch list.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`serializable` |`xref:../Serializable.adoc[Serializable]` |The instance implementing serialization capability.
+|===
+
+'''
+
+=== `saveSession(): void`
+
+Persists the current state of all registered `xref:../Serializable.adoc[Serializable]` instances to `localStorage`.
+
+'''
+
+=== `clearSession(): void`
+
+Clears out the active session data from `localStorage`, functionally resetting the user's progress for the given `gameId`.
+
+'''
+
+=== `setShowModalFunction(showModal: (onConfirm: () => void, onCancel: () => void) => void): void`
+
+Registers the callback that triggers the session recovery UI element.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`showModal` |`Function` |The callback that is executed, receiving the internal `onConfirm` and `onCancel` closure functions as arguments.
+|===
+
+== General Usage
+
+The `Session` module subscribes to the `GameState` lifecycle. Upon detecting a transition to the `PLAYING` state, if previous active records exist in `localStorage`, it invokes the modal logic set via `setShowModalFunction`. The engine's `Game` orchestrates this by default.

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

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

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

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