brick-engine-js 1.0.1

package/src/core/helpers/CoordinateHelper.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import p5 from 'p5';
+import CoordinateHelper from './CoordinateHelper';
+import RelativeValuesHelper from './RelativeValuesHelper';
+
+// [ARRANGE] Mock dependencies
+vi.mock('./RelativeValuesHelper');
+vi.mock('../../config/configs', () => ({
+    default: {
+        screenLayout: {
+            display: {
+                margin: 0.05,
+            },
+        },
+    },
+}));
+
+describe('CoordinateHelper', () => {
+    const mockP5 = {
+        width: 1000,
+        height: 2000,
+    } as unknown as p5;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('getRelativeCoordinate', () => {
+        it('should scale coordinates using RelativeValuesHelper', () => {
+            // [ARRANGE]
+            const coord = { x: 0.5, y: 0.5 };
+            vi.mocked(RelativeValuesHelper.getRelativeWidth).mockReturnValue(500);
+            vi.mocked(RelativeValuesHelper.getRelativeHeight).mockReturnValue(1000);
+
+            // [ACT]
+            const result = CoordinateHelper.getRelativeCoordinate(mockP5, coord);
+
+            // [ASSERT]
+            expect(result).toEqual({ x: 500, y: 1000 });
+            expect(RelativeValuesHelper.getRelativeWidth).toHaveBeenCalledWith(mockP5, 0.5);
+            expect(RelativeValuesHelper.getRelativeHeight).toHaveBeenCalledWith(mockP5, 0.5);
+        });
+    });
+
+    describe('getDisplayPosX', () => {
+        it('should calculate absolute X with margin', () => {
+            // [ARRANGE]
+            const x = 0.5;
+            const displayWidth = 600;
+            // margin is 0.05 in mock. RelativeWidth(0.05) -> 50
+            vi.mocked(RelativeValuesHelper.getRelativeWidth).mockReturnValue(50);
+
+            // [ACT]
+            const result = CoordinateHelper.getDisplayPosX(mockP5, x, displayWidth);
+
+            // [ASSERT]
+            // result = 600 * 0.5 + 50 = 350
+            expect(result).toBe(350);
+            expect(RelativeValuesHelper.getRelativeWidth).toHaveBeenCalledWith(mockP5, 0.05);
+        });
+    });
+
+    describe('getDisplayPosY', () => {
+        it('should calculate absolute Y with margin', () => {
+            // [ARRANGE]
+            const y = 0.5;
+            const displayHeight = 1000;
+            vi.mocked(RelativeValuesHelper.getRelativeHeight).mockReturnValue(100);
+
+            // [ACT]
+            const result = CoordinateHelper.getDisplayPosY(mockP5, y, displayHeight);
+
+            // [ASSERT]
+            // result = 1000 * 0.5 + 100 = 600
+            expect(result).toBe(600);
+            expect(RelativeValuesHelper.getRelativeHeight).toHaveBeenCalledWith(mockP5, 0.05);
+        });
+    });
+
+    describe('getHudPosX', () => {
+        it('should calculate absolute X for HUD', () => {
+            // [ARRANGE]
+            const x = 0.5;
+            const displayWidth = 600;
+            // zero = displayWidth + margin*2 = 600 + 50*2 = 700
+            // width = p.width - zero - margin = 1000 - 700 - 50 = 250
+            // result = 250 * 0.5 + 700 = 125 + 700 = 825
+            vi.mocked(RelativeValuesHelper.getRelativeWidth).mockReturnValue(50);
+
+            // [ACT]
+            const result = CoordinateHelper.getHudPosX(mockP5, x, displayWidth);
+
+            // [ASSERT]
+            expect(result).toBe(825);
+        });
+    });
+
+    describe('getHudPosY', () => {
+        it('should calculate absolute Y for HUD (same logic as display)', () => {
+            // [ARRANGE]
+            const y = 0.1;
+            const displayHeight = 1000;
+            vi.mocked(RelativeValuesHelper.getRelativeHeight).mockReturnValue(100);
+
+            // [ACT]
+            const result = CoordinateHelper.getHudPosY(mockP5, y, displayHeight);
+
+            // [ASSERT]
+            // 1000 * 0.1 + 100 = 200
+            expect(result).toBe(200);
+        });
+    });
+});

package/src/core/helpers/CoordinateHelper.ts

@@ -0,0 +1,82 @@
+import p5 from 'p5';
+import { Coordinate } from '../types/Types';
+import configs from '../../config/configs';
+import RelativeValuesHelper from './RelativeValuesHelper';
+
+/**
+ * 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 {
+        return {
+            x: RelativeValuesHelper.getRelativeWidth(p, coordinate.x),
+            y: RelativeValuesHelper.getRelativeHeight(p, coordinate.y),
+        };
+    }
+
+    /**
+     * 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 {
+        const { margin } = configs.screenLayout.display;
+
+        return displayWidth * x + RelativeValuesHelper.getRelativeWidth(p, margin);
+    }
+
+    /**
+     * 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 {
+        const { margin } = configs.screenLayout.display;
+        return displayHeight * y + RelativeValuesHelper.getRelativeHeight(p, margin);
+    }
+
+    /**
+     * 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 {
+        const { margin } = configs.screenLayout.display;
+        const zero = displayWidth + RelativeValuesHelper.getRelativeWidth(p, margin) * 2;
+        const width = p.width - zero - RelativeValuesHelper.getRelativeWidth(p, margin);
+        return width * x + zero;
+    }
+
+    /**
+     * 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 {
+        const { margin } = configs.screenLayout.display;
+
+        return displayHeight * y + RelativeValuesHelper.getRelativeHeight(p, margin);
+    }
+}

package/src/core/helpers/InterfaceIdentifierHelper.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import InterfaceIdentifierHelper from './InterfaceIdentifierHelper';
+import GameState from '../module/state/GameState';
+
+describe('InterfaceIdentifierHelper', () => {
+    describe('isSerializable', () => {
+        it('should return true when object has serialize, deserialize and serialId', () => {
+            // [ARRANGE]
+            const validModule = {
+                serialize: () => '{}',
+                deserialize: () => {},
+                serialId: 'test-id',
+            };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isSerializable(validModule);
+
+            // [ASSERT]
+            expect(result).toBe(true);
+        });
+
+        it('should return false when object is missing required methods or properties', () => {
+            // [ARRANGE]
+            const invalidModule = { serialize: () => '{}' };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isSerializable(invalidModule);
+
+            // [ASSERT]
+            expect(result).toBe(false);
+        });
+
+        it('should return false when object is null or undefined', () => {
+            // [ACT] & [ASSERT]
+            expect(InterfaceIdentifierHelper.isSerializable(null as unknown as object)).toBe(false);
+            expect(InterfaceIdentifierHelper.isSerializable(undefined as unknown as object)).toBe(false);
+        });
+    });
+
+    describe('isInitializable', () => {
+        it('should return true when object has a setup function', () => {
+            // [ARRANGE]
+            const validModule = { setup: () => {} };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isInitializable(validModule);
+
+            // [ASSERT]
+            expect(result).toBe(true);
+        });
+
+        it('should return false when object lacks a setup function', () => {
+            // [ARRANGE]
+            const invalidModule = { otherMethod: () => {} };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isInitializable(invalidModule);
+
+            // [ASSERT]
+            expect(result).toBe(false);
+        });
+    });
+
+    describe('isStateSyncable', () => {
+        it('should return true when object has syncState and is NOT GameState', () => {
+            // [ARRANGE]
+            const validModule = { syncState: () => {} };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isStateSyncable(validModule);
+
+            // [ASSERT]
+            expect(result).toBe(true);
+        });
+
+        it('should return false when object is an instance of GameState', () => {
+            // [ARRANGE]
+            const gameStateInstance = new GameState();
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isStateSyncable(gameStateInstance);
+
+            // [ASSERT]
+            expect(result).toBe(false);
+        });
+
+        it('should return false when object lacks syncState method', () => {
+            // [ARRANGE]
+            const invalidModule = { otherMethod: () => {} };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isStateSyncable(invalidModule);
+
+            // [ASSERT]
+            expect(result).toBe(false);
+        });
+    });
+
+    describe('isDebuggable', () => {
+        it('should return true when object has getDebugData function', () => {
+            // [ARRANGE]
+            const validModule = { getDebugData: () => ({}) };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isDebuggable(validModule);
+
+            // [ASSERT]
+            expect(result).toBe(true);
+        });
+
+        it('should return false when object lacks getDebugData function', () => {
+            // [ARRANGE]
+            const invalidModule = { otherMethod: () => {} };
+
+            // [ACT]
+            const result = InterfaceIdentifierHelper.isDebuggable(invalidModule);
+
+            // [ASSERT]
+            expect(result).toBe(false);
+        });
+    });
+});

package/src/core/helpers/InterfaceIdentifierHelper.ts

@@ -0,0 +1,43 @@
+import GameState from '../module/state/GameState';
+import { Debuggable, Initializable, StateSyncable, Serializable } from '../types/Interfaces';
+
+export default class InterfaceIdentifierHelper {
+    static isSerializable(module: object): module is Serializable {
+        if (module === null || module === undefined) return false;
+
+        const serializable = module as Serializable;
+
+        const hasSerialize = typeof serializable.serialize === 'function';
+        const hasDeserialize = typeof serializable.deserialize === 'function';
+        const hasSerialId = typeof serializable.serialId === 'string';
+
+        return hasSerialize && hasDeserialize && hasSerialId;
+    }
+
+    static isInitializable(module: object): module is Initializable {
+        if (module === null || module === undefined) return false;
+
+        const initializable = module as Initializable;
+
+        return typeof initializable.setup === 'function';
+    }
+
+    static isStateSyncable(module: object): module is StateSyncable {
+        if (module === null || module === undefined) return false;
+
+        const stateSyncable = module as StateSyncable;
+
+        const hasSyncState = typeof stateSyncable.syncState === 'function';
+        const isGameState = stateSyncable instanceof GameState;
+
+        return hasSyncState && !isGameState;
+    }
+
+    static isDebuggable(module: object): module is Debuggable {
+        if (module === null || module === undefined) return false;
+
+        const debuggable = module as Debuggable;
+
+        return typeof debuggable.getDebugData === 'function';
+    }
+}

package/src/core/helpers/RelativeValuesHelper.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import p5 from 'p5';
+import RelativeValuesHelper from './RelativeValuesHelper';
+
+describe('RelativeValuesHelper', () => {
+    // [ARRANGE]
+    const mockP5 = {
+        width: 1000,
+        height: 2000,
+    } as unknown as p5;
+
+    describe('getRelativeWidth', () => {
+        it('should return 500 when size is 0.5 and p5.width is 1000', () => {
+            // [ACT]
+            const result = RelativeValuesHelper.getRelativeWidth(mockP5, 0.5);
+
+            // [ASSERT]
+            expect(result).toBe(500);
+        });
+
+        it('should return 0 when size is 0', () => {
+            // [ACT]
+            const result = RelativeValuesHelper.getRelativeWidth(mockP5, 0);
+
+            // [ASSERT]
+            expect(result).toBe(0);
+        });
+    });
+
+    describe('getRelativeHeight', () => {
+        it('should return 1000 when size is 0.5 and p5.height is 2000', () => {
+            // [ACT]
+            const result = RelativeValuesHelper.getRelativeHeight(mockP5, 0.5);
+
+            // [ASSERT]
+            expect(result).toBe(1000);
+        });
+
+        it('should return 2000 when size is 1', () => {
+            // [ACT]
+            const result = RelativeValuesHelper.getRelativeHeight(mockP5, 1);
+
+            // [ASSERT]
+            expect(result).toBe(2000);
+        });
+    });
+});

package/src/core/helpers/RelativeValuesHelper.ts

@@ -0,0 +1,29 @@
+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 {
+        return size * p.width;
+    }
+
+    /**
+     * 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 {
+        return size * p.height;
+    }
+}

package/src/core/module/control/GameControl.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import GameControl from './GameControl';
+import { ControlKey, ControlEventType } from '../../types/enums';
+import { GameModules } from '../../types/Types';
+import { State } from '../../types/modules';
+
+describe('GameControl', () => {
+    let control: GameControl;
+    let mockModules: GameModules;
+
+    beforeEach(() => {
+        control = new GameControl();
+        mockModules = {
+            state: {
+                isOn: vi.fn().mockReturnValue(true),
+                isOff: vi.fn().mockReturnValue(false),
+                isStarted: vi.fn().mockReturnValue(false),
+                isPlaying: vi.fn().mockReturnValue(false),
+                isPaused: vi.fn().mockReturnValue(false),
+                isGameOver: vi.fn().mockReturnValue(false),
+            } as unknown as State,
+        } as GameModules;
+        control.setModules(mockModules);
+    });
+
+    describe('notify', () => {
+        it('should throw error if modules are not set', () => {
+            // [ARRANGE]
+            const freshControl = new GameControl();
+
+            // [ACT & ASSERT]
+            expect(() => freshControl.notify(ControlKey.UP, ControlEventType.PRESSED)).toThrow('Modules not initialized');
+        });
+
+        it('should notify all subscribers of a key event', () => {
+            // [ARRANGE]
+            const callback = vi.fn();
+            control.subscribe(ControlKey.UP, ControlEventType.PRESSED, callback);
+
+            // [ACT]
+            control.notify(ControlKey.UP, ControlEventType.PRESSED);
+
+            // [ASSERT]
+            expect(callback).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    key: ControlKey.UP,
+                    type: ControlEventType.PRESSED,
+                    modules: mockModules,
+                }),
+            );
+        });
+
+        it('should not notify unsubscribed callbacks', () => {
+            // [ARRANGE]
+            const callback = vi.fn();
+            control.subscribe(ControlKey.UP, ControlEventType.PRESSED, callback);
+            control.unsubscribe(ControlKey.UP, ControlEventType.PRESSED, callback);
+
+            // [ACT]
+            control.notify(ControlKey.UP, ControlEventType.PRESSED);
+
+            // [ASSERT]
+            expect(callback).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('getDebugData', () => {
+        it('should return subscriber counts', () => {
+            // [ARRANGE]
+            control.subscribe(ControlKey.UP, ControlEventType.PRESSED, vi.fn());
+            control.subscribe(ControlKey.DOWN, ControlEventType.PRESSED, vi.fn());
+            control.subscribe(ControlKey.DOWN, ControlEventType.HELD, vi.fn());
+
+            // [ACT]
+            const debug = control.getDebugData();
+
+            // [ASSERT]
+            expect(debug.total_subscribers).toBe(3);
+            expect(debug.tracked_keys).toBe(2); // UP and DOWN
+        });
+    });
+});

package/src/core/module/control/GameControl.ts

@@ -0,0 +1,142 @@
+import { ControlKey } from '../../types/enums';
+import { Control } from '../../types/modules';
+import { Debuggable } from '../../types/Interfaces';
+import { ControlCallback, ControlEventType, GameEvent, GameModules } from '../../types/Types';
+import GameControlKeyBinding from './GameControlKeyBinding';
+
+/**
+ * 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: GameModules;
+
+    private _keyBinding: GameControlKeyBinding;
+    private _subscribers: Map<ControlKey, Map<ControlEventType, Set<ControlCallback>>> = new Map();
+
+    /**
+     * Initializes the control system.
+     * Sets up key bindings and prepares the input handler.
+     */
+    setup() {
+        this._keyBinding = new GameControlKeyBinding(this);
+
+        this._keyBinding.bindControls();
+    }
+
+    /**
+     * Unbinds all control event listeners.
+     */
+    unbindControls() {
+        this._keyBinding.unbindControls();
+        this._subscribers.clear();
+    }
+
+    /**
+     * Binds all control event listeners.
+     */
+    bindControls() {
+        this._keyBinding.bindControls();
+    }
+
+    /**
+     * Injects the game modules for context-aware events.
+     *
+     * @param {GameModules} modules - The collected game modules.
+     */
+    setModules(modules: GameModules): void {
+        this._modules = modules;
+    }
+
+    /**
+     * 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 {
+        if (!this._subscribers.has(key)) {
+            this._subscribers.set(key, new Map());
+        }
+
+        const keySubscribers = this._subscribers.get(key)!;
+        if (!keySubscribers.has(type)) {
+            keySubscribers.set(type, new Set());
+        }
+
+        keySubscribers.get(type)!.add(callback);
+    }
+
+    /**
+     * 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 {
+        const keySubscribers = this._subscribers.get(key);
+        if (keySubscribers) {
+            const callbacks = keySubscribers.get(type);
+            if (callbacks) {
+                callbacks.delete(callback);
+            }
+        }
+    }
+
+    /**
+     * 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 {
+        if (!this._modules) {
+            throw new Error('Modules not initialized');
+        }
+
+        const event: GameEvent = {
+            key,
+            type,
+            modules: this._modules,
+        };
+
+        const state = this._modules.state;
+
+        let isAllowed = false;
+
+        if (state.isOff()) {
+            isAllowed = key === ControlKey.POWER;
+        } else if (!state.isStarted() || state.isPlaying() || state.isGameOver()) {
+            isAllowed = true;
+        } else if (state.isPaused()) {
+            isAllowed = key.endsWith(';system');
+        }
+
+        const callbacks = this._subscribers.get(key)?.get(type);
+        if (callbacks && isAllowed) {
+            callbacks.forEach(callback => callback(event));
+        }
+    }
+
+    /**
+     * Retrieves debug information about the control system.
+     *
+     * @returns {Record<string, string | number | boolean>} The debug data.
+     */
+    getDebugData(): Record<string, string | number | boolean> {
+        let totalSubscribers = 0;
+        this._subscribers.forEach(keyMap => {
+            keyMap.forEach(typeSet => {
+                totalSubscribers += typeSet.size;
+            });
+        });
+
+        return {
+            total_subscribers: totalSubscribers,
+            tracked_keys: this._subscribers.size,
+        };
+    }
+}