physics3d
import "github.com/nsgo-dev/game/packages/game/physics3d"
纯 Go 实现的紧凑、确定性 3D 碰撞检测、射线检测、刚体动力学与运动学角色控制器。
架构决策(#180)
physics3d 采用方案 (a):仅依赖 Go 标准库的零 cgo 纯 Go 实现。
选择纯 Go 而不封装 C/C++ 物理引擎(如 Jolt、Bullet 或 PhysX)的原因:
- 全平台开箱即用:macOS、Windows、Linux、iOS、Android 和 WebAssembly 都可以用普通的
go build/go tool nsgo check直接编译,不需要 C/C++ 工具链、各平台静态库或 Wasm/FFI 胶水代码。 - 零 FFI 开销:重叠查询、射线检测、刚体步进和角色移动直接在 Go 值上运行,没有 cgo 调用边界成本。
- 按位一致的确定性:配合
game.Loop的固定步长推进World,宽相、窄相、冲量求解和位置修正都按固定的刚体与接触顺序执行,不依赖 map 遍历顺序或墙钟时间,相同的初始状态在多次运行中产生完全一致的轨迹。
包的能力范围保持克制和清晰:轴对齐包围盒(Box)、球体(Sphere)和胶囊体(Capsule)、精确的重叠与射线查询、平动刚体求解,以及胶囊角色控制器。完整三角网格碰撞、关节约束和旋转惯性张量不在初始包的范围内。
坐标系约定
physics3d 采用右手、Y 轴向上的坐标系(+X 向右,+Y 向上,+Z 朝向观察者)。NewWorld() 将默认重力设为 (0, -9.81, 0)。
形状、重叠查询与射线检测
三种基本形状通过带标签的 Shape 封装(BoxShape、SphereShape、CapsuleShape):
Box:由Center和HalfExtents定义的轴对齐包围盒(也可用BoxFromMinMax(min, max)构造)。Sphere:由Center和Radius定义的球体。Capsule:由线段A到B沿半径Radius扫略而成的胶囊体(也可用VerticalCapsule(center, radius, height)构造竖直胶囊)。
重叠检测返回 Contact,其中单位法线 Normal 从 B 指向 A(将 A 沿 Normal 移动 Depth 即可分离两者):
TestBoxBox、TestSphereSphere、TestCapsuleCapsule、TestBoxSphere、TestBoxCapsule、TestSphereCapsule以及TestShapes(a, b)。world.QueryOverlap(shape)按确定的插入顺序返回所有重叠的刚体。
射线检测支持对单个形状测试 Ray{Origin, Dir, MaxDist}(RaycastBox、RaycastSphere、RaycastCapsule、RaycastShape),以及对整个世界发射线段(world.Raycast(from, to) 和 world.RaycastFirst(from, to)),返回按 [0, 1] 范围内的 T 升序排列的 RaycastHit,包含世界坐标命中点 Point、距离 Distance 和向外单位法线 Normal。
刚体动力学
World 管理静态(Static: true 或零质量)和动态 Body,在 Step(dt) 中通过半隐式欧拉积分、确定性碰撞检测、带热启动和三维各向同性库仑摩擦的迭代冲量求解器、非线性高斯-赛德尔位置修正以及静止休眠机制推进模拟。
world := physics3d.NewWorld()
world.AddBody(physics3d.NewStaticBody(
physics3d.BoxShape(physics3d.Box{HalfExtents: physics3d.Vec3{X: 20, Y: 1, Z: 20}}),
physics3d.Vec3{Y: -1},
))
crate := world.AddBody(physics3d.NewDynamicBody(
physics3d.BoxShape(physics3d.Box{HalfExtents: physics3d.Vec3{X: 0.5, Y: 0.5, Z: 0.5}}),
physics3d.Vec3{Y: 3},
1.0,
))
loop := &game.Loop{
Update: func(dt time.Duration) {
world.Step(dt)
_ = crate.Pos
},
}
角色控制器
CharacterController 通过 Move(world, wishMove, dt) 在 World 中移动一个运动学胶囊(Pos 为脚底位置,尺寸为 Radius 和 Height):
- 在平地上行走,并在不超过
MaxSlopeAngle(默认 45°)的斜坡上平滑上下滑行,下坡时保持贴地。 - 阻止攀爬超过
MaxSlopeAngle的陡坡,并在重力作用下沿陡坡滑落。 - 在验证头顶净空、水平前进增益和可站立踏面后,自动迈上不超过
StepHeight的台阶。 - 遇到竖直墙面时干净停止,斜向撞墙时沿墙面切向滑行而不穿透。
cc := physics3d.NewCharacterController(physics3d.Vec3{Y: 0}, 0.3, 1.8)
loop := &game.Loop{
Update: func(dt time.Duration) {
res := cc.Move(world, physics3d.Vec3{X: 3.5}, dt)
_ = res.Pos
},
}