| name | threejs-collision-patterns |
| description | Collision detection patterns for Three.js games without physics engines |
| prerequisites | ["Three.js imported","Game loop with delta time"] |
| tags | ["threejs","collision","physics","game","hitbox"] |
Three.js Collision Patterns
Manual collision detection for Three.js games. No physics engine required — uses simple geometric tests each frame.
When To Use This Skill
Use this when a project needs:
- Collidable walls, obstacles, or furniture (AABB)
- Tapered static obstacles such as mountains, spires, or cones
- Projectile hit detection against entities (sphere)
- Collectible/power-up pickup zones (distance)
- Arena boundaries that block movement
Read Order
- This file (overview + integration checklist)
- patterns/aabb-box-collider.md — static obstacles
- patterns/sphere-distance-collider.md — pickups & projectiles
- patterns/boundary-and-projectile.md — arena edges & bullet-vs-wall
Core Principle
Every collidable game object consists of two parts:
- Visual mesh — what the player sees (can be complex geometry)
- Collision primitive — simple shape used for hit tests (box or sphere)
The collision primitive is registered at mesh creation time and tested each frame in the game loop.
Integration Checklist
When implementing collision in a new game:
- Define entity radius in Constants.js (e.g.,
PLAYER: { COLLISION_RADIUS: 1.65 }).
- Choose pattern based on shape:
- Box-shaped static objects → AABB (Pattern 1 or 2)
- Tapered static obstacles → height-aware radial collider
- Moving entities vs walls → Box3 intersection (Pattern 2)
- Projectiles/pickups → Sphere distance (Pattern 3)
- Arena edges → Boundary clamp (Pattern 4)
- Register colliders at mesh creation time (not retroactively).
- Test in game loop every frame, BEFORE applying movement.
- Label obstacles for debugging.
- Use
collidable: false for visual-only decoration meshes.
- Keep collision shapes simple — enclosing boxes/spheres, not complex mesh geometry.
Anti-Patterns (DO NOT)
- Do NOT use raycasting for simple AABB collision (expensive, unnecessary).
- Do NOT add physics engine deps (cannon.js, rapier, ammo.js) unless explicitly requested.
- Do NOT make collision radius exactly match mesh size — add 10-20% padding for game feel.
- Do NOT use a full-height AABB for obviously tapered obstacles like mountains if mid-air false positives matter.
- Do NOT skip collision on decorative meshes silently — explicitly mark
collidable: false.
- Do NOT test collision AFTER applying movement (causes entities stuck inside walls).
- Do NOT allocate new Vector3/Box3 objects inside the collision loop (GC pressure) — reuse temporaries.
Preflight Checklist
