2D Rigid Bodies & Joints Architecture
This document records the design decision for 2D rigid-body dynamics in github.com/nsgo-dev/game/packages/game/physics (#320, #321, #322).
Decision
Implement a lightweight, pure-Go, deterministic 2D rigid-body and constraint solver (RigidWorld, RigidBody, and Joint types) directly inside packages/game/physics, rather than binding a C/C++ physics engine (such as Box2D or Chipmunk2D) via cgo or taking on an external Go dependency.
Rationale
- Zero cgo and zero third-party dependencies: NSGo games target macOS, iOS, Windows, Linux, Android, and Web (WASM). Wrapping Box2D or Chipmunk via cgo adds C/C++ cross-compilation toolchains, platform-specific static libraries, and WASM bridging complexity. A pure-Go solver builds identically on every target with standard
go tool nsgo. - Determinism on fixed steps:
game.Loopsteps gameplay at a fixeddt. Keeping the solver free of map iteration, background threads, and platform-specific C math libraries ensures identical inputs produce repeatable simulation trajectories across runs and targets. - Unified coordinate system and types:
RigidBodyreusesShape(BoxandCircle),LayerMask, and NSGo's screen-space coordinates (+X right, +Y down, clockwise radians) directly, avoiding translation layers between kinematic physics, queries, sprites, and rigid bodies. - Right-sized for 2D games: Most 2D NSGo games need arcade dynamics—falling crates, stacks, projectiles, ragdolls, pendulums, ropes, and spring suspensions—rather than a full industrial CAD or continuous-collision solver.
Solver Design
- Integration: Symplectic (semi-implicit) Euler. Forces, gravity, and linear/angular damping update velocities first; the constraint solver corrects velocities; updated velocities then advance positions and angles.
- Contact generation: Deterministic
i < jbody pair ordering withLayerMaskfiltering and rotated AABB culling. Narrow-phase handles Circle–Circle, Circle–OBB, and OBB–OBB (2D SAT with Sutherland–Hodgman clipping to produce up to 2 contact points so flat box stacks remain stable). - Velocity resolution: Sequential impulse solver (
RigidWorld.SolverIterations, defaulting to 10) with accumulated normal and Coulomb friction clamping and a velocity threshold on restitution to prevent micro-bouncing in resting stacks. - Positional correction: Direct linear projection with slop (
0.01) after position integration, resolving residual overlap without injecting artificial bounce velocity. - Joints:
DistanceJoint: fixed-length rod constraint with optionalStiffnessand XPBDCompliance.SpringJoint: damped Hooke's law spring using unconditionally stable implicit impulse integration.RevoluteJoint: 2-DOF pin/hinge constraint using a 2×2 effective-mass block matrix to keep local anchors coincident while allowing free rotation.
Trade-offs & Scope
- Supported shapes: oriented
BoxandCircle. Arbitrary concave polygons and swept continuous collision detection (CCD) are intentionally out of scope for the built-in solver. - Scale: Designed for tens to low hundreds of active rigid bodies per scene; games requiring large-scale multi-thousand-body simulations can integrate a dedicated physics engine alongside
packages/game.
Example
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)
},
}