brick-engine-js 1.0.1

package/src/core/module/time/GameTime.ts

@@ -0,0 +1,144 @@
+import { Debuggable } from '../../types/Interfaces';
+import { Time } from '../../types/modules';
+import { Serializable } from '../../types/Interfaces';
+import configs from '../../../config/configs';
+
+/**
+ * Manages game time, frame rates, and tick intervals.
+ * Handles the game loop timing and debug statistics (FPS, TPS).
+ */
+export default class GameTime implements Time, Debuggable, Serializable {
+    // Time accumulator
+    protected _accumulatedTime: number = 0;
+    protected _initialTickInterval: number = configs.game.tickInterval;
+    protected _minTickInterval: number = configs.game.minTickInterval;
+    protected _tickInterval: number = configs.game.tickInterval;
+    protected _fps: number = 0;
+    protected _tps: number = 0;
+    protected _tickCounter: number = 0;
+    protected _timeSinceLastTpsUpdate: number = 0;
+
+    serialId: string = 'time';
+
+    /**
+     * Initializes the time module.
+     * Resets all timers and counters.
+     */
+    setup(): void {
+        this.reset();
+    }
+
+    /**
+     * Updates the time accumulator and calculates FPS/TPS.
+     * Should be called once per frame.
+     *
+     * @param {number} deltaTime - Time elapsed since last frame in milliseconds.
+     */
+    update(deltaTime: number) {
+        this._accumulatedTime += deltaTime;
+        this._fps = 1000 / deltaTime;
+
+        this._timeSinceLastTpsUpdate += deltaTime;
+        if (this._timeSinceLastTpsUpdate >= 1000) {
+            this._tps = this._tickCounter;
+            this._tickCounter = 0;
+            this._timeSinceLastTpsUpdate -= 1000;
+        }
+    }
+
+    /**
+     * Checks if enough time has passed for a game tick.
+     * Consumes accumulated time if a tick occurs.
+     *
+     * @returns {boolean} True if a tick should occur.
+     */
+    shouldTick(): boolean {
+        if (this._accumulatedTime >= this._tickInterval) {
+            this._accumulatedTime -= this._tickInterval;
+            this._tickCounter++;
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Resets the time accumulator and debug counters.
+     */
+    reset() {
+        this._accumulatedTime = 0;
+        this._fps = 0;
+        this._tps = 0;
+        this._tickCounter = 0;
+        this._timeSinceLastTpsUpdate = 0;
+        this._tickInterval = this._initialTickInterval;
+    }
+
+    /**
+     * Gets the current tick interval.
+     *
+     * @returns {number} The tick interval in milliseconds.
+     */
+    get tickInterval(): number {
+        return this._tickInterval;
+    }
+
+    /**
+     * Sets the tick interval and resets timing.
+     *
+     * @param {number} interval - The new tick interval in milliseconds.
+     */
+    set tickInterval(interval: number) {
+        this._tickInterval = interval;
+        // this.reset(); // Removed reset to prevent stuttering on speed change
+    }
+
+    /**
+     * Increments the tick interval (slowing down the game).
+     *
+     * @param {number} amount - The amount to add to the interval.
+     */
+    incrementTickInterval(amount: number) {
+        this.tickInterval = this._tickInterval + amount;
+    }
+
+    /**
+     * 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) {
+        const newInterval = Math.max(this._minTickInterval, this._tickInterval - amount);
+        this.tickInterval = newInterval;
+    }
+
+    /**
+     * Retrieves debug information about the time system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean> {
+        return {
+            fps: Math.round(this._fps),
+            tps: this._tps,
+            tick_interval: this._tickInterval.toFixed(2),
+            accumulated_time: this._accumulatedTime.toFixed(2),
+        };
+    }
+
+    serialize(): string {
+        return JSON.stringify({
+            tickInterval: this._tickInterval,
+        });
+    }
+    deserialize(data: string): void {
+        const parsed = JSON.parse(data);
+        this._tickInterval = parsed.tickInterval;
+    }
+    setTickInterval(interval: number): void {
+        this._tickInterval = interval;
+    }
+    setMinTickInterval(interval: number): void {
+        this._minTickInterval = interval;
+    }
+}

package/src/core/types/Interfaces.ts

@@ -0,0 +1,59 @@
+import { State } from './modules';
+import { RendererMetrics } from './Types';
+
+/**
+ * Defines a contract for modules that require an initialization step.
+ */
+export interface Initializable {
+    /**
+     * Initializes the module.
+     * Should be called after the instance is created and dependencies are injected.
+     */
+    setup(): void;
+}
+
+/**
+ * Defines a contract for modules that need to synchronize with the global game state.
+ * This is primarily used for persistence and state reactivity.
+ */
+export interface StateSyncable {
+    /** Reference to the central state module. */
+    _state: State;
+
+    /**
+     * Binds the module to the game state.
+     *
+     * @param {State} state - The game state instance to sync with.
+     */
+    syncState(state: State): void;
+}
+
+/**
+ * Defines a contract for renderers that require initialization with layout metrics.
+ */
+export interface RendererInitializable {
+    /**
+     * Initializes the renderer with calculated screen metrics.
+     *
+     * @param {RendererMetrics} rendererMetrics - The layout metrics (dimensions, origins).
+     */
+    setup(rendererMetrics: RendererMetrics): void;
+}
+
+/**
+ * Defines a contract for modules that expose internal data to the debug overlay.
+ */
+export interface Debuggable {
+    /**
+     * Retrieves key-multivalue pairs of debug information.
+     *
+     * @returns {Record<string, string | number | boolean>} A dictionary of debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+}
+
+export interface Serializable {
+    serialId: string;
+    serialize(): string;
+    deserialize(data: string): void;
+}

package/src/core/types/Types.ts

@@ -0,0 +1,124 @@
+import { Color, ControlKey, ControlEventType, StateProperty } from './enums';
+import { Control, Grid, RendererComposite, Score, Session, SoundModule, State, Text, Time } from './modules';
+
+export { Color, ControlKey, ControlEventType, StateProperty };
+
+/**
+ * Represents a single cell within the game grid.
+ */
+export type Cell = {
+    /** The cell's state value. `0` indicates inactive/empty, values > 0 indicate occupancy or type. */
+    value: number;
+    /** The color of the cell, defined by the {@link Color} enum. */
+    color: Color;
+    /** The logical grid coordinate of this cell. */
+    coordinate: Coordinate;
+};
+
+/**
+ * Represents a 2D direction vector with X and Y components.
+ * Values are restricted to -1, 0, or 1 to ensure unit-based movement.
+ */
+export type Vector = {
+    /** The X component (-1: left, 0: none, 1: right). */
+    x: -1 | 0 | 1;
+    /** The Y component (-1: up, 0: none, 1: down). */
+    y: -1 | 0 | 1;
+};
+
+/**
+ * Represents an axis in a 2D coordinate system.
+ */
+export type Axis = 'x' | 'y';
+
+/**
+ * Represents a piece which is a collection of cells.
+ */
+export type Piece = Cell[];
+
+/**
+ * Represents a 2D point in a coordinate system.
+ * Typically used for grid positions or normalized screen coordinates.
+ */
+export type Coordinate = {
+    /** The horizontal position. */
+    x: number;
+    /** The vertical position. */
+    y: number;
+};
+
+/**
+ * Defines the calculated layout metrics for the game renderer.
+ * These values are used to position elements on the HTML5 Canvas.
+ */
+export interface RendererMetrics {
+    /** Metrics for the main game display area. */
+    display: {
+        /** The computed width of the display in pixels. */
+        width: number;
+        /** The computed height of the display in pixels. */
+        height: number;
+        /** The top-left origin point of the display relative to the canvas. */
+        origin: Coordinate;
+    };
+    /** Metrics for the Head-Up Display (HUD) area. */
+    hud: {
+        /** The computed width of the HUD in pixels. */
+        width: number;
+        /** The computed height of the HUD in pixels. */
+        height: number;
+        /** The top-left origin point of the HUD relative to the canvas. */
+        origin: Coordinate;
+    };
+    /** Metrics for individual grid cells. */
+    cell: {
+        /** The computed size (width/height) of a cell in pixels. */
+        size: number;
+    };
+}
+
+/**
+ * Aggregates all core engine modules.
+ * This object is passed around to allow inter-module communication.
+ */
+export type GameModules = {
+    /** The main game grid module. */
+    grid: Grid;
+    /** The HUD grid module (usually 4x4 for previews). */
+    hudGrid: Grid;
+    /** The text rendering module. */
+    text: Text;
+    /** The game state and lifecycle module. */
+    state: State;
+    /** The input control module. */
+    control: Control;
+    /** The main renderer compositor module. */
+    renderer: RendererComposite;
+    /** The game loop timing module. */
+    time: Time;
+    /** The audio system module. */
+    sound: SoundModule;
+    /** The scoring and progression module. */
+    score: Score;
+    /** The game session module. */
+    session: Session;
+};
+
+/**
+ * Represents an input event triggered by the Control module.
+ */
+export interface GameEvent {
+    /** The control key associated with the event. */
+    key: ControlKey;
+    /** The type of event (Pressed or Held). */
+    type: ControlEventType;
+    /** Reference to the game modules for context-aware callbacks. */
+    modules: GameModules;
+}
+
+/**
+ * Callback function type for handling input events.
+ *
+ * @param {GameEvent} event - The event data containing key, type, and module access.
+ */
+export type ControlCallback = (event: GameEvent) => void;

package/src/core/types/enums.ts

@@ -0,0 +1,113 @@
+/**
+ * Enumerates all available colors for grid cells and UI elements.
+ */
+export enum Color {
+    DEFAULT = 'rgb(19, 26, 18)',
+    BLUE = 'rgb(0, 0, 128)',
+    CYAN = 'rgb(0, 128, 128)',
+    GRAY = 'rgb(128, 128, 128)',
+    GREEN = 'rgb(0, 128, 0)',
+    PURPLE = 'rgb(128, 0, 128)',
+    RED = 'rgb(128, 0, 0)',
+    YELLOW = 'rgb(128, 128, 0)',
+    INACTIVE = 'rgb(166, 183, 165)',
+}
+
+/**
+ * Enumerates all available horizontal text alignments.
+ */
+export enum FontAlign {
+    /** Aligns text to the center. */
+    CENTER = 'center',
+    /** Aligns text to the left. */
+    LEFT = 'left',
+    /** Aligns text to the right. */
+    RIGHT = 'right',
+}
+
+/**
+ * Enumerates all available font size presets.
+ * These correspond to specific pixel values calculated at runtime based on screen size.
+ */
+export enum FontSize {
+    EXTRA_SMALL = 0,
+    SMALL = 1,
+    MEDIUM = 2,
+    LARGE = 3,
+    EXTRA_LARGE = 4,
+}
+
+/**
+ * Enumerates all available vertical text alignments.
+ */
+export enum FontVerticalAlign {
+    /** Aligns text to the vertical center. */
+    CENTER = 'center',
+    /** Aligns text to the top. */
+    TOP = 'top',
+    /** Aligns text to the bottom. */
+    BOTTOM = 'bottom',
+}
+
+/**
+ * Enumerates all available sound assets.
+ * Each value corresponds to the path of the audio file.
+ */
+export enum Sound {
+    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',
+}
+
+/**
+ * Enumerates all logical control keys used in the engine.
+ * These are mapped to physical keys in the Control module.
+ */
+export enum ControlKey {
+    UP = 'up;control',
+    DOWN = 'down;control',
+    LEFT = 'left;control',
+    RIGHT = 'right;control',
+    ACTION = 'action;control',
+    POWER = 'power;system',
+    START_PAUSE = 'start_pause;system',
+    SOUND = 'sound;system',
+    RESET = 'reset;system',
+    EXIT = 'exit;system',
+    COLOR = 'color;system',
+}
+
+/**
+ * Enumerates the types of input events.
+ */
+export enum ControlEventType {
+    /** Triggered once when the key is pressed down. */
+    PRESSED = 'pressed',
+    /** Triggered continuously while the key is held down. */
+    HELD = 'held',
+}
+
+/**
+ * Enumerates all observable state properties.
+ * These keys are used for state subscriptions and persistence.
+ */
+export enum StateProperty {
+    ON = 'on',
+    START = 'start',
+    PLAYING = 'playing',
+    GAME_OVER = 'gameOver',
+    COLOR_ENABLED = 'colorEnabled',
+    MUTED = 'muted',
+}