brick-engine-js 1.0.1

package/dist/config/configs.d.ts

@@ -0,0 +1,180 @@
+declare const _default: {
+    /** Colors used for styling the game interface. */
+    readonly colors: {
+        /** Primary background color for the game screen. */
+        readonly background: "rgb(172, 189, 173)";
+        /** Active Font/Cell color. */
+        readonly active: "rgb(19, 26, 18)";
+        /** Inactive Font/Cell color. */
+        readonly inactive: "rgba(161, 178, 160, 1)";
+        /** Main theme color for the game device body. */
+        readonly bodyMain: "rgb(0, 68, 187)";
+        /** Secondary theme color for the buttons on the device body. */
+        readonly bodyButton: "rgb(247, 222, 57)";
+    };
+    /** Screen layout configurations. */
+    readonly screenLayout: {
+        /** Main game grid dimensions. */
+        readonly grid: {
+            readonly columns: 11;
+            readonly rows: 18;
+        };
+        /** Head-Up Display (HUD) grid dimensions. */
+        readonly hudGrid: {
+            readonly columns: 4;
+            readonly rows: 4;
+        };
+        /** Logical display settings within the container. */
+        readonly display: {
+            readonly width: 0.65;
+            readonly height: 0.956;
+            readonly margin: 0.022;
+            readonly borderWeight: 0.0075;
+        };
+        /** Predefined font scale factors relative to container size. */
+        readonly fontSize: {
+            readonly extraSmall: 0.05;
+            readonly small: 0.065;
+            readonly medium: 0.1;
+            readonly large: 0.125;
+            readonly extraLarge: 0.15;
+        };
+        /** Sizing and spacing for individual grid cells. */
+        readonly cell: {
+            readonly margin: 0.1;
+            readonly padding: 0.3;
+            readonly strokeWeight: 0.075;
+        };
+    };
+    /** View layout configurations. */
+    readonly viewLayout: {
+        /** Aspect ratio multiplier for the device body height relative to width. */
+        readonly bodyHeightWidthMultiplier: 1.9;
+        /** Screen width threshold for switching to mobile layout (in pixels). */
+        readonly mobileBreakpoint: 600;
+        /** Responsive canvas scaling and aspect ratio settings. */
+        readonly canvas: {
+            readonly widthRatio: 0.7;
+            readonly aspectRatio: 1.114;
+        };
+        /** Delay before hiding the splash screen after initialization (in milliseconds). */
+        readonly splashHideDelayMs: 250;
+        /** Dimensions and ratios for the game interface. */
+        readonly dimensions: {
+            /** Border radius as a ratio of container width. */
+            readonly borderRadiusRatio: 0.05;
+            /** Border width as a ratio of container width. */
+            readonly borderWidthRatio: 0.006;
+            /** Button-specific scaling factors. */
+            readonly button: {
+                /** Small button size ratio. */
+                readonly smSizeRatio: 0.08;
+                /** Medium/Standard button size ratio. */
+                readonly mdSizeRatio: 0.18;
+                /** Large action button size ratio. */
+                readonly lgSizeRatio: 0.25;
+                /** Scaling factors specifically for mobile viewports. */
+                readonly mobile: {
+                    /** Mobile small button size ratio. */
+                    readonly smSizeRatio: 0.13;
+                    /** Mobile medium/standard button size ratio. */
+                    readonly mdSizeRatio: 0.26;
+                    /** Mobile large action button size ratio. */
+                    readonly lgSizeRatio: 0.35;
+                    /** Standard font ratio for mobile buttons. */
+                    readonly fontRatio: 0.05;
+                    /** Small font ratio for mobile buttons. */
+                    readonly smFontRatio: 0.04;
+                    /** Large font ratio for mobile buttons. */
+                    readonly lgFontRatio: 0.055;
+                    /** Spacing ratio between mobile buttons. */
+                    readonly spacingRatio: 0.018;
+                };
+                /** Button border width as a ratio of container width. */
+                readonly borderRatio: 0.0045;
+                /** Duration for button press animations. */
+                readonly animationDuration: "0.15s";
+            };
+        };
+        /** Standard shadow dispersion size for UI depth. */
+        readonly shadowDispersion: "3px";
+    };
+    /** Input query parameters. */
+    readonly inputQueryParams: {
+        /** Key for customizing the device body main color. */
+        readonly mainColor: "body-color";
+        /** Key for customizing the device body button color. */
+        readonly buttonColor: "button-color";
+        /** Key for detecting if the game is running on a mobile app wrapper. */
+        readonly runningOnApp: "mobile";
+    };
+    /** Selectors for DOM elements. */
+    readonly selectors: {
+        /** Root container where the p5 instance is attached. */
+        readonly parent: "#brick-game";
+        /** Splash screen shown during initial load. */
+        readonly splash: "#splash";
+        /** Modal IDs used for session continuation. */
+        readonly modalIds: {
+            /** Modal shown when continuing a previous session. */
+            readonly sessionModal: "#session-modal";
+            /** Confirmation button in the session modal. */
+            readonly sessionContinueYes: "#session-modal-yes";
+            /** Cancellation button in the session modal. */
+            readonly sessionContinueNo: "#session-modal-no";
+        };
+        /** Explicit IDs assigned to dynamically created DOM elements. */
+        readonly viewElementIds: {
+            readonly canvas: "brick-game-canvas";
+            readonly container: "container";
+            readonly frame: "frame";
+            readonly buttonContainer: "button-container";
+            readonly smallButtonContainer: "small-button-container";
+            readonly innerButtonContainer: "inner-button-container";
+            readonly mediumButtonContainer: "medium-button-container";
+            readonly directionVerticalContainer: "direction-vertical-container";
+            readonly directionHorizontalContainer: "direction-horizontal-container";
+            readonly largeButtonContainer: "large-button-container";
+        };
+    };
+    /** Storage keys for persisting data in LocalStorage. */
+    readonly storageKeys: {
+        /** Key for audio muting preference. */
+        readonly muted: "STATE.MUTED";
+        /** Key for color mode preference. */
+        readonly colorEnabled: "STATE.COLOR_ENABLED";
+        /** Key for the current game grid state. */
+        readonly grid: "GAME.GRID";
+        /** Key for the current HUD grid state. */
+        readonly hudGrid: "GAME.HUD_GRID";
+        /** Key for the game speed/tick interval. */
+        readonly tickInterval: "GAME.TICK_INTERVAL";
+        /** Key for the user's high score. */
+        readonly score: "GAME.SCORE";
+    };
+    /** Button hold settings. */
+    readonly buttonHold: {
+        /** Initial delay before a held button starts repeating (in milliseconds). */
+        readonly holdDelayMs: 250;
+        /** Interval between repeated actions while a button is held (in milliseconds). */
+        readonly holdIntervalMs: 50;
+    };
+    /** Game settings. */
+    readonly game: {
+        /** Interval between game ticks (in milliseconds). */
+        readonly tickInterval: number;
+        /** Minimum interval between game ticks (in milliseconds). */
+        readonly minTickInterval: number;
+        /** Performance Monitor settings. */
+        readonly debugger: {
+            /** Number of milliseconds to count before updating the performance. */
+            readonly msInterval: 100;
+            /** Enable performance overlay. */
+            readonly enabled: true;
+        };
+        readonly sound: {
+            readonly volume: 0.025;
+        };
+    };
+};
+export default _default;

package/dist/config/configs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/env.d.ts

@@ -0,0 +1,2 @@
+export declare function isClientMode(): boolean;
+export declare function isServerMode(): boolean;

package/dist/config/env.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/Game.d.ts

@@ -0,0 +1,107 @@
+import p5 from 'p5';
+import type GameView from '../view/GameView';
+import { Initializable } from './types/Interfaces';
+import { GameModules } from './types/Types';
+/**
+ * Base abstract class for the game.
+ *
+ * It manages the game loop, initialization of core modules, and integration with p5.js.
+ * All game logic should be implemented in subclasses by overriding `processTick` and `processFrame`.
+ */
+export default abstract class Game implements Initializable {
+    protected _p: p5;
+    protected _view: GameView;
+    private _modules;
+    private _initialStateSnapshot;
+    private _gameId;
+    private _switchHandler;
+    /**
+     * Gets the game ID
+     */
+    get gameId(): string;
+    /**
+     * Sets the game ID
+     */
+    set gameId(id: string);
+    /**
+     * Registers the callback to be used when a game requests to switch to another game.
+     * This is typically called by the engine's main loop (index.ts).
+     * @param handler The callback function.
+     */
+    setSwitchHandler(handler: (newGame: Game) => void): void;
+    /**
+     * Propagates the switch handler to the new game.
+     * @param game Game instance that has the switch handler.
+     */
+    propagateSwitchHandler(game: Game): void;
+    /**
+     * Creates an instance of the Game.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {GameView} view - The view strategy associated with this game.
+     */
+    constructor(p: p5, view: GameView);
+    /**
+     * Gets the game view.
+     *
+     * @returns {GameView} The game view instance.
+     */
+    get view(): GameView;
+    /**
+     * Switches execution to a new game instance.
+     * Use this instead of global window methods.
+     *
+     * @param {Game} newGame - The new game instance to load.
+     */
+    switchGame(newGame: Game): void;
+    /**
+     * Gets the game modules.
+     *
+     * @returns {GameModules} The collection of initialized game modules.
+     */
+    get modules(): GameModules;
+    /**
+     * Sets up the game, initializing all modules and viewing components.
+     * Called automatically by the engine key sequence.
+     */
+    setup(): void;
+    /**
+     * Main draw loop, called by p5.js.
+     * Handles time updates, logic ticks, and rendering.
+     */
+    draw(): void;
+    /**
+     * Destroys the game instance, cleaning up all event listeners and stopping the loop.
+     * Call this before switching to another game or when the game is no longer needed.
+     */
+    destroy(): void;
+    get p(): p5;
+    /**
+     * Abstract method for processing game logic.
+     * Called every tick, but ONLY when the game is in the 'playing' state.
+     *
+     * @param {number} deltaTime - Time elapsed since last tick.
+     */
+    abstract update(deltaTime: number): void;
+    /**
+     * Abstract method for processing visual frames.
+     * Called every frame (depending on frameInterval).
+     */
+    abstract render(): void;
+    /**
+     * Abstract method for setting up the game specific logic.
+     * Called after the game modules are initialized.
+     */
+    abstract setupGame(): void;
+    /**
+     * Abstract method for drawing the Title Screen (Welcome).
+     * Called when the game is ON but not yet STARTED.
+     */
+    abstract drawTitleScreen(): void;
+    /**
+     * Abstract method for drawing the Game Over Screen.
+     * Called when the game is in GAME OVER state.
+     */
+    abstract drawGameOverScreen(): void;
+    private _subscribeSystemControls;
+}

package/dist/core/Game.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/InitialStateSnapshot.d.ts

@@ -0,0 +1,19 @@
+export default class InitialStateSnapshot {
+    private _initialState;
+    private _baseProperties;
+    /**
+     * Captures the base properties of the instance before any custom client properties are added.
+     * @param instance The object instance to extract keys from.
+     */
+    captureBaseProperties(instance: object): void;
+    /**
+     * Stores the initial state of custom client properties.
+     * @param instance The object instance containing custom properties.
+     */
+    captureInitialState(instance: object): void;
+    /**
+     * Restores the captured custom properties back to the instance.
+     * @param instance The object instance to restore properties onto.
+     */
+    restoreInitialState(instance: object): void;
+}

package/dist/core/InitialStateSnapshot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/CellHelper.d.ts

@@ -0,0 +1,13 @@
+import { Cell, Coordinate } from '../types/Types';
+/**
+ * Utility class for creating and managing grid cells.
+ */
+export default class CellHelper {
+    /**
+     * Creates a new empty cell at the specified coordinate.
+     *
+     * @param {Coordinate} coordinate - The location of the new cell.
+     * @returns {Cell} A new cell object initialized with value 0 and default color.
+     */
+    static emptyCell(coordinate: Coordinate): Cell;
+}

package/dist/core/helpers/CellHelper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/ControlInputHandlerHelper.d.ts

@@ -0,0 +1,32 @@
+import { ControlKey } from '../types/Types';
+import { Control } from '../types/modules';
+/**
+ * Helper class that standardizes input handling logic.
+ * It manages the distinction between single 'press' events and continuous 'hold' events
+ * for both keyboard and UI button inputs.
+ */
+export default class ControlInputHandlerHelper {
+    private _control;
+    private _activeKeys;
+    /**
+     * Creates an instance of the input handler.
+     *
+     * @param {Control} control - The control module instance to notify.
+     */
+    constructor(control: Control);
+    /**
+     * Processes a key down or button press action.
+     * Triggers an immediate {@link ControlEventType.PRESSED} event, and schedules
+     * a {@link ControlEventType.HELD} loop if the key remains active.
+     *
+     * @param {ControlKey} key - The identity of the control key being pressed.
+     */
+    handlePress(key: ControlKey): void;
+    /**
+     * Processes a key up or button release action.
+     * Cancels any pending hold timers and cleans up the active key state.
+     *
+     * @param {ControlKey} key - The identity of the control key being released.
+     */
+    handleRelease(key: ControlKey): void;
+}

package/dist/core/helpers/ControlInputHandlerHelper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/CoordinateHelper.d.ts

@@ -0,0 +1,54 @@
+import p5 from 'p5';
+import { Coordinate } from '../types/Types';
+/**
+ * Static utility class for coordinate transformations.
+ * Handles conversions between relative (0-1) coordinates and absolute pixel positions
+ * for both the main display and the HUD.
+ */
+export default class CoordinateHelper {
+    /**
+     * Converts a simplified coordinate object to relative screen dimensions.
+     *
+     * @param {p5} p - The P5 instance.
+     * @param {Coordinate} coordinate - The normal coordinate.
+     * @returns {Coordinate} A new coordinate scaled to the canvas width/height.
+     */
+    static getRelativeCoordinate(p: p5, coordinate: Coordinate): Coordinate;
+    /**
+     * Calculates the absolute X pixel position for an element on the Main Display.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {number} x - The relative or normalized X position.
+     * @param {number} displayWidth - The calculated width of the display area.
+     * @returns {number} The absolute X pixel coordinate.
+     */
+    static getDisplayPosX(p: p5, x: number, displayWidth: number): number;
+    /**
+     * Calculates the absolute Y pixel position for an element on the Main Display.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {number} y - The relative or normalized Y position.
+     * @param {number} displayHeight - The calculated height of the display area.
+     * @returns {number} The absolute Y pixel coordinate.
+     */
+    static getDisplayPosY(p: p5, y: number, displayHeight: number): number;
+    /**
+     * Calculates the absolute X pixel position for an element on the HUD.
+     * Use this to position elements in the sidebar.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {number} x - The relative or normalized X position within the HUD.
+     * @param {number} displayWidth - The width of the main display (used for offset calculation).
+     * @returns {number} The absolute X pixel coordinate.
+     */
+    static getHudPosX(p: p5, x: number, displayWidth: number): number;
+    /**
+     * Calculates the absolute Y pixel position for an element on the HUD.
+     *
+     * @param {p5} p - The p5 instance.
+     * @param {number} y - The relative or normalized Y position within the HUD.
+     * @param {number} displayHeight - The height of the main display (used for scaling).
+     * @returns {number} The absolute Y pixel coordinate.
+     */
+    static getHudPosY(p: p5, y: number, displayHeight: number): number;
+}

package/dist/core/helpers/CoordinateHelper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/InterfaceIdentifierHelper.d.ts

@@ -0,0 +1,7 @@
+import { Debuggable, Initializable, StateSyncable, Serializable } from '../types/Interfaces';
+export default class InterfaceIdentifierHelper {
+    static isSerializable(module: object): module is Serializable;
+    static isInitializable(module: object): module is Initializable;
+    static isStateSyncable(module: object): module is StateSyncable;
+    static isDebuggable(module: object): module is Debuggable;
+}

package/dist/core/helpers/InterfaceIdentifierHelper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/RelativeValuesHelper.d.ts

@@ -0,0 +1,23 @@
+import p5 from 'p5';
+/**
+ * Static utility for calculating pixel values relative to the canvas size.
+ * Allows for responsive design by defining sizes as percentages (0.0 - 1.0).
+ */
+export default class RelativeValuesHelper {
+    /**
+     * Calculates a pixel width based on a percentage of the canvas width.
+     *
+     * @param {p5} p - The P5 instance.
+     * @param {number} size - The percentage (0.0 to 1.0).
+     * @returns {number} The absolute width in pixels.
+     */
+    static getRelativeWidth(p: p5, size: number): number;
+    /**
+     * Calculates a pixel height based on a percentage of the canvas height.
+     *
+     * @param {p5} p - The P5 instance.
+     * @param {number} size - The percentage (0.0 to 1.0).
+     * @returns {number} The absolute height in pixels.
+     */
+    static getRelativeHeight(p: p5, size: number): number;
+}

package/dist/core/helpers/RelativeValuesHelper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/control/GameControl.d.ts

@@ -0,0 +1,62 @@
+import { ControlKey } from '../../types/enums';
+import { Control } from '../../types/modules';
+import { Debuggable } from '../../types/Interfaces';
+import { ControlCallback, ControlEventType, GameModules } from '../../types/Types';
+/**
+ * Manages game control inputs and event dispatching.
+ * Acts as the central hub for handling user input and notifying subscribers.
+ */
+export default class GameControl implements Control, Debuggable {
+    private _modules;
+    private _keyBinding;
+    private _subscribers;
+    /**
+     * Initializes the control system.
+     * Sets up key bindings and prepares the input handler.
+     */
+    setup(): void;
+    /**
+     * Unbinds all control event listeners.
+     */
+    unbindControls(): void;
+    /**
+     * Binds all control event listeners.
+     */
+    bindControls(): void;
+    /**
+     * Injects the game modules for context-aware events.
+     *
+     * @param {GameModules} modules - The collected game modules.
+     */
+    setModules(modules: GameModules): void;
+    /**
+     * Subscribes a callback to a specific control event.
+     *
+     * @param {ControlKey} key - The key to listen for.
+     * @param {ControlEventType} type - The event type (pressed/held).
+     * @param {ControlCallback} callback - The function to execute.
+     */
+    subscribe(key: ControlKey, type: ControlEventType, callback: ControlCallback): void;
+    /**
+     * Unsubscribes a callback from a control event.
+     *
+     * @param {ControlKey} key - The key to stop listening for.
+     * @param {ControlEventType} type - The event type.
+     * @param {ControlCallback} callback - The function to remove.
+     */
+    unsubscribe(key: ControlKey, type: ControlEventType, callback: ControlCallback): void;
+    /**
+     * Notifies subscribers of a control event.
+     *
+     * @param {ControlKey} key - The key triggering the event.
+     * @param {ControlEventType} type - The type of event.
+     * @throws {Error} If modules have not been initialized.
+     */
+    notify(key: ControlKey, type: ControlEventType): void;
+    /**
+     * Retrieves debug information about the control system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}

package/dist/core/module/control/GameControl.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/module/control/GameControlKeyBinding.d.ts

@@ -0,0 +1,36 @@
+import { Control } from '../../types/modules';
+/**
+ * Handles the binding of physical keyboard events to logical control actions.
+ * Translates Browser `KeyboardEvent`s into engine `ControlKey`s.
+ */
+export default class GameControlKeyBinding {
+    private _inputHandler;
+    private _boundHandleKeyDown;
+    private _boundHandleKeyUp;
+    /**
+     * Creates an instance of GameControlKeyBinding.
+     *
+     * @param {Control} control - The parent control module.
+     */
+    constructor(control: Control);
+    /**
+     * Binds keyboard events to the global window object.
+     */
+    bindControls(): void;
+    /**
+     * Unbinds keyboard events from the global window object.
+     */
+    unbindControls(): void;
+    /**
+     * Internal handler for key down events.
+     *
+     * @param {KeyboardEvent} event - The browser keyboard event.
+     */
+    private _handleKeyDown;
+    /**
+     * Internal handler for key up events.
+     *
+     * @param {KeyboardEvent} event - The browser keyboard event.
+     */
+    private _handleKeyUp;
+}

package/dist/core/module/control/GameControlKeyBinding.test.d.ts

@@ -0,0 +1 @@
+export {};