CollisionManager

CollisionManager is a singleton that runs AABB, sphere, and circle overlap detection each frame. It uses a spatial hash for broad-phase culling and supports layer/mask filtering.

It is mounted automatically by Game via the internal CollisionFlush system (priority -25). You do not need to set it up manually.

import { getCollisionManager } from "@carverjs/core/systems";

How It Works #

1. Each component calls useCollision to register a collider with a shape, layer, and callbacks.

2. Every frame at priority -25 (after fixedUpdate, before update), CollisionFlush calls tick().

3. tick() runs:

   • Broad phase — inserts all colliders into a spatial hash grid and extracts candidate pairs.

   • Layer filtering — skips pairs where (layerA & maskB) === 0 || (layerB & maskA) === 0.

   • Narrow phase — tests AABB-AABB, sphere-sphere, and AABB-sphere overlaps.

   • Event dispatch — fires onCollisionEnter, onCollisionStay, and onCollisionExit callbacks.

Supported Shape Pairs #

All tests are 2D-aware — in "2d" mode, the Z axis is ignored.

API #

getCollisionManager() #

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

destroyCollisionManager() #

Destroys the singleton. Called automatically when Game unmounts.

Usage #

Most game code should use useCollision instead of accessing CollisionManager directly. Direct access is useful for systems-level code:

import { getCollisionManager } from "@carverjs/core/systems";

// Check if two named colliders overlap
const mgr = getCollisionManager();
const overlaps = mgr.getOverlaps(colliderId);

Type Definitions #

See Types for ColliderDef, ColliderShape, CollisionEvent, and CollisionCallback.