brick-engine-js 1.0.38 → 1.0.40

package/dist/types/core/module/time/GameTime.d.ts

@@ -2,18 +2,21 @@ import { Debuggable } from '../../types/Interfaces';
 import { Time } from '../../types/modules';
 import { Serializable } from '../../types/Interfaces';
 /**
- * Module responsible for managing the logical engine clock, hardware frame rates, and tick intervals.
+ * Orchestrates the engine's logical clock and performance metrics.
  *
- * It decouples the deterministic game logic "ticks" from the unpredictable visual frame rate
- * of the browser canvas. By separating `update` loops from visual rendering, it ensures
- * consistent gameplay speed calculations (like difficulty progression) regardless of the
- * host device's performance capabilities.
+ * Designed to decouple deterministic game logic "ticks" from the unpredictable
+ * visual frame rate of the browser. By maintaining an internal time accumulator,
+ * it ensures that gameplay events (like physics, timers, and difficulty scaling)
+ * execute at a consistent speed regardless of the host device's hardware
+ * performance or FPS fluctuations.
+ *
+ * Implements the {@link Time} interface to provide a standardized timing
+ * contract for all engine modules.
  */
 export default class GameTime implements Time, Debuggable, Serializable {
     protected _tickAccumulator: number;
     /** The tick interval at the start of the game session. Used for resets. */
     private _initialTickInterval;
-    private _minTickInterval;
     private _tickInterval;
     private _fps;
     private _tps;
@@ -22,26 +25,58 @@ export default class GameTime implements Time, Debuggable, Serializable {
     private _timeSinceLastTpsUpdate;
     private _totalElapsedTime;
     serialId: string;
+    /**
+     * Gets the total number of ticks since the game started.
+     *
+     * @returns {number} Total tick count.
+     */
+    get totalTicks(): number;
+    /**
+     * Gets the total elapsed time in milliseconds.
+     *
+     * @returns {number} Elapsed time in ms.
+     */
+    get elapsedTime(): number;
     /**
      * Initializes the time module's core state.
-     * Resets all internal timers and statistical accumulators securely.
      *
-     * @returns {void} Returns nothing.
+     * Resets all internal timers and statistical accumulators to their
+     * baseline values, ensuring a clean state for a new game session.
+     *
+     * @returns {void}
      */
     setup(): void;
     /**
-     * Updates the internal time accumulator and calculates physical FPS/TPS.
-     * Must be invoked strictly once per hardware visual frame.
+     * Updates the physical performance metrics.
      *
-     * @param {number} deltaTime - Time physically elapsed since the last rendering frame in milliseconds.
-     * @returns {void} Returns nothing.
+     * Calculates the current Frames Per Second (FPS) and updates the Ticks
+     * Per Second (TPS) statistics. This method should be called exactly
+     * once per visual frame in the main loop.
+     *
+     * @param {number} deltaTime - The physical time physically elapsed since the last rendering frame in milliseconds.
+     * @returns {void}
      */
     update(deltaTime: number): void;
     /**
-     * Checks if enough time has passed for a game tick.
-     * Consumes accumulated time if a tick occurs.
+     * Adds elapsed time to the simulation accumulator.
+     *
+     * This time is used to determine when the next logical tick should
+     * be processed. It allows the engine to "catch up" if the frame
+     * rate drops below the target tick rate.
+     *
+     * @param {number} deltaTime - Time in milliseconds to add to the logic simulation.
+     * @returns {void}
+     */
+    accumulate(deltaTime: number): void;
+    /**
+     * Evaluates if the engine should execute a logical simulation tick.
      *
-     * @returns {boolean} True if a tick should occur.
+     * Checks if the accumulated time exceeds the required tick interval.
+     * If so, it consumes all pending time in the accumulator and
+     * increments the logical counters.
+     *
+     * @internal Used specifically by the engine's core orchestration loop.
+     * @returns {boolean} `true` if at least one tick's worth of time was consumed.
      */
     shouldTick(): boolean;
     /**
@@ -51,30 +86,24 @@ export default class GameTime implements Time, Debuggable, Serializable {
      */
     reset(): void;
     /**
-     * Gets the current tick interval.
+     * Checks if enough logical time has passed based on a specific millisecond interval.
+     * Use for time-based triggers that need to be stable even if the frame rate varies.
      *
-     * @returns {number} The tick interval in milliseconds.
+     * @param {number} ms - The millisecond interval to check.
+     * @returns {boolean} True if the logical clock just crossed a multiple of the interval.
      */
-    get tickInterval(): number;
+    atInterval(ms: number): boolean;
     /**
-     * Sets the tick interval and resets timing.
+     * Executes a callback function every N milliseconds of logical game time.
      *
-     * @param {number} interval - The new tick interval in milliseconds.
-     */
-    set tickInterval(interval: number);
-    /**
-     * Increments the tick interval (slowing down the game).
+     * Provides a declarative functional approach to handling recurring game logic,
+     * such as spawning enemies or updating timers.
      *
-     * @param {number} amount - The amount to add to the interval.
+     * @param {number} ms - The millisecond interval between executions.
+     * @param {() => void} action - The callback function to execute if the interval is crossed.
+     * @returns {void}
      */
-    incrementTickInterval(amount: number): void;
-    /**
-     * Decrements the tick interval (speeding up the game).
-     * Enforces a minimum interval of 10ms.
-     *
-     * @param {number} amount - The amount to subtract from the interval.
-     */
-    decrementTickInterval(amount: number): void;
+    every(ms: number, action: () => void): void;
     /**
      * Retrieves debug information about the time system.
      *
@@ -83,34 +112,4 @@ export default class GameTime implements Time, Debuggable, Serializable {
     getDebugData(): Record<string, string | number | boolean>;
     serialize(): string;
     deserialize(data: string): void;
-    setTickInterval(interval: number): void;
-    setMinTickInterval(interval: number): void;
-    /**
-     * Gets the total number of ticks since the game started.
-     *
-     * @returns {number} Total tick count.
-     */
-    get totalTicks(): number;
-    /**
-     * Gets the total elapsed time in milliseconds.
-     *
-     * @returns {number} Elapsed time in ms.
-     */
-    get elapsedTime(): number;
-    /**
-     * Checks if the current total tick count is a multiple of the provided interval.
-     *
-     * @param {number} interval - The tick interval to check.
-     * @returns {boolean} True if the current tick is a multiple of the interval.
-     */
-    isTickEvery(interval: number): boolean;
-    /**
-     * Captures the current tick interval as the deterministic initial baseline state.
-     *
-     * This is useful for restoring the intended baseline game speed on session
-     * resets rather than reverting to the engine's hardcoded default.
-     *
-     * @returns {void} Returns nothing.
-     */
-    captureInitialState(): void;
 }

package/dist/types/core/types/enums.d.ts

@@ -116,3 +116,14 @@ export declare enum StateProperty {
     MUTED = "muted",
     TRACKPAD = "trackpadEnabled"
 }
+/**
+ * Enumerates all observable score and progression properties.
+ * These keys are used for score subscriptions.
+ */
+export declare enum ScoreProperty {
+    SCORE = "score",
+    LEVEL = "level",
+    MULTIPLIER = "multiplier",
+    MAX_LEVEL = "maxLevel",
+    HIGH_SCORE = "highScore"
+}

package/dist/types/core/types/modules.d.ts

@@ -1,5 +1,5 @@
 import p5 from 'p5';
-import { Color, ControlKey, FontAlign, FontSize, FontVerticalAlign, Sound, TextTheme } from './enums';
+import { Color, ControlKey, FontAlign, FontSize, FontVerticalAlign, ScoreProperty, Sound, TextTheme } from './enums';
 import { Debuggable, Initializable, RendererInitializable, StateSyncable, Serializable } from './Interfaces';
 import { Cell, ControlCallback, ControlEventType, Coordinate, RendererMetrics, GameModules, StateProperty, Vector, Piece, Axis } from './Types';
 /**
@@ -583,58 +583,66 @@ export interface State extends Initializable {
      */
     unsubscribe(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Registers a callback for a specific state change ONLY during the title screen.
+     * Subscribes to changes in a specific state property only when in the Title Screen.
+     *
      * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * @param {function(boolean | number): void} callback - The function to execute.
      * @returns {void} Returns nothing.
      */
     subscribeForTitleScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Removes an existing title screen subscription.
-     * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * Unsubscribes a callback from Title Screen scoped notifications.
+     *
+     * @param {StateProperty} property - The state property being monitored.
+     * @param {function(boolean | number): void} callback - The callback to remove.
      * @returns {void} Returns nothing.
      */
     unsubscribeForTitleScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Registers a callback for a specific state change ONLY during the game over screen.
+     * Subscribes to changes in a specific state property only when in the Game Over screen.
+     *
      * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * @param {function(boolean | number): void} callback - The function to execute.
      * @returns {void} Returns nothing.
      */
     subscribeForGameOverScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Removes an existing game over screen subscription.
-     * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * Unsubscribes a callback from Game Over scoped notifications.
+     *
+     * @param {StateProperty} property - The state property being monitored.
+     * @param {function(boolean | number): void} callback - The callback to remove.
      * @returns {void} Returns nothing.
      */
     unsubscribeForGameOverScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Registers a callback for a specific state change ONLY during active gameplay.
+     * Subscribes to changes in a specific state property only during active Gameplay.
+     *
      * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * @param {function(boolean | number): void} callback - The function to execute.
      * @returns {void} Returns nothing.
      */
     subscribeForPlayingScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Removes an existing playing screen subscription.
-     * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * Unsubscribes a callback from Playing scoped notifications.
+     *
+     * @param {StateProperty} property - The state property being monitored.
+     * @param {function(boolean | number): void} callback - The callback to remove.
      * @returns {void} Returns nothing.
      */
     unsubscribeForPlayingScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Registers a callback for a specific state change ONLY during the paused screen.
+     * Subscribes to changes in a specific state property only when the game is Paused.
+     *
      * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * @param {function(boolean | number): void} callback - The function to execute.
      * @returns {void} Returns nothing.
      */
     subscribeForPausedScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
     /**
-     * Removes an existing paused screen subscription.
-     * @param {StateProperty} property - The state property to monitor.
-     * @param {function(boolean | number): void} callback - The function to execute when the property changes.
+     * Unsubscribes a callback from Paused scoped notifications.
+     *
+     * @param {StateProperty} property - The state property being monitored.
+     * @param {function(boolean | number): void} callback - The callback to remove.
      * @returns {void} Returns nothing.
      */
     unsubscribeForPausedScreen(property: StateProperty, callback: (value: boolean | number) => void): void;
@@ -814,73 +822,61 @@ export interface Control extends Initializable {
  * Manages the game loop timing, ticks, and delta time.
  */
 export interface Time extends Initializable {
-    /** The interval between logic ticks in milliseconds. */
-    tickInterval: number;
     /** The total number of ticks since the game started. */
     readonly totalTicks: number;
     /** Total elapsed time in milliseconds since the game started. */
     readonly elapsedTime: number;
     /**
-     * Checks if enough time has passed for a game tick based on a specific interval.
+     * Checks if enough time has passed based on a specific millisecond interval.
      *
-     * @param {number} interval - The tick interval to check.
-     * @returns {boolean} `true` if the current tick is a multiple of the interval.
+     * @param {number} ms - The millisecond interval to check.
+     * @returns {boolean} `true` if the logical clock just crossed a multiple of the interval.
      */
-    isTickEvery(interval: number): boolean;
+    atInterval(ms: number): boolean;
     /**
-     * Accumulates passed time and calculates FPS/TPS.
+     * Executes a callback function every N milliseconds of logical game time.
      *
-     * @param {number} deltaTime - Time elapsed since last frame in milliseconds.
-     * @returns {void} Returns nothing.
-     */
-    update(deltaTime: number): void;
-    /**
-     * Determines if a logic tick should occur based on the accumulator.
+     * Provides a declarative functional approach to handling recurring game logic,
+     * such as spawning enemies or updating timers.
      *
-     * @returns {boolean} `true` if a tick is due.
+     * @param {number} ms - The millisecond interval between executions.
+     * @param {() => void} action - The callback function to execute if the interval is crossed.
+     * @returns {void}
      */
-    shouldTick(): boolean;
+    every(ms: number, action: () => void): void;
     /**
-     * Resets internal time accumulators and counters.
+     * Updates the system clock, total elapsed time, and performance metrics (FPS/TPS).
      *
-     * @returns {void} Returns nothing.
-     */
-    reset(): void;
-    /**
-     * Increases the tick interval (slowing down the game logic).
+     * Should be invoked strictly once per hardware visual frame, even when the
+     * game is paused, to maintain accurate UI animations and performance tracking.
      *
-     * @param {number} amount - Milliseconds to add.
+     * @param {number} deltaTime - Time elapsed since last frame in milliseconds.
      * @returns {void} Returns nothing.
      */
-    incrementTickInterval(amount: number): void;
+    update(deltaTime: number): void;
     /**
-     * Decreases the tick interval (speeding up the game logic).
+     * Accumulates time specifically for the logical engine ticks.
      *
-     * @param {number} amount - Milliseconds to subtract.
-     * @returns {void} Returns nothing.
-     */
-    decrementTickInterval(amount: number): void;
-    /**
-     * Sets the tick interval.
+     * This should only be invoked when the game logic is active (not paused
+     * or on title screens) to prevent the logic from "catching up" after
+     * periods of inactivity.
      *
-     * @param {number} interval - The new tick interval in milliseconds.
+     * @param {number} deltaTime - Time to add to the logic accumulator.
      * @returns {void} Returns nothing.
      */
-    setTickInterval(interval: number): void;
+    accumulate(deltaTime: number): void;
     /**
-     * Sets the minimum tick interval.
+     * Determines if a logic tick should occur based on the accumulator.
      *
-     * @param {number} interval - The new minimum tick interval in milliseconds.
-     * @returns {void} Returns nothing.
+     * @returns {boolean} `true` if a tick is due.
      */
-    setMinTickInterval(interval: number): void;
+    shouldTick(): boolean;
     /**
-     * Captures the current tick interval as the initial state.
-     * Use this after games have set their starting speed.
+     * Resets internal time accumulators and counters.
      *
      * @returns {void} Returns nothing.
      */
-    captureInitialState(): void;
+    reset(): void;
 }
 /**
  * Interface for the audio module.
@@ -993,6 +989,20 @@ export interface Score {
      * @returns {void} Returns nothing.
      */
     setupGameHighScore(id: string): void;
+    /**
+     * Subscribes a callback for a specific score property.
+     * @param {ScoreProperty} property - The property to subscribe to.
+     * @param {function} callback - The callback function.
+     * @returns {void} Returns nothing.
+     */
+    subscribe(property: ScoreProperty, callback: (score: number) => void): void;
+    /**
+     * Unsubscribes a callback from a specific score property.
+     * @param {ScoreProperty} property - The property to unsubscribe from.
+     * @param {function} callback - The callback function.
+     * @returns {void} Returns nothing.
+     */
+    unsubscribe(property: ScoreProperty, callback: (score: number) => void): void;
 }
 export interface Session extends StateSyncable, Debuggable {
     gameId: string;

package/dist/types/view/ShortcutsModal.test.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brick-engine-js",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "A lightweight brick engine built with p5.js and TypeScript",
   "type": "commonjs",
   "main": "dist/brick-engine.js",