brick-engine-js 1.0.1

package/dist/core/module/grid/GameGrid.d.ts

@@ -0,0 +1,399 @@
+import { Color } from '../../types/enums';
+import { Cell, Coordinate, Vector, Piece, Axis } from '../../types/Types';
+import { Debuggable } from '../../types/Interfaces';
+import { Grid } from '../../types/modules';
+import { Serializable } from '../../types/Interfaces';
+/**
+ * Manages the game's logical grid state and operations.
+ *
+ * Provides a robust API for cell manipulation, row/column management,
+ * collision detection, and mass grid modifications.
+ */
+export default class GameGrid implements Grid, Debuggable, Serializable {
+    /**
+     * The internal 2D array representing the game grid [y][x].
+     */
+    protected _grid: Cell[][];
+    private _movementEngine;
+    private _transformEngine;
+    private _analysisEngine;
+    private _lineEngine;
+    private _regionEngine;
+    serialId: string;
+    constructor();
+    /**
+     * Gets the current grid state as a 2D array of cells.
+     *
+     * @returns {Cell[][]} The underlying grid data.
+     */
+    getGrid(): Cell[][];
+    /**
+     * Gets the number of columns in the grid.
+     *
+     * @returns {number} The grid width.
+     */
+    get width(): number;
+    /**
+     * Gets the number of rows in the grid.
+     *
+     * @returns {number} The grid height.
+     */
+    get height(): number;
+    /**
+     * Initializes the grid by resetting its content to an empty state.
+     *
+     * @returns {void}
+     */
+    setup(): void;
+    /**
+     * Resets the entire grid state based on the dimensions defined in the configuration.
+     *
+     * Populates the grid with empty cells using {@link CellHelper.emptyCell}.
+     *
+     * @returns {void}
+     */
+    resetGrid(): void;
+    /**
+     * Iterates over every cell in the grid and executes a callback.
+     *
+     * @param {function(Cell): void} callback - The function to execute for each cell.
+     * @returns {void}
+     */
+    forEach(callback: (cell: Cell) => void): void;
+    /**
+     * Verifies if a given coordinate is within the grid boundaries.
+     *
+     * @param {Coordinate} coordinate - The coordinate to validate.
+     * @returns {boolean} True if the coordinate is valid, false otherwise.
+     */
+    isValidCoordinate(coordinate: Coordinate): boolean;
+    /**
+     * Retrieves a cell at a specific coordinate.
+     *
+     * @param {Coordinate} coordinate - The coordinate of the cell.
+     * @returns {Cell | null} The cell object, or null if out of bounds.
+     */
+    getCell(coordinate: Coordinate): Cell | null;
+    /**
+     * Updates the status value of a cell at a specific coordinate.
+     *
+     * @param {Coordinate} coordinate - The target coordinate.
+     * @param {number} value - The new value (e.g., 0 for inactive, >0 for active).
+     * @returns {void}
+     */
+    setCellValue(coordinate: Coordinate, value: number): void;
+    /**
+     * Updates the color of a cell at a specific coordinate.
+     *
+     * @param {Coordinate} coordinate - The target coordinate.
+     * @param {Color} color - The new color enum value.
+     * @returns {void}
+     */
+    setCellColor(coordinate: Coordinate, color: Color): void;
+    /**
+     * Checks if a cell at a specific coordinate is active (value > 0).
+     *
+     * @param {Coordinate} coordinate - The coordinate to check.
+     * @returns {boolean} True if active, false otherwise.
+     */
+    isCellActive(coordinate: Coordinate): boolean;
+    /**
+     * Checks if a cell at a specific coordinate is inactive (value === 0).
+     *
+     * @param {Coordinate} coordinate - The coordinate to check.
+     * @returns {boolean} True if inactive, false otherwise.
+     */
+    isCellInactive(coordinate: Coordinate): boolean;
+    /**
+     * Checks if every cell in a specific row is active.
+     *
+     * @param {number} y - The row index.
+     * @returns {boolean} True if the row is completely full.
+     */
+    isRowFull(y: number): boolean;
+    /**
+     * Checks if every cell in a specific row is inactive.
+     *
+     * @param {number} y - The row index.
+     * @returns {boolean} True if the row is completely empty.
+     */
+    isRowEmpty(y: number): boolean;
+    /**
+     * Resets all cells in a specific row to their default empty state.
+     *
+     * @param {number} y - The row index to clear.
+     * @returns {void}
+     */
+    clearRow(y: number): void;
+    /**
+     * Shifts all rows above a certain index down by one position.
+     *
+     * Clears the top-most row after shifting.
+     *
+     * @param {number} fromY - The starting row index for the shift down.
+     * @returns {void}
+     */
+    shiftRowsDown(fromY: number): void;
+    /**
+     * Shifts all rows below a certain index up by one position.
+     *
+     * Clears the bottom-most row after shifting.
+     *
+     * @param {number} fromY - The starting row index for the shift up.
+     * @returns {void}
+     */
+    shiftRowsUp(fromY: number): void;
+    /**
+     * Scans the grid for full rows, clears them, and shifts remaining rows down.
+     *
+     * Re-checks the same index after a shift to handle consecutive full rows.
+     *
+     * @returns {number} The total number of rows cleared during the operation.
+     */
+    clearFullRows(): number;
+    /**
+     * Checks if every cell in a specific column is active.
+     *
+     * @param {number} x - The column index.
+     * @returns {boolean} True if the column is completely full.
+     */
+    isColumnFull(x: number): boolean;
+    /**
+     * Checks if every cell in a specific column is inactive.
+     *
+     * @param {number} x - The column index.
+     * @returns {boolean} True if the column is completely empty.
+     */
+    isColumnEmpty(x: number): boolean;
+    /**
+     * Resets all cells in a specific column to their default empty state.
+     *
+     * @param {number} x - The column index to clear.
+     * @returns {void}
+     */
+    clearColumn(x: number): void;
+    /**
+     * Shifts all columns to the left of a certain index one position to the right.
+     *
+     * Clears the left-most column (index 0) after shifting.
+     *
+     * @param {number} fromX - The starting column index for the shift right.
+     * @returns {void}
+     */
+    shiftColumnsRight(fromX: number): void;
+    /**
+     * Shifts all columns to the right of a certain index one position to the left.
+     *
+     * Clears the right-most column after shifting.
+     *
+     * @param {number} fromX - The starting column index for the shift left.
+     * @returns {void}
+     */
+    shiftColumnsLeft(fromX: number): void;
+    /**
+     * Scans the grid for full columns, clears them, and shifts remaining columns right.
+     *
+     * @returns {number} The total number of columns cleared during the operation.
+     */
+    clearFullColumns(): number;
+    /**
+     * Checks if any of the provided coordinates are already occupied (active) or out of bounds.
+     *
+     * @param {Coordinate[]} coordinates - An array of coordinates to check.
+     * @returns {boolean} True if the area is occupied or invalid, false if completely clear.
+     */
+    isAreaOccupied(coordinates: Coordinate[]): boolean;
+    /**
+     * Fills a rectangular region defined by two corners with a specific value and color.
+     *
+     * Automatically handles bounds and coordinate order.
+     *
+     * @param {Coordinate} start - One corner of the rectangle.
+     * @param {Coordinate} end - The opposite corner of the rectangle.
+     * @param {number} value - The cell status value to apply.
+     * @param {Color} color - The color to apply.
+     * @returns {void}
+     */
+    fillArea(start: Coordinate, end: Coordinate, value: number, color: Color): void;
+    /**
+     * Updates multiple coordinates simultaneously with their specific values and colors.
+     *
+     * Effectively "stamps" a piece's shape onto the static grid.
+     *
+     * @param {Piece} piece - The collection of cells to stamp.
+     * @returns {void}
+     */
+    stampPiece(piece: Piece): void;
+    /**
+     * Updates a single coordinate with a specific value and color from a Cell.
+     *
+     * @param {Cell} cell - The cell containing coordinate, value and color.
+     * @returns {void}
+     */
+    stampCell(cell: Cell): void;
+    /**
+     * Attempts to shift a collection of cells (a piece) in a given direction.
+     *
+     * Validates that all new positions are within grid boundaries and are not
+     * occupied by other active cells (excluding the cells that are part of the original piece).
+     *
+     * @param {Piece} piece - The current piece (collection of cells).
+     * @param {Vector} direction - The movement vector (e.g., {x: -1, y: 0} for left).
+     * @returns {Piece | null} The new piece with updated coordinates if the move is valid, or null if blocked.
+     */
+    movePiece(piece: Piece, direction: Vector): Piece | null;
+    /**
+     * Alias for {@link movePiece} shifting one unit to the left.
+     * @param {Piece} piece - The current piece.
+     * @returns {Piece | null}
+     */
+    movePieceLeft(piece: Piece): Piece | null;
+    /**
+     * Alias for {@link movePiece} shifting one unit to the right.
+     * @param {Piece} piece - The current piece.
+     * @returns {Piece | null}
+     */
+    movePieceRight(piece: Piece): Piece | null;
+    /**
+     * Alias for {@link movePiece} shifting one unit up.
+     * @param {Piece} piece - The current piece.
+     * @returns {Piece | null}
+     */
+    movePieceUp(piece: Piece): Piece | null;
+    /**
+     * Alias for {@link movePiece} shifting one unit down.
+     * @param {Piece} piece - The current piece.
+     * @returns {Piece | null}
+     */
+    movePieceDown(piece: Piece): Piece | null;
+    /**
+     * Attempts to shift a single cell in a given direction.
+     *
+     * Validates that the new position is within grid boundaries and is not occupied.
+     *
+     * @param {Cell} cell - The current cell.
+     * @param {Vector} direction - The movement vector.
+     * @returns {Cell | null} The new cell with updated coordinate if the move is valid, or null if blocked.
+     */
+    moveCell(cell: Cell, direction: Vector): Cell | null;
+    /**
+     * Alias for {@link moveCell} shifting one unit to the left.
+     * @param {Cell} cell - The current cell.
+     * @returns {Cell | null}
+     */
+    moveCellLeft(cell: Cell): Cell | null;
+    /**
+     * Alias for {@link moveCell} shifting one unit to the right.
+     * @param {Cell} cell - The current cell.
+     * @returns {Cell | null}
+     */
+    moveCellRight(cell: Cell): Cell | null;
+    /**
+     * Alias for {@link moveCell} shifting one unit up.
+     * @param {Cell} cell - The current cell.
+     * @returns {Cell | null}
+     */
+    moveCellUp(cell: Cell): Cell | null;
+    /**
+     * Alias for {@link moveCell} shifting one unit down.
+     * @param {Cell} cell - The current cell.
+     * @returns {Cell | null}
+     */
+    moveCellDown(cell: Cell): Cell | null;
+    /**
+     * Attempts to rotate a piece 90 degrees around a specific origin.
+     *
+     * @param {Piece} piece - The current piece.
+     * @param {Coordinate} origin - The center of rotation.
+     * @param {boolean} [clockwise=true] - Direction of rotation.
+     * @returns {Piece | null} The new piece if rotation is valid, or null if blocked.
+     */
+    rotatePiece(piece: Piece, origin: Coordinate, clockwise?: boolean): Piece | null;
+    /**
+     * Identifies all rows that are completely filled with active cells.
+     *
+     * @returns {number[]} Array of row indices (y).
+     */
+    getFullRows(): number[];
+    /**
+     * Identifies all columns that are completely filled with active cells.
+     *
+     * @returns {number[]} Array of column indices (x).
+     */
+    getFullColumns(): number[];
+    /**
+     * Calculates the final resting position of a piece if it were dropped continuously.
+     *
+     * @param {Piece} piece - The piece to project.
+     * @returns {Piece} The piece at its final vertical resting position.
+     */
+    getDropPath(piece: Piece): Piece;
+    /**
+     * Calculates the final resting position of a piece if it were moved continuously upwards.
+     *
+     * @param {Piece} piece - The piece to project.
+     * @returns {Piece} The piece at its highest vertical resting position.
+     */
+    getRisePath(piece: Piece): Piece;
+    /**
+     * Calculates the final resting position of a piece if it were moved continuously to the left.
+     *
+     * @param {Piece} piece - The piece to project.
+     * @returns {Piece} The piece at its leftmost resting position.
+     */
+    getReachPathLeft(piece: Piece): Piece;
+    /**
+     * Calculates the final resting position of a piece if it were moved continuously to the right.
+     *
+     * @param {Piece} piece - The piece to project.
+     * @returns {Piece} The piece at its rightmost resting position.
+     */
+    getReachPathRight(piece: Piece): Piece;
+    /**
+     * Returns the active cells adjacent to a specific coordinate.
+     *
+     * @param {Coordinate} coord - The center coordinate.
+     * @param {boolean} [includeDiagonal=false] - Whether to include 8 neighbors or just 4.
+     * @returns {Cell[]} List of neighboring cells.
+     */
+    getNeighbors(coord: Coordinate, includeDiagonal?: boolean): Cell[];
+    /**
+     * Finds all connected active cells of the same value starting from a specific coordinate.
+     * Uses a Breadth-First Search (BFS) algorithm.
+     *
+     * @param {Coordinate} coord - Starting coordinate.
+     * @returns {Piece} Collection of connected cells.
+     */
+    findConnectedCells(coord: Coordinate): Piece;
+    /**
+     * Mirrors a piece across a specific axis relative to its bounding box.
+     *
+     * @param {Piece} piece - The piece to mirror.
+     * @param {Axis} axis - The axis to flip across ('x' for horizontal flip, 'y' for vertical).
+     * @returns {Piece} The mirrored piece.
+     */
+    mirrorPiece(piece: Piece, axis: Axis): Piece;
+    /**
+     * Swaps the values and colors of two cells.
+     *
+     * @param {Coordinate} a - First coordinate.
+     * @param {Coordinate} b - Second coordinate.
+     * @returns {void}
+     */
+    swapCells(a: Coordinate, b: Coordinate): void;
+    /**
+     * Private helper to get piece bounds, delegated to transform engine.
+     */
+    protected getPieceBounds(piece: Piece): {
+        min: Coordinate;
+        max: Coordinate;
+    };
+    /**
+     * Returns metadata for the real-time debugger.
+     *
+     * @returns {Record<string, string | number | boolean>} Technical debugging data.
+     */
+    getDebugData(): Record<string, string | number | boolean>;
+    serialize(): string;
+    deserialize(data: string): void;
+}

package/dist/core/module/grid/GameGrid.test.d.ts

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

package/dist/core/module/grid/GameHudGrid.d.ts

@@ -0,0 +1,24 @@
+import { Serializable } from '../../types/Interfaces';
+import GameGrid from './GameGrid';
+/**
+ * A specialized grid implementation for the Heads-Up Display (HUD).
+ * Typically used for previewing the "next piece" in Tetris-like games.
+ * It has fixed dimensions (usually 4x4).
+ */
+export default class GameHudGrid extends GameGrid implements Serializable {
+    serialId: string;
+    /**
+     * The fixed width of the HUD grid.
+     *
+     * @returns {number} Always returns 4.
+     */
+    get width(): number;
+    /**
+     * The fixed height of the HUD grid.
+     *
+     * @returns {number} Always returns 4.
+     */
+    get height(): number;
+    serialize(): string;
+    deserialize(data: string): void;
+}

package/dist/core/module/grid/GameHudGrid.test.d.ts

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

package/dist/core/module/grid/engines/GridAnalysisEngine.d.ts

@@ -0,0 +1,29 @@
+import { Cell, Coordinate, Piece } from '../../../types/Types';
+import { Grid } from '../../../types/modules';
+/**
+ * Handles analysis and search operations on the grid.
+ */
+export default class GridAnalysisEngine {
+    private grid;
+    constructor(grid: Grid);
+    /**
+     * Identifies all rows that are completely filled with active cells.
+     */
+    getFullRows(): number[];
+    /**
+     * Identifies all columns that are completely filled with active cells.
+     */
+    getFullColumns(): number[];
+    /**
+     * Returns the active cells adjacent to a specific coordinate.
+     */
+    getNeighbors(coord: Coordinate, includeDiagonal?: boolean): Cell[];
+    /**
+     * Finds all connected active cells of the same value starting from a specific coordinate.
+     */
+    findConnectedCells(coord: Coordinate): Piece;
+    /**
+     * Swaps the values and colors of two cells.
+     */
+    swapCells(a: Coordinate, b: Coordinate): void;
+}

package/dist/core/module/grid/engines/GridAnalysisEngine.test.d.ts

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

package/dist/core/module/grid/engines/GridLineEngine.d.ts

@@ -0,0 +1,56 @@
+import { Grid } from '../../../types/modules';
+/**
+ * Handles line-based operations (rows and columns) on the grid.
+ */
+export default class GridLineEngine {
+    private grid;
+    constructor(grid: Grid);
+    /**
+     * Checks if every cell in a specific row is active.
+     */
+    isRowFull(y: number): boolean;
+    /**
+     * Checks if every cell in a specific row is inactive.
+     */
+    isRowEmpty(y: number): boolean;
+    /**
+     * Resets all cells in a specific row to their default empty state.
+     */
+    clearRow(y: number): void;
+    /**
+     * Shifts all rows above a certain index down by one position.
+     */
+    shiftRowsDown(fromY: number): void;
+    /**
+     * Shifts all rows below a certain index up by one position.
+     */
+    shiftRowsUp(fromY: number): void;
+    /**
+     * Scans for full rows, clears them, and shifts remaining rows down.
+     */
+    clearFullRows(): number;
+    /**
+     * Checks if every cell in a specific column is active.
+     */
+    isColumnFull(x: number): boolean;
+    /**
+     * Checks if every cell in a specific column is inactive.
+     */
+    isColumnEmpty(x: number): boolean;
+    /**
+     * Resets all cells in a specific column to their default empty state.
+     */
+    clearColumn(x: number): void;
+    /**
+     * Shifts all columns to the left of a certain index one position to the right.
+     */
+    shiftColumnsRight(fromX: number): void;
+    /**
+     * Shifts all columns to the right of a certain index one position to the left.
+     */
+    shiftColumnsLeft(fromX: number): void;
+    /**
+     * Scans for full columns, clears them, and shifts remaining columns right.
+     */
+    clearFullColumns(): number;
+}

package/dist/core/module/grid/engines/GridLineEngine.test.d.ts

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

package/dist/core/module/grid/engines/GridMovementEngine.d.ts

@@ -0,0 +1,29 @@
+import { Cell, Vector, Piece } from '../../../types/Types';
+import { Grid } from '../../../types/modules';
+/**
+ * Handles movement and projection logic for the game grid.
+ */
+export default class GridMovementEngine {
+    private grid;
+    constructor(grid: Grid);
+    /**
+     * Attempts to shift a collection of cells (a piece) in a given direction.
+     */
+    movePiece(piece: Piece, direction: Vector): Piece | null;
+    movePieceLeft(piece: Piece): Piece | null;
+    movePieceRight(piece: Piece): Piece | null;
+    movePieceUp(piece: Piece): Piece | null;
+    movePieceDown(piece: Piece): Piece | null;
+    /**
+     * Attempts to shift a single cell in a given direction.
+     */
+    moveCell(cell: Cell, direction: Vector): Cell | null;
+    moveCellLeft(cell: Cell): Cell | null;
+    moveCellRight(cell: Cell): Cell | null;
+    moveCellUp(cell: Cell): Cell | null;
+    moveCellDown(cell: Cell): Cell | null;
+    getDropPath(piece: Piece): Piece;
+    getRisePath(piece: Piece): Piece;
+    getReachPathLeft(piece: Piece): Piece;
+    getReachPathRight(piece: Piece): Piece;
+}

package/dist/core/module/grid/engines/GridMovementEngine.test.d.ts

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

package/dist/core/module/grid/engines/GridRegionEngine.d.ts

@@ -0,0 +1,26 @@
+import { Color } from '../../../types/enums';
+import { Cell, Coordinate, Piece } from '../../../types/Types';
+import { Grid } from '../../../types/modules';
+/**
+ * Handles region-based operations (areas, stamps, and occupancy) on the grid.
+ */
+export default class GridRegionEngine {
+    private grid;
+    constructor(grid: Grid);
+    /**
+     * Checks if any of the provided coordinates are already occupied or out of bounds.
+     */
+    isAreaOccupied(coordinates: Coordinate[]): boolean;
+    /**
+     * Fills a rectangular region defined by two corners with a specific value and color.
+     */
+    fillArea(start: Coordinate, end: Coordinate, value: number, color: Color): void;
+    /**
+     * Updates multiple coordinates simultaneously with their specific values and colors.
+     */
+    stampPiece(piece: Piece): void;
+    /**
+     * Updates a single coordinate with a specific value and color from a Cell.
+     */
+    stampCell(cell: Cell): void;
+}

package/dist/core/module/grid/engines/GridRegionEngine.test.d.ts

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

package/dist/core/module/grid/engines/GridTransformEngine.d.ts

@@ -0,0 +1,24 @@
+import { Coordinate, Axis, Piece } from '../../../types/Types';
+import { Grid } from '../../../types/modules';
+/**
+ * Handles geometric transformations for pieces on the grid.
+ */
+export default class GridTransformEngine {
+    private grid;
+    constructor(grid: Grid);
+    /**
+     * Attempts to rotate a piece 90 degrees around a specific origin.
+     */
+    rotatePiece(piece: Piece, origin: Coordinate, clockwise?: boolean): Piece | null;
+    /**
+     * Mirrors a piece across a specific axis relative to its bounding box.
+     */
+    mirrorPiece(piece: Piece, axis: Axis): Piece;
+    /**
+     * Calculates the bounding box of a piece.
+     */
+    getPieceBounds(piece: Piece): {
+        min: Coordinate;
+        max: Coordinate;
+    };
+}

package/dist/core/module/grid/engines/GridTransformEngine.test.d.ts

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

package/dist/core/module/renderer/DisplayRenderer.d.ts

@@ -0,0 +1,51 @@
+import p5 from 'p5';
+import { Cell, GameModules, RendererMetrics } from '../../types/Types';
+import { Renderer, State } from '../../types/modules';
+/**
+ * Responsible for rendering the main game field (the grid where the game is played).
+ * Handles cell rendering, background drawing, and optimizes static elements using an off-screen buffer.
+ */
+export default class DisplayRenderer implements Renderer {
+    private _p;
+    private _rendererMetrics;
+    private _cellPreCalculatedGeometry;
+    private _staticGraphics;
+    /**
+     * Creates an instance of the DisplayRenderer.
+     *
+     * @param {p5} p - The p5 instance.
+     */
+    constructor(p: p5);
+    /**
+     * Initializes the renderer with the calculated metrics.
+     * Pre-calculates cell geometry for faster rendering.
+     *
+     * @param {RendererMetrics} rendererMetrics - The shared renderer metrics.
+     */
+    setup(rendererMetrics: RendererMetrics): void;
+    /**
+     * Renders the game grid.
+     * Draws the static background first, then iterates over the grid to draw cells.
+     *
+     * @param {Cell[][]} grid - The current grid state.
+     */
+    render(grid: Cell[][], modules: GameModules): void;
+    /**
+     * Renders static elements (background and borders) to an off-screen buffer.
+     * This improves performance by avoiding re-drawing static shapes every frame.
+     */
+    private _renderStaticElements;
+    /**
+     * Renders a single brick at grid coordinates.
+     * Uses translation matrices to keep drawing logic clean.
+     *
+     * @param {Cell} cell - The cell data to render.
+     */
+    protected renderCell({ coordinate, color, value }: Cell, state: State): void;
+    /**
+     * Iterates through the grid and renders each cell.
+     *
+     * @param {Cell[][]} grid - The grid to render.
+     */
+    protected renderGrid(grid: Cell[][], state: State): void;
+}

package/dist/core/module/renderer/DisplayRenderer.test.d.ts

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