ADR-004: Third-Party Facade Pattern
Status: Accepted Date: 2026-01-25
Context
Building every engine subsystem from scratch requires significant development time. However, third-party libraries must be evaluated on maintenance status, performance, ECS integration potential, and TypeScript support.
Decision
Use Third-Party (Facade Pattern)
| Package | Backend | Reason |
|---|---|---|
physics2d/physics3d | Rapier | WASM performance, determinism, active development |
The physics packages define abstract interfaces, and the Rapier adapter packages (physics2d-rapier, physics3d-rapier) provide the concrete implementation. This isolates the third-party dependency behind a facade.
Build Custom (ECS-Integrated)
| Package | Reason |
|---|---|
pathfinding | Parallelizable, modern algorithms (JPS, HPA*, flow fields), NavMesh |
audio | ECS spatial audio, audio occlusion, dynamic mixing |
ecs | Core architecture -- must control completely |
renderer | WebGPU-first differentiator |
netcode | Rollback tightly coupled with ECS |
Custom implementations enable:
- Cache-friendly iteration via ECS SoA data layout
- Automatic parallelization across available cores
- Tight integration with the ECS component and system model
Consequences
Positive
- Pathfinding -- Modern algorithms, parallelization, full TypeScript
- Audio -- Deep ECS integration, audio occlusion, procedural audio
- Performance -- 5-50x gains from ECS data layout and parallelization
- No stale dependencies -- Custom implementations stay current
Negative
- Development time -- Custom implementations require more effort
- Testing -- Need comprehensive test coverage for each custom system
Alternatives Considered
- PathFinding.js wrapper -- Rejected due to library being 10+ years unmaintained
- Howler.js only -- Rejected because ECS integration provides more value
- All custom -- Rejected for physics (Rapier is too good to replicate)