NSGo Game

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
	},
}
编辑此页