brick-engine-js 1.0.1

package/docs/reference/modules/GameGrid.adoc

@@ -0,0 +1,794 @@
+= 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.
+|===
+
+
+'''