brick-engine-js 1.0.1

package/dist/view/Debugger.d.ts

@@ -0,0 +1,12 @@
+import p5 from 'p5';
+import { Initializable } from '../core/types/Interfaces';
+import { GameModules } from '../core/types/Types';
+export default class NewDebugger implements Initializable {
+    private _p;
+    private _gameModules;
+    private _moduleElements;
+    constructor(gameModules: GameModules, p: p5);
+    setup(): void;
+    setGameModules(gameModules: GameModules): void;
+    update(): void;
+}

package/dist/view/Debugger.test.d.ts

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

package/dist/view/GameView.d.ts

@@ -0,0 +1,101 @@
+import p5 from 'p5';
+import { Control } from '../core/types/modules';
+import { GameModules } from '../core/types/Types';
+/**
+ * Responsible for rendering the game body and handling control events.
+ *
+ * This class acts as the main view controller, orchestrating the layout,
+ * styles, and user interaction (clicks and holds) for the game.
+ *
+ * @class
+ */
+export default class GameView {
+    private _onOffBtn;
+    private _startPauseBtn;
+    private _soundBtn;
+    private _resetBtn;
+    private _exitBtn;
+    private _enableColorBtn;
+    private _upBtn;
+    private _downBtn;
+    private _rightBtn;
+    private _leftBtn;
+    private _actionBtn;
+    private _parent;
+    private _p;
+    private _inputHandler;
+    private _cachedCanvas;
+    private _debugger;
+    private _sessionModal;
+    /**
+     * Creates an instance of GameView.
+     *
+     * @param p - The p5 instance used for rendering and event handling.
+     * @param parent - The DOM element where the game view will be attached.
+     */
+    constructor(p: p5, parent: HTMLElement);
+    /**
+     * Checks if the game body has been built.
+     * @returns True if the game body has been built, false otherwise.
+     */
+    isBodyBuilt(): boolean;
+    /**
+     * Builds the visual structure of the game.
+     *
+     * It initializes themes, layouts (frames, containers, buttons), and calculates responsive dimensions.
+     *
+     * @returns An object containing the canvas element and its explicit dimensions.
+     * - canvas: The p5 element for the canvas.
+     * - canvasWidth: The calculated width of the canvas.
+     * - canvasHeight: The calculated height of the canvas.
+     */
+    build(): {
+        canvas: p5.Element;
+        canvasWidth: number;
+        canvasHeight: number;
+    };
+    /**
+     * Sets up the session modal with the current game modules.
+     * @param gameModules - The game modules to be used in the session modal.
+     */
+    setupSessionModal(): void;
+    showSessionModal(onConfirm: () => void, onCancel: () => void): void;
+    /**
+     * Sets up the debugger with the current game modules.
+     * @param gameModules - The game modules to be debugged.
+     */
+    setupDebugger(gameModules: GameModules): void;
+    updateDebuggerGameModules(gameModules: GameModules): void;
+    /**
+     * Updates the debugger with the current game state.
+     */
+    updateDebugger(): void;
+    /**
+     * Binds game control events to the view buttons.
+     *
+     * Connects click and hold events from the UI buttons to the game logic controllers.
+     *
+     * @param control - The control module instance.
+     */
+    bindControls(control: Control): void;
+    /**
+     * Unbinds all events from the view buttons.
+     *
+     * Replaces all event listeners with empty functions to prevent interaction
+     * (e.g., when the game is paused or stopped).
+     */
+    unbindControls(): void;
+    /**
+     * Helper method to bind press and release events using ControlInputHandler.
+     *
+     * @param btn - The p5 button element to bind.
+     * @param key - The control key to notify.
+     */
+    private _bindButtonEvents;
+    /**
+     * Helper method to hide the splash screen after a delay.
+     *
+     * @param delay - The delay in milliseconds (defaults to `configs.viewLayout.splashHideDelayMs`).
+     */
+    private _hideSplash;
+}

package/dist/view/GameView.test.d.ts

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

package/dist/view/SessionModal.d.ts

@@ -0,0 +1,12 @@
+import { Initializable } from '../core/types/Interfaces';
+import p5 from 'p5';
+export default class SessionModal implements Initializable {
+    private _p;
+    private _container;
+    private _confirmButton;
+    private _cancelButton;
+    constructor(p: p5);
+    setup(): void;
+    show(onConfirm: () => void, onCancel: () => void): void;
+    private _hide;
+}

package/dist/view/SessionModal.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @vitest-environment jsdom
+ */
+export {};

package/dist/view/components/layout/ButtonLayout.d.ts

@@ -0,0 +1,25 @@
+import p5 from 'p5';
+interface ButtonLayoutResponse {
+    smallButtonContainer: p5.Element;
+    mediumButtonContainer: p5.Element;
+    largeButtonContainer: p5.Element;
+    directionVerticalContainer: p5.Element;
+    directionHorizontalContainer: p5.Element;
+}
+/**
+ * Creates and organizes the layout containers for game control buttons.
+ *
+ * It constructs a hierarchy of div elements to separate small system buttons,
+ * inner group buttons, and directional pads.
+ *
+ * @param {p5} p - The p5 instance.
+ * @param {p5.Element} container - The parent container element.
+ * @returns {ButtonLayoutResponse} Object containing the button containers.
+ *  - smallButtonContainer: For system buttons (Reset, Sound, etc.), uses `configs.selectors.viewElementIds.smallButtonContainer`.
+ *  - mediumButtonContainer: For direction controls, uses `configs.selectors.viewElementIds.mediumButtonContainer`.
+ *  - largeButtonContainer: For the main action button, uses `configs.selectors.viewElementIds.largeButtonContainer`.
+ *  - directionVerticalContainer: For Up/Down buttons.
+ *  - directionHorizontalContainer: For Left/Right buttons.
+ */
+export default function ButtonLayout(p: p5, container: p5.Element): ButtonLayoutResponse;
+export {};

package/dist/view/components/layout/ButtonLayout.test.d.ts

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

package/dist/view/components/layout/ContainerLayout.d.ts

@@ -0,0 +1,23 @@
+import p5 from 'p5';
+/**
+ * Response object containing container dimensions and element reference.
+ */
+interface ContainerResponse {
+    width: number;
+    height: number;
+    container: p5.Element;
+}
+/**
+ * Creates the main game container and calculates its optimal dimensions.
+ *
+ * It ensures the game container fits within the parent element (usually the window or a specific div)
+ * while maintaining a fixed aspect ratio defined by `configs.viewLayout.bodyHeightWidthMultiplier`.
+ * On smaller screens (<= configs.viewLayout.mobileBreakpoint width), it attempts to fill the parent width.
+ * On larger screens, it calculates the maximum dimensions that fit without overflowing vertically.
+ *
+ * @param {p5} p - The p5 instance.
+ * @param {HTMLElement} parent - The DOM element where the container will be appended.
+ * @returns {ContainerResponse} Object containing the container element and its calculated width/height.
+ */
+export default function ContainerLayout(p: p5, parent: HTMLElement): ContainerResponse;
+export {};

package/dist/view/components/layout/ContainerLayout.test.d.ts

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

package/dist/view/components/layout/FrameLayout.d.ts

@@ -0,0 +1,11 @@
+import p5 from 'p5';
+/**
+ * Creates the decorative frame for the game.
+ *
+ * Adds a visual frame around the game area and includes the branding text "Brick Game".
+ *
+ * @param p - The p5 instance.
+ * @param container - The parent container element.
+ * @returns The created frame element.
+ */
+export default function FrameLayout(p: p5, container: p5.Element): p5.Element;

package/dist/view/components/layout/FrameLayout.test.d.ts

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

package/dist/view/components/ui/BigButton.d.ts

@@ -0,0 +1,13 @@
+import p5 from 'p5';
+/**
+ * Creates the large action button.
+ *
+ * This button is typically used for the primary game action (e.g., rotate, fire).
+ * It creates a specific container and applies large button styles.
+ *
+ * @param p - The p5 instance.
+ * @param container - The container element to attach the button to.
+ * @param label - The text label for the button (currently used for aria-label or internal logic as visual label is commented out).
+ * @returns The created button element.
+ */
+export default function BigButton(p: p5, container: p5.Element, label: string): p5.Element;

package/dist/view/components/ui/BigButton.test.d.ts

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

package/dist/view/components/ui/Button.d.ts

@@ -0,0 +1,12 @@
+import p5 from 'p5';
+/**
+ * Creates a standard directional button.
+ *
+ * These buttons are used for the D-pad controls (Up, Down, Left, Right).
+ *
+ * @param p - The p5 instance.
+ * @param container - The container element to attach the button to.
+ * @param label - The text label for the button.
+ * @returns The created button element.
+ */
+export default function Button(p: p5, container: p5.Element, label: string): p5.Element;

package/dist/view/components/ui/Button.test.d.ts

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

package/dist/view/components/ui/Canvas.d.ts

@@ -0,0 +1,22 @@
+import p5 from 'p5';
+/**
+ * Response object containing canvas dimensions and element reference.
+ */
+interface CanvasResponse {
+    canvasWidth: number;
+    canvasHeight: number;
+    canvas: p5.Element;
+}
+/**
+ * Creates the main p5 canvas for rendering the game.
+ *
+ * It calculates the canvas size based on the provided container width, maintaining a specific aspect ratio
+ * defined by `configs.viewLayout.canvas.aspectRatio`.
+ *
+ * @param {p5} p - The p5 instance.
+ * @param {p5.Element} container - The frame container to attach the canvas to.
+ * @param {number} width - The width of the outer container, used to calculate canvas dimensions with `configs.viewLayout.canvas.widthRatio`.
+ * @returns {CanvasResponse} Object containing the canvas element and its calculated dimensions.
+ */
+export default function Canvas(p: p5, container: p5.Element, width: number): CanvasResponse;
+export {};

package/dist/view/components/ui/Canvas.test.d.ts

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

package/dist/view/components/ui/SmallButton.d.ts

@@ -0,0 +1,13 @@
+import p5 from 'p5';
+/**
+ * Creates a small system button (e.g., Reset, Sound).
+ *
+ * These buttons have a distinct style and include a visible paragraph label next to them.
+ *
+ * @param {p5} p - The p5 instance.
+ * @param {p5.Element} container - The container element to attach the button to.
+ * @param {string} label - The visible text label displayed near the button.
+ * @param {boolean} top - Determines position/styling nuance (e.g. if it belongs to the top row of small buttons).
+ * @returns {p5.Element} The created button element.
+ */
+export default function SmallButton(p: p5, container: p5.Element, label: string, top: boolean): p5.Element;

package/dist/view/components/ui/SmallButton.test.d.ts

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

package/dist/view/theme/applyColors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Applies color themes to the application by setting CSS variables.
+ *
+ * It checks for `configs.inputQueryParams.mainColor` and `configs.inputQueryParams.buttonColor` query parameters in the URL.
+ * If present, these values are used; otherwise, default `configs.colors` are applied.
+ * It also calculates and sets shadow and reflection variations for these colors.
+ *
+ * @returns {void}
+ */
+export default function applyColors(): void;

package/dist/view/theme/applyColors.test.d.ts

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

package/dist/view/theme/dimensions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calculates and sets various CSS variables for responsive sizing of the game UI.
+ *
+ * This function defines sizes for the main container, canvas, borders, buttons (including mobile variations),
+ * and fonts based on the provided dimensions.
+ *
+ * @param width - The width of the game container.
+ * @param height - The height of the game container.
+ * @param canvasWidth - The width of the game canvas.
+ * @param canvasHeight - The height of the game canvas.
+ * @returns
+ */
+export default function dimensions(width: number, height: number, canvasWidth: number, canvasHeight: number): void;

package/dist/view/theme/dimensions.test.d.ts

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

package/docs/GAME_DEVELOPER_GUIDE.adoc

@@ -0,0 +1,167 @@
+= Game Developer Guide
+
+This guide explains how to develop and package games for the Brick Engine.
+
+== Architecture
+
+The Brick Engine runs as a host application. Your game is loaded as a separate script bundle. To ensure compatibility and avoid code duplication:
+
+1.  **Do not bundle the engine**: Your game should treat `brick-engine` as an external dependency.
+2.  **Expose your class**: Your game must assign its main class to `window.BrickEngineGame`.
+
+== Project Setup
+
+=== 1. Dependencies
+
+You need `typescript` and `webpack` (or similar bundler). You also need the `brick-engine` types.
+
+=== Starting from Scratch
+
+If you are creating a new game project, follow these steps:
+
+1.  **Initialize Project**:
+    `npm init -y`
+
+2.  **Install Dependencies**:
+    `npm install --save-dev typescript webpack webpack-cli ts-loader unused-webpack-plugin` (adjust as needed)
+
+3.  **Configure TypeScript (`tsconfig.json`)**:
++
+[source,json]
+----
+{
+    "compilerOptions": {
+        "outDir": "./dist/",
+        "noImplicitAny": true,
+        "module": "es6",
+        "target": "es5",
+        "allowJs": true,
+        "moduleResolution": "node",
+        "resolveJsonModule": true,
+        "types": ["node"]
+    },
+    "include": ["src/**/*"]
+}
+----
+
+4.  **Configure Webpack (`webpack.config.js`)**:
+    (See section 3 below)
+
+5.  **Add Scripts to `package.json`**:
++
+[source,json]
+----
+"scripts": {
+    "build": "webpack --mode production",
+    "start": "webpack serve --mode development"
+}
+----
+
+=== Local Development Setup (Linking)
+
+Since the engine is not yet published to npm, you can link it locally:
+
+1.  **In `brick-engine` folder**:
+    *   Run `npm install`
+    *   Run `npm run build:types` (to generate `.d.ts` files)
+    *   Run `npm link`
+2.  **In your game folder**:
+    *   Run `npm link brick-engine`
+
+This makes `import { Game } from 'brick-engine'` work in your editor!
+
+=== 2. Entry Point (`src/index.ts`)
+
+Instead of `new Game()`, you simply export your class to the global scope:
+
+[source,typescript]
+----
+import { Game } from 'brick-engine'; // Resolves to global BrickEngine.Game
+
+export default class MyGame extends Game {
+    setupGame() {
+        // ... your setup logic
+    }
+
+    update() {
+        // ... your update logic
+    }
+    
+    render() {
+        // ... your render logic
+    }
+}
+
+// CRITICAL: Register your game
+(window as any).BrickEngineGame = MyGame;
+----
+
+=== 3. Webpack Configuration
+
+Configure Webpack to exclude `brick-engine` and `p5` from your bundle.
+
+[source,javascript]
+----
+// webpack.config.js
+const path = require('path');
+
+module.exports = {
+    entry: './src/index.ts',
+    module: {
+        rules: [
+            {
+                test: /\.tsx?$/,
+                use: 'ts-loader',
+                exclude: /node_modules/,
+            },
+        ],
+    },
+    resolve: {
+        extensions: ['.tsx', '.ts', '.js'],
+    },
+    externals: {
+        'brick-engine': 'BrickEngine', // Maps import 'brick-engine' to window.BrickEngine
+        'p5': 'p5' // p5 is also provided by the engine
+    },
+    output: {
+        filename: 'my-game.bundle.js',
+        path: path.resolve(__dirname, 'dist'),
+        library: {
+            type: 'var',
+            name: 'MyGameBundle' // Optional, but good practice
+        }
+    }
+};
+----
+
+== Local Testing
+
+You can test your game locally without uploading it:
+
+1.  **Build** your game (`npm run build`).
+2.  **Serve** the `dist` folder:
+    *   Command: `npx http-server ./dist --cors` (or similar).
+    *   Note the URL (e.g., `http://127.0.0.1:8081/my-game.bundle.js`).
+3.  **Register** in Engine:
+    *   In `src/menu/GameRepository.ts`, add a temporary entry:
++
+[source,typescript]
+----
+{
+    name: 'My Local Game',
+    url: 'http://127.0.0.1:8081/my-game.bundle.js'
+}
+----
+
+== Publishing and Submission
+
+Once your game is ready and hosted (e.g., on GitHub Pages):
+
+1.  **Test**: Ensure it loads correctly when you manually simulate a load (or use the provided template).
+2.  **Submit**: To have your game listed in the official Brick Engine menu, please send an email to **[EMAIL_ADDRESS]** with the following details:
+    *   **Game Name**: The title of your game.
+    *   **Bundle URL**: The direct link to your `.js` bundle.
+    *   **Thumbnail/Icon**: (Optional) A small image for the menu.
+    *   **Source Code**: (Optional) Link to your repository.
+
+We will review your game and add it to the repository!

package/docs/brick-engine-guide.adoc

@@ -0,0 +1,87 @@
+= Brick Engine CLI
+:toc: left
+:sectnums:
+
+CLI to scaffold Brick Engine projects.
+
+== Introduction
+
+`brick-engine-cli` is a command-line tool designed to accelerate game development using the **Brick Engine**. It automates the creation of the project's initial structure, configures build tools and code quality settings, allowing you to start programming your game immediately.
+
+== Installation and Usage
+
+You can use this tool in two main ways:
+
+=== 1. Use Without Installation (Recommended)
+
+The fastest way to get started is using `npx`, which runs the latest version of the tool without requiring a global installation on your system:
+
+[source,bash]
+----
+npx brick-engine-cli init <project-name>
+----
+
+=== 2. Global Installation
+
+If you prefer to have the command permanently available in your terminal, you can install it globally via `npm`:
+
+[source,bash]
+----
+npm install -g brick-engine-cli
+----
+
+After installation, you can use the command directly:
+
+[source,bash]
+----
+brick-engine-cli init <project-name>
+----
+
+== Commands
+
+=== `init <name>`
+
+Initializes a new Brick Engine project in a directory with the provided name.
+
+During the process, you will be asked about:
+* Project description.
+* Whether you want to use **ESLint** to ensure code quality.
+* Whether you want to use **Prettier** for automatic formatting.
+
+== Template Scripts
+
+Generated projects come with the following scripts in `package.json`:
+
+=== Development and Build
+
+[cols="1,3"]
+|===
+| Command | Description
+
+| `npm start`
+| Starts the development server with hot reload and opens the browser in `standalone` mode.
+
+| `npm run build:standalone`
+| Generates the production version of the game in the `/dist` folder for independent web hosting.
+
+| `npm run build:bundle`
+| Generates an optimized bundle to be loaded at link:https://brickengine.com.br[brickengine.com.br], where you can play all previously published games directly in the browser.
+
+| `npm run serve`
+| Starts a local HTTP server to test the production version generated in `/dist`.
+|===
+
+=== Code Quality (Optional)
+
+If you selected these options during `init`:
+
+[cols="1,3"]
+|===
+| Command | Description
+
+| `npm run format`
+| Automatically formats the code using **Prettier**.
+
+| `npm run lint`
+| Runs **ESLint** to find issues in the code.
+|===

package/docs/diagrams/lifecycle.mmd

@@ -0,0 +1,19 @@
+graph TD
+    Start([Start]) --> Setup[Setup Modules]
+    Setup --> DrawLoop{Draw Loop}
+    
+    subgraph "Each Frame (Draw)"
+        DrawLoop --> TimeUpdate[Time Update]
+        TimeUpdate --> CheckTick{"Should Tick?"}
+        CheckTick -- Yes --> ProcessTick["Process Logic (Tick) [processTick()]"]
+        CheckTick -- No --> RenderGrid
+        ProcessTick --> RenderGrid[Render Grid]
+        RenderGrid --> CheckFrame{"Frame Interval?"}
+        CheckFrame -- Yes --> ProcessFrame["Process Visuals (Frame) [processFrame()]"]
+        CheckFrame -- No --> CheckPerf
+        ProcessFrame --> CheckPerf{"Performance Monitor Enabled?"}
+        CheckPerf -- Yes --> RenderPerf[Render Performance Monitor]
+    end
+    
+    CheckPerf -- No --> DrawLoop
+    RenderPerf --> DrawLoop