ADR-005: Collision Detection Strategy
Status: Accepted Date: 2026-01-26
Context
The project had a standalone @web-engine-dev/collision package providing broad-phase and narrow-phase collision detection. However, ADR-004 established Rapier as the chosen physics backend, and Rapier provides all the same collision functionality plus more.
This created functional redundancy between the custom collision package and Rapier.
Decision
Remove the standalone collision package and rely on Rapier's collision detection through the physics packages.
| Aspect | Custom Collision | Rapier |
|---|---|---|
| Performance | JavaScript | Rust/WASM (10-100x faster) |
| Shapes | 4 basic shapes | 6+ shapes including trimesh |
| Determinism | Not guaranteed | Cross-platform deterministic |
| Maintenance | Custom code to maintain | Maintained by Dimforge |
| Integration | Standalone | Integrated with physics |
Migration Path
| Previous API | Replacement |
|---|---|
SpatialHashBroadPhase | Rapier's broad-phase (automatic) |
NarrowPhase | Rapier's narrow-phase (automatic) |
CircleShape, AABBShape, etc. | Rapier's Ball, Cuboid, etc. |
TriggerZone | Rapier's sensors with collision events |
CollisionWorld.raycast() | PhysicsWorld.raycast() |
CollisionWorld.queryAABB() | Rapier's intersection queries |
Consequences
Positive
- No redundant code to maintain
- Better performance via Rapier's WASM implementation
- More features (CCD, shape-casting, convex hulls, trimesh)
- Determinism for netcode rollback
- Simpler architecture -- one collision system, not two
Negative
- WASM dependency for collision-only use cases
- Larger bundle size if only collision is needed (Rapier is ~300KB gzipped)
- Loss of lightweight option for simple games
Mitigations
- The
spatialpackage can handle simple AABB queries without Rapier - Rapier can be used in collision-only mode (kinematic bodies, no dynamics)
Alternatives Considered
- Keep both -- Rejected: creates confusion and doubles maintenance
- Make collision a Rapier facade -- Rejected:
physics2d/physics3dalready serve this role - Keep collision for lightweight use -- Deferred: may revisit if there is demand for WASM-free collision