GridCollisionManager

GridCollisionManager is a singleton that manages a 2D tile-based collision grid backed by an Int32Array. It provides O(1) cell lookups, neighbor queries, and world-to-grid coordinate conversion.

Unlike CollisionManager, GridCollisionManager is not auto-mounted by Game. You create and manage it via useGridCollision.

tsx
import { getGridCollisionManager } from "@carverjs/core/systems";

How It Works #

  1. Call useGridCollision with a GridCollisionConfig to create the grid.

  2. The hook initializes a flat Int32Array of width * height cells.

  3. Use setCell / getCell / isCellOccupied to read/write cell values.

  4. On unmount, the grid is destroyed.

Cell values: 0 = empty, positive integers = occupied by type (you define the meaning).

API #

getGridCollisionManager() #

Returns the singleton instance. Creates one if it doesn't exist.

destroyGridCollisionManager() #

Destroys the singleton and frees the grid memory. Called automatically when the useGridCollision hook unmounts.

Usage #

Most game code should use useGridCollision instead of accessing the manager directly.

tsx
import { getGridCollisionManager } from "@carverjs/core/systems";

const mgr = getGridCollisionManager();
mgr.setCell(5, 5, 1);
const occupied = mgr.isCellOccupied(5, 5); // true

Type Definitions #

See Types for GridCollisionConfig and GridCellCallback.