npm - brick-engine-js - Versions diffs - 1.0.8 → 1.0.10 - Mend

brick-engine-js 1.0.8 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (280) hide show

package/docs/reference/modules/GameGrid.adoc DELETED Viewed

@@ -1,794 +0,0 @@
-= GameGrid Module Reference
-:description: Manages the state of a 2D grid for cell manipulation and collision detection.
-:keywords: grid, cells, logic, collision
-:toc: left
-:toclevels: 3
-:sectnums:
-:sectlinks:
-:icons: font
-:source-highlighter: highlight.js
-:reproducible:
-:experimental:
-:idprefix:
-:idseparator: -
-The `GameGrid` module manages the state of a 2D grid, providing a robust API for cell manipulation, row/column operations, and collision detection.
-== Specialized Instances
-The engine provides two main grid instances:
-*   `modules.grid`: The main game display area (dimensions defined in `configs`).
-*   `modules.hudGrid`: A specialized 4x4 grid used for HUD elements (e.g., "Next Piece" in Tetris).
-== API Reference
-=== Core & Utilities
-Fundamental methods for grid initialization, basic cell access, and iteration. These methods form the backbone of grid state management.
-==== `width: number`
-Read-only property returning the number of columns in the grid.
-**Returns**
-`number` - Grid width.
-'''
-==== `height: number`
-Read-only property returning the number of rows in the grid.
-**Returns**
-`number` - Grid height.
-'''
-==== `resetGrid(): void`
-Resets the entire grid to its empty state.
-**Behavior**
-Clears all cells and populates them with default empty cell objects using dimensions from the engine configuration.
-'''
-==== `getGrid(): xref:../types/Cell.adoc[Cell][][]`
-Returns the underlying 2D array of cells.
-**Returns**
-`xref:../types/Cell.adoc[Cell][][]` - The matrix representing the grid state.
-'''
-==== `forEach(callback: (cell: xref:../types/Cell.adoc[Cell]) => void): void`
-Iterates over every cell and executes the provided callback.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`callback` |`(cell: xref:../types/Cell.adoc[Cell]) => void` |Function to execute for each cell.
-|===
-'''
-==== `isValidCoordinate(coordinate: xref:../types/Coordinate.adoc[Coordinate]): boolean`
-Verifies if a coordinate is within the current grid boundaries.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |The `{x, y}` point to validate.
-|===
-**Returns**
-`boolean` - `true` if valid, `false` otherwise.
-'''
-==== `getCell(coordinate: xref:../types/Coordinate.adoc[Coordinate]): xref:../types/Cell.adoc[Cell] | null`
-Retrieves a cell at a specific coordinate.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |The `{x, y}` position to query.
-|===
-**Returns**
-`xref:../types/Cell.adoc[Cell] | null` - The cell object, or `null` if the coordinate is out of bounds.
-'''
-==== `setCellValue(coordinate: xref:../types/Coordinate.adoc[Coordinate], value: number): void`
-Updates the numeric value of a cell.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Target position.
-|`value` |`number` |New status value (0 for inactive, >0 for active).
-|===
-**Behavior**
-Updates the `value` property of the cell. If the coordinate is invalid, the operation is ignored.
-'''
-==== `setCellColor(coordinate: xref:../types/Coordinate.adoc[Coordinate], color: xref:../enums/Color.adoc[Color]): void`
-Updates the color of a cell.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Target position.
-|`color` |`xref:../enums/Color.adoc[Color]` |Enum value representing the new color.
-|===
-'''
-==== `isCellActive(coordinate: xref:../types/Coordinate.adoc[Coordinate]): boolean`
-Checks if a cell is currently occupied.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Point to check.
-|===
-**Returns**
-`boolean` - `true` if the cell value is greater than 0.
-'''
-==== `isCellInactive(coordinate: xref:../types/Coordinate.adoc[Coordinate]): boolean`
-Checks if a cell is currently empty.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinate` |`xref:../types/Coordinate.adoc[Coordinate]` |Point to check.
-|===
-**Returns**
-`boolean` - `true` if the cell value is exactly 0.
-'''
-==== `getDebugData(): Record<string, string | number | boolean>`
-Returns metadata for the real-time debugger.
-**Returns**
-`Record<string, string | number | boolean>` - Object containing `width`, `height`, and `activeCells` count.
-'''
-=== Line & Column Management
-Methods for managing entire lines (rows) or columns. These are essential for mechanics like clearing full lines in Tetris-style games or shifting grid content as a single block.
-==== `isRowFull(y: number): boolean`
-Checks if a specific row has no empty cells.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`y` |`number` |Row index to check.
-|===
-**Returns**
-`boolean` - `true` if all cells in the row are active.
-'''
-==== `isRowEmpty(y: number): boolean`
-Checks if a specific row is completely empty.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`y` |`number` |Row index to check.
-|===
-**Returns**
-`boolean` - `true` if all cells in the row are inactive.
-'''
-==== `clearRow(y: number): void`
-Resets all cells in a row to the empty state.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`y` |`number` |Row index to clear.
-|===
-'''
-==== `shiftRowsDown(fromY: number): void`
-Shifts all rows above an index down by one position.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fromY` |`number` |The row index to start shifting from.
-|===
-**Behavior**
-Moves row `y-1` to `y` for all rows up to `fromY`. The top-most row (index 0) is cleared after the shift.
-'''
-==== `shiftRowsUp(fromY: number): void`
-Shifts all rows below an index up by one position.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fromY` |`number` |The row index to start shifting from.
-|===
-**Behavior**
-Moves row `y+1` to `y` for all rows starting from `fromY` downwards. The bottom-most row is cleared after the shift.
-'''
-==== `clearFullRows(): number`
-Scans for, clears, and collapses full rows.
-**Returns**
-`number` - The total count of rows cleared.
-**Behavior**
-Iterates through all rows. If a row is full, it is cleared, and all rows above it are shifted down.
-'''
-==== `isColumnFull(x: number): boolean`
-Checks if a specific column has no empty cells.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`x` |`number` |Column index to check.
-|===
-**Returns**
-`boolean` - `true` if full.
-'''
-==== `isColumnEmpty(x: number): boolean`
-Checks if a specific column is completely empty.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`x` |`number` |Column index to check.
-|===
-**Returns**
-`boolean` - `true` if empty.
-'''
-==== `clearColumn(x: number): void`
-Resets all cells in a column to the empty state.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`x` |`number` |Column index to clear.
-|===
-'''
-==== `shiftColumnsRight(fromX: number): void`
-Shifts all columns to the right of an index.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fromX` |`number` |The column index to start shifting from.
-|===
-'''
-==== `shiftColumnsLeft(fromX: number): void`
-Shifts all columns to the left of an index.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`fromX` |`number` |The column index to start shifting from.
-|===
-'''
-==== `clearFullColumns(): number`
-Detects and clears all full columns.
-**Returns**
-`number` - The total count of cleared columns.
-'''
-=== Region & Area Management
-Operations for handling multi-cell areas, rectangular regions, and piece shapes. These methods facilitate the logical placement and validation of game objects within the grid.
-==== `isAreaOccupied(coordinates: xref:../types/Coordinate.adoc[Coordinate][]): boolean`
-Checks for collisions between a list of coordinates and active cells in the grid.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coordinates` |`xref:../types/Coordinate.adoc[Coordinate][]` |Array of `{x, y}` points representing a shape or piece.
-|===
-**Returns**
-`boolean` - `true` if any coordinate is either out of bounds or already occupied (active).
-'''
-==== `fillArea(start: xref:../types/Coordinate.adoc[Coordinate], end: xref:../types/Coordinate.adoc[Coordinate], value: number, color: xref:../enums/Color.adoc[Color]): void`
-Fills a rectangular area with specified properties.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`start` |`xref:../types/Coordinate.adoc[Coordinate]` |Top-left corner of the rectangle.
-|`end` |`xref:../types/Coordinate.adoc[Coordinate]` |Bottom-right corner of the rectangle.
-|`value` |`number` |Value to apply to all cells in the area.
-|`color` |`xref:../enums/Color.adoc[Color]` |Color to apply to all cells in the area.
-|===
-'''
-==== `stampPiece(piece: xref:../types/Piece.adoc[Piece]): void`
-Updates multiple specific coordinates simultaneously with their specific values and colors.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The collection of cells to stamp.
-|===
-'''
-==== `stampCell(cell: xref:../types/Cell.adoc[Cell]): void`
-Updates a single coordinate with a specific value and color from a Cell.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`cell` |`xref:../types/Cell.adoc[Cell]` |The cell object containing the target coordinate, value, and color.
-|===
-'''
-=== Movement & Projections
-Advanced methods for handling piece and cell movement with built-in collision detection and trajectory prediction.
-==== `movePiece(piece: xref:../types/Piece.adoc[Piece], direction: xref:../types/Vector.adoc[Vector]): xref:../types/Piece.adoc[Piece] | null`
-Attempts to shift a collection of cells (a piece) in a specified direction.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The current collection of cells.
-|`direction` |`xref:../types/Vector.adoc[Vector]` |The movement vector (e.g., `{x: -1, y: 0}`).
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece] | null` - The new piece with updated coordinates if the move is valid, or `null` if blocked.
-**Behavior**
-Validates that all new positions are within grid boundaries and are not occupied by other active cells. Cells that are already part of the input `piece` are ignored during collision detection to allow a piece to move "into its own space."
-'''
-==== `movePieceLeft(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece] | null`
-Alias for `movePiece` shifting one unit to the left.
-'''
-==== `movePieceRight(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece] | null`
-Alias for `movePiece` shifting one unit to the right.
-'''
-==== `movePieceUp(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece] | null`
-Alias for `movePiece` shifting one unit up.
-'''
-==== `movePieceDown(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece] | null`
-Alias for `movePiece` shifting one unit down.
-'''
-==== `moveCell(cell: xref:../types/Cell.adoc[Cell], direction: xref:../types/Vector.adoc[Vector]): xref:../types/Cell.adoc[Cell] | null`
-Attempts to shift a single cell in a specified direction.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`cell` |`xref:../types/Cell.adoc[Cell]` |The current cell.
-|`direction` |`xref:../types/Vector.adoc[Vector]` |The movement vector.
-|===
-**Returns**
-`xref:../types/Cell.adoc[Cell] | null` - The new cell with updated coordinate if the move is valid, or `null` if blocked.
-**Behavior**
-Validates that the target position is within grid boundaries and is currently empty (inactive).
-'''
-==== `moveCellLeft(cell: xref:../types/Cell.adoc[Cell]): xref:../types/Cell.adoc[Cell] | null`
-Alias for `moveCell` shifting one unit to the left.
-'''
-==== `moveCellRight(cell: xref:../types/Cell.adoc[Cell]): xref:../types/Cell.adoc[Cell] | null`
-Alias for `moveCell` shifting one unit to the right.
-'''
-==== `moveCellUp(cell: xref:../types/Cell.adoc[Cell]): xref:../types/Cell.adoc[Cell] | null`
-Alias for `moveCell` shifting one unit up.
-'''
-==== `moveCellDown(cell: xref:../types/Cell.adoc[Cell]): xref:../types/Cell.adoc[Cell] | null`
-Alias for `moveCell` shifting one unit down.
-'''
-==== `getDropPath(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece]`
-Calculates the final vertical resting position of a piece if it were dropped continuously downwards.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to project.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - A new piece representing the final resting position. Useful for rendering "ghost" or "preview" pieces.
-'''
-==== `getRisePath(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece]`
-Calculates the final vertical resting position of a piece if it were moved continuously upwards.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to project.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - A new piece representing the highest resting position.
-'''
-==== `getReachPathLeft(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece]`
-Calculates the final horizontal resting position of a piece if it were moved continuously to the left.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to project.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - A new piece representing the leftmost resting position.
-'''
-==== `getReachPathRight(piece: xref:../types/Piece.adoc[Piece]): xref:../types/Piece.adoc[Piece]`
-Calculates the final horizontal resting position of a piece if it were moved continuously to the right.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to project.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - A new piece representing the rightmost resting position.
-'''
-=== Transformations
-Geometric operations for rotating or mirroring complex shapes within the grid boundaries.
-==== `rotatePiece(piece: xref:../types/Piece.adoc[Piece], origin: xref:../types/Coordinate.adoc[Coordinate], clockwise: boolean = true): xref:../types/Piece.adoc[Piece] | null`
-Attempts to rotate a collection of cells 90 degrees around a specific origin point.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to rotate.
-|`origin` |`xref:../types/Coordinate.adoc[Coordinate]` |The pivot point for rotation.
-|`clockwise` |`boolean` |If true, rotates 90° clockwise; otherwise, 90° counter-clockwise.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece] | null` - The new piece if rotation is valid (no collisions), or `null` if blocked.
-'''
-==== `mirrorPiece(piece: xref:../types/Piece.adoc[Piece], axis: xref:../types/Axis.adoc[Axis]): xref:../types/Piece.adoc[Piece]`
-Mirrors a piece across its own center on a specific axis.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`piece` |`xref:../types/Piece.adoc[Piece]` |The piece to mirror.
-|`axis` |`xref:../types/Axis.adoc[Axis]` |The axis ('x' or 'y') to flip across.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - The mirrored piece.
-'''
-=== Grid Analysis
-Methods for inspecting grid state, finding patterns, and performing searches over the active cell data.
-==== `getFullRows(): number[]`
-Identifies all rows that are completely filled with active cells.
-**Returns**
-`number[]` - An array of `y` indices representing the filled rows.
-'''
-==== `getFullColumns(): number[]`
-Identifies all columns that are completely filled with active cells.
-**Returns**
-`number[]` - An array of `x` indices representing the filled columns.
-'''
-==== `getNeighbors(coord: xref:../types/Coordinate.adoc[Coordinate], includeDiagonal: boolean = false): xref:../types/Cell.adoc[Cell][]`
-Returns all active cells adjacent to a specific coordinate.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coord` |`xref:../types/Coordinate.adoc[Coordinate]` |The central coordinate.
-|`includeDiagonal` |`boolean` |If true, checks 8 neighbors; otherwise, checks the 4 cardinal neighbors.
-|===
-**Returns**
-`xref:../types/Cell.adoc[Cell][]` - List of neighboring cells found.
-'''
-==== `findConnectedCells(coord: xref:../types/Coordinate.adoc[Coordinate]): xref:../types/Piece.adoc[Piece]`
-Finds all connected active cells of the same value starting from a specific coordinate using a Breadth-First Search (BFS) algorithm.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`coord` |`xref:../types/Coordinate.adoc[Coordinate]` |The starting point for the search.
-|===
-**Returns**
-`xref:../types/Piece.adoc[Piece]` - A collection of all connected cells found.
-'''
-==== `swapCells(a: xref:../types/Coordinate.adoc[Coordinate], b: xref:../types/Coordinate.adoc[Coordinate]): void`
-Swaps the values and colors of two specified cells on the grid.
-**Parameters**
-[cols="1,1,3"]
-|===
-|Name |Type |Description
-|`a` |`xref:../types/Coordinate.adoc[Coordinate]` |First coordinate.
-|`b` |`xref:../types/Coordinate.adoc[Coordinate]` |Second coordinate.
-|===
-'''