| name | threejs-game-physics-collision |
| description | Design a collision and physics layer for a three.js game, including character movement, collision layers, scene queries, and engine-adapter boundaries. Use when gameplay needs robust contact, blocking, triggers, or rigid-body behavior. |
Goal
为 three.js 游戏建立碰撞与物理层的正确边界，区分“世界碰撞”“角色控制”“刚体模拟”“查询系统”和“游戏判定”。
Use this skill when
- 你要给角色加地面碰撞、墙体阻挡、台阶、坡面、跳跃
- 你要引入完整物理引擎或设计一个轻量碰撞层
- 你要统一射线、重叠、触发器和物理世界查询
- 你要避免把玩法逻辑和物理实现绑死
Required inputs
- 游戏类型：FPS / platformer / sandbox / driving / physics puzzler
- 是否需要完整刚体
- 是否需要网络同步 / 回放 / 快照
- 世界是否静态为主
- 是否已有碰撞代理体资源
Outputs
- PhysicsAdapter
- 碰撞层矩阵
- 角色控制器方案
- 查询 API 约定
- 引擎选型建议
Standards
- 不把 three.js mesh 直接当物理世界唯一真相
- 可视 mesh 与碰撞代理体可以不同
- 角色控制器、刚体模拟、trigger 查询要分开建模
- 玩法系统通过适配层调用物理，不直接深绑底层引擎 API
Workflow
1. 先选路线
静态世界 + 角色移动为主
可优先：
需要完整刚体、character controller、scene queries、快照
优先：
只是轻量原型
可接受：
2. 建立碰撞层矩阵
至少定义：
- player
- enemy
- world-static
- world-dynamic
- trigger
- projectile
- pickup
- ui-proxy / debug
输出矩阵必须明确谁与谁碰撞、谁与谁只重叠不阻挡。
3. 角色控制器
必须明确：
- 水平移动
- 重力
- 落地检测
- 台阶
- 坡面
- 墙滑
- 跳跃窗口 / coyote time（如果玩法需要）
- moving platform 规则（如果玩法需要）
4. 查询系统
统一封装：
- raycast
- shape cast / sweep
- overlap
- ground probe
- line of sight
不要让玩法代码直接到处调用底层引擎实例。
5. 同步与快照边界
如果项目需要多人或回放，要提前说明：
- 哪些对象是物理驱动
- 哪些对象是逻辑驱动
- 是否需要 deterministic 或近似 deterministic 方案
- 是否要用物理世界 snapshot
Required checks
- 是否建立 PhysicsAdapter
- 是否给角色控制器写清楚行为规则
- 是否定义碰撞层矩阵
- 是否区分可视 mesh 和碰撞代理体
- 是否统一物理查询 API
Common pitfalls
- 拿渲染 mesh 直接做所有碰撞
- 角色控制器与刚体混在一套不清不楚的逻辑里
- 没有碰撞层矩阵，后期弹丸、拾取物、触发器冲突混乱
- 先写了大量玩法判定，后面才发现没有稳定地面检测
- 网络需求出现后才想起物理世界无法快照
Deliverable template
- 引擎路线选择
- 碰撞层矩阵
- 角色控制器规则
- 查询接口设计
- 同步 / 回放风险说明
Official references
- three.js docs/examples: Octree, games_fps
- Rapier docs: character controller, scene queries, serialization
- cannon-es docs
- three-mesh-bvh docs for accelerated queries
