Collision Broad Phase
The broad phase decides which collider pairs are worth checking. Gravitas uses GridForge voxels as a spatial index. A pair can share a voxel even when its shapes are separated, so candidates still pass filters and a shape test.
Quick Read
Imagine a sphere moving across a floor. Its bounds cover cells A and B at first, then B and C. The labels stand for full world voxel identities. Gravitas updates only the changed memberships.
| Cell | Before the move | After the move | Membership update |
|---|---|---|---|
| A | Covered | Clear | Remove the sphere ID |
| B | Covered | Covered | Keep the sphere ID |
| C | Clear | Covered | Add the sphere ID |
If the sphere and floor share both B and C, the pair is routed through its first shared partition in stable order. Duplicate suppression keeps the extra shared cell from producing a second shape check. If the sphere sleeps, it remains available to queries. Only awake dynamic membership activates solver pair distribution.
Partition Owners
| Domain | Partition type | Owner service |
|---|---|---|
| 3D | PhysicsPartition |
GravitasCollisionService |
| 2D | PhysicsPartition2D |
GravitasCollision2DService |
| Mixed | PhysicsMixedPartition |
GravitasMixedCollisionService |
Partition ownership must flow through the owning service. Do not manually return the same partition through a second path; that risks double-release and stale activation state.
Membership storage is internal and grows with local collider population rather than global collider ID magnitude. Partition mutation methods maintain role, awake and retained-empty state together. Hosts can inspect role counts or copy sorted IDs into their own reusable buffers; see the migration guide for the removed mutable fields and inspection replacements.
Movement traces exact new voxel coverage. Shared memberships survive unchanged; departed memberships are removed in their prior coordinate order, and new memberships follow tracer order. Mobility changes replace the old role even in shared voxels. Geometry/bounds versions still advance when membership is unchanged, so queries and support caches see shape changes normally. Coverage comparison uses full world voxel identities, including grid spawn tokens.
3D Partitioning
Update Coverage
When a collider initializes, moves, rotates, changes scale, or changes local
shape inputs, LSCollider rebuilds runtime shape data and asks
GravitasCollisionService to repartition it. Shape inputs are tracked by an
internal snapshot so several local edits before a simulation call collapse into
one bounds/shape rebuild.
Prepared canonical geometry, analytical conservative bounds, and mass properties commit atomically. Bounds clipped to the representable coordinate domain exist only for partition coverage; narrow phase always consumes the canonical shape.
GravitasCollisionService.PartitionObject(...):
- validates that the collider belongs to the service context.
- asks GridForge
GridTracer.GetCoveredVoxelsInto(...)for topology-aware voxel coverage. - uses GridForge traversal state and topology metrics for conservative voxel-position padding.
- suppresses duplicate voxel visits with GridForge traversal helpers and context-local sets.
- checks that the voxel position falls within collider bounds.
- rents or reuses a
PhysicsPartitionon the voxel. - stores the collider's
WorldVoxelIndex. - adds the collider ID to the partition mobility bucket.
Reuse Empty Partitions
When a collider leaves a voxel, Gravitas removes the collider ID from the
partition but keeps the empty PhysicsPartition attached to that voxel. Empty
partitions are inactive and query-invisible. PhysicsSettings
RetainedPartitionTimeToKillFrames controls the deterministic retention window,
and RetainedPartitionRetirementSweepBudget bounds how many retained partitions
the collision service checks per distribution step.
An explicit dense list tracks eligible empty payloads. If the inactive pool is empty, rental detaches the last dense eligible entry in constant time; occupied registration does not search all retained payloads. Reoccupation and release remove eligibility immediately. Expiry keeps its bounded retained-list sweep. These cache reuse rules apply to pure 2D, 3D and mixed partitions; collision/query ordering still uses sorted spatial identities and collider IDs.
GravitasWorldContext.Reset() is a stronger session boundary: it detaches
retained Gravitas partition payloads from GridForge voxels, clears retained
tracking, and clears partition pools. The collider registry can reuse IDs
within a session. A reset starts a fresh context-local allocation sequence.
2D Partitioning
PhysicsPartition2D mirrors the same ID-first model for 2D. LSCollider2D
rebuilds its FixedBoundArea, then GravitasCollision2DService maps X/Z bounds
into GridForge voxels on the internal Y=0 storage plane.
That Y=0 plane is broad-phase identity only. It is not physical thickness and
does not imply mixed collision. Mixed collision uses separate embedded 2D slab
state owned by LSCollider2D and GravitasMixedCollisionService.
2D partitions retain and retire empty payloads through the same deterministic TTK settings and return them to the 2D collision service's pool.
Mixed Partitioning
Mixed mode uses PhysicsMixedPartition payloads attached to GridForge voxels.
The service refreshes mixed 3D and 2D membership after 3D and 2D body
integration. Embedded 2D membership uses LSCollider2D.MixedBounds3D: 2D X/Z
bounds plus a positive Y half-thickness centered on the host transform's Y
position.
Mixed candidate links are dimension-tagged. Plain 2D and 3D collider IDs are not comparable because the services intentionally own separate ID spaces.
Mobility Buckets
Membership is explicit:
| Collider or body state | Partition bucket |
|---|---|
| Bodyless collider | static |
PhysicsMobilityType.Static |
static |
PhysicsMobilityType.Kinematic |
kinematic |
PhysicsMobilityType.Dynamic |
dynamic |
| Awake dynamic body with solver mobility | dynamic plus awake-dynamic |
Freeze axes never change the partition role. Partial freezes and fully locked dynamic bodies remain in dynamic membership; the solver constrains their degrees of freedom through effective mass and inertia. A fully locked dynamic body does not seed awake pair distribution because it has no solver mobility, but it remains available to contacts, queries, wake propagation, and an awake counterpart's candidate traversal.
Only awake dynamic membership activates pair distribution for solver work. Sleeping bodies remain in normal dynamic membership so queries, wake propagation, pair cleanup, and contact lifecycle retain access to them.
Active Partitions And Pair Distribution
An active partition is one with awake dynamic members. Active partitions emit candidate pairs against local static, kinematic, dynamic, and awake-dynamic members according to the owning service's rules.
Candidate generation must be deterministic:
- voxel and partition traversal order is explicit.
- collider ID ordering is explicit.
- pair keys are stable.
- duplicate-pair suppression is applied before narrow phase.
- retained sleeping pairs can keep contact state without forcing fresh narrow phase every frame.
If every dynamic body in a partition is sleeping, pair generation is skipped until a deterministic wake reason changes a body or collider shape state.
Pure 2D candidate routing rejects disjoint bounds before physical-pair admission and canonical shared-partition ownership. Bounds-accepted pairs still pass the full physical filters. Three-dimensional retained-pair culling has a different lifecycle boundary; do not assume the same rejection order applies there.
Pair Filters
Candidate pairs are rejected before exact shape work when any required filter fails:
| Filter | Notes |
|---|---|
| Context | Colliders must belong to the same context. |
| Active state | Inactive colliders do not produce pairs. |
| Same agent | Host-owned same-agent collisions are suppressed. |
| Explicit hierarchy | Parent/child and sibling filters use dimension-tagged hierarchy keys. |
| Collision matrix | Context-wide physical layer matrix must allow the pair. |
| Collider-local ignored layers | Either collider can reject the other collider's layer. |
| Trigger policy | Bodyless trigger volumes skip physical response and emit trigger events only when exactly one collider is a trigger and the other collider is body-owned. |
| Bounds | Broad bounds must overlap before narrow phase. |
| Awake/resting policy | Sleeping/sleeping fresh links exit; retained resting links can keep island state. |
Collider-local ignored layer masks affect collision pairs, trigger pairs, internal CCD target eligibility, and grounding/support acceptance. Public query services use caller-owned include masks instead.
Duplicate Suppression
One broad collider can cover many voxels. Gravitas suppresses duplicate work in two layers:
- Voxel traversal suppresses duplicate voxel visits while collecting coverage or query candidates.
- Pair routing sends a broad collider pair through its deterministic first shared partition before the frame duplicate-pair set.
This keeps multi-voxel colliders from generating repeated narrow-phase work or repeated contact notifications.
Pair Culling
New 3D discrete pairs require inclusive overlap of the current collider bounds. Exact touching remains eligible for narrow phase. Retained pairs still run through their normal update and retirement paths so separation and exit notifications can reach both endpoints.
Pair culling may delay checks only for non-colliding retained pairs according to stable distance, velocity, age, and size scores. It must not skip active contacts or nearby candidate pairs because a host considers an object less important.
Authoritative collision detection is not asynchronous. Hosts may run independent contexts on separate threads, but one context's collision and response phases must keep stable observable order.
Large Scene Policy
Large object counts are handled through deterministic broad-phase and solver ownership:
- GridForge-backed voxel partitioning.
- retained
PhysicsPartition,PhysicsPartition2D, andPhysicsMixedPartitionpayloads. - mobility buckets and awake-dynamic sets.
- duplicate pair suppression.
- hierarchy, layer, and local physical filtering.
- retained collision pairs and warm-start caches.
- deterministic sleep state.
- CCD frame caches and bounded handoff queues.
Collision LOD is authored data, not camera-distance runtime mutation. A host or offline tool may choose simpler fixed collision shapes for a simulation, but Gravitas does not change authoritative collision geometry during a run based on renderer distance or presentation priority.
Deactivation Cleanup
LSCollider.Deactivate():
- clears partition membership through the owning collision service.
- removes owned collision-pair references.
- removes holder references from opposite colliders.
- clears explicit parent binding.
- deactivates and pools pairs when pooling is enabled.
- unregisters the collider ID from the context-local physics service.
- marks the collider inactive.
2D and mixed cleanup follow the same ownership principle through their owning services.