2D 刚体与关节架构说明
本文档记录 github.com/nsgo-dev/game/packages/game/physics 中 2D 刚体动力学的架构决策(#320、#321、#322)。
决策
直接在 packages/game/physics 内实现轻量级、纯 Go、确定性的 2D 刚体与约束求解器(RigidWorld、RigidBody 与 Joint 类型),而不是通过 cgo 绑定 C/C++ 物理引擎(如 Box2D、Chipmunk2D)或引入第三方 Go 依赖。
原因
- 零 cgo、零第三方依赖:NSGo 游戏需要同时面向 macOS、iOS、Windows、Linux、Android 和 Web(WASM)。通过 cgo 封装 Box2D 或 Chipmunk 会带来复杂的 C/C++ 交叉编译工具链、各平台静态库及 WASM 桥接成本。纯 Go 求解器可以用标准的
go tool nsgo在所有目标平台上一致构建。 - 固定步长下的确定性:
game.Loop以固定步长dt推进游戏逻辑。求解器不依赖 map 遍历、后台协程或平台相关的 C 数学库,保证相同输入在每次运行和不同目标上都能复现一致的模拟轨迹。 - 统一的坐标系与类型:
RigidBody直接复用Shape(Box和Circle)、LayerMask以及 NSGo 的屏幕坐标系(X 向右、Y 向下、角度为顺时针弧度),避免运动学碰撞、空间查询、精灵绘制和刚体之间反复做坐标或类型转换。 - 贴合 2D 游戏规模:绝大多数 2D NSGo 游戏需要的是玩法级动力学——箱子堆叠、掉落物、摆锤、弹簧悬挂、布娃娃和机关谜题——而不是工业级 CAD 或重型连续碰撞求解器。
求解器设计
- 积分方式:辛欧拉(半隐式欧拉)积分。先将重力、外力与阻尼积分到速度,再由约束求解器修正速度,最后用修正后的速度更新位置与角度。
- 接触生成:按确定性的
i < j刚体配对顺序执行,结合LayerMask过滤与旋转包围盒(AABB)粗筛。窄相检测支持圆–圆、圆–旋转矩形(OBB)和 OBB–OBB(基于 2D SAT 与 Sutherland–Hodgman 裁切生成最多 2 个接触点,确保堆叠的矩形稳定不晃动)。 - 速度求解:顺序冲量(Sequential Impulse)求解器(
RigidWorld.SolverIterations,默认 10 次迭代),支持累计法向与库仑摩擦冲量钳位,并对弹性恢复设置速度阈值,防止静止堆叠出现微幅弹跳。 - 位置修正:在位置积分后执行带容差(slop =
0.01)的直接线性位置投影,消除残余穿透而不额外注入虚假反弹速度。 - 关节约束:
DistanceJoint:定长杆约束,支持可选的Stiffness与 XPBDCompliance柔度参数。SpringJoint:胡克定律阻尼弹簧,采用无条件稳定的隐式冲量积分。RevoluteJoint:二自由度铰链/销钉约束,通过 2×2 有效质量块矩阵使两个局部锚点在世界空间重合,同时允许自由旋转。
取舍与适用范围
- 支持的形状:旋转
Box与Circle。任意凹多边形与扫掠连续碰撞检测(CCD)不在内置求解器范围内。 - 规模:面向单场景数十至数百个活跃刚体;若游戏需要数千刚体的大规模物理模拟,可在
packages/game之外按需集成专用引擎。
示例
var rw physics.RigidWorld
rw.GravityY = 600
floor := physics.NewStaticRigidBox(160, 220, 320, 20)
crate := physics.NewRigidBox(160, 100, 32, 32, 1)
pendulum := physics.NewRigidCircle(240, 140, 12, 1)
pivot := physics.NewStaticRigidBox(240, 60, 8, 8)
rw.AddBody(floor, crate, pendulum, pivot)
rw.AddJoint(physics.NewDistanceJoint(pivot, pendulum, core.Point{}, core.Point{}, 80))
loop := &game.Loop{
Rate: 60,
Update: func(dt time.Duration) {
rw.Step(dt)
},
}