physics2d

physics2d

Box2D v3–backed 2D physics plugin for Cardinal, powered by the pure-Go Box2D port in pkg/box2d. All simulation state lives in the plugin instance's engine world; Cardinal drives it through three ECS components attached to the entities you want simulated.

Regenerating the wire code

The wire.gen.go files are generated by world sdk generate. From the world-engine repo root:

world sdk generate ./pkg/plugin/physics2d \
  --go-out ./pkg/plugin/physics2d/gen

Requires Docker (the generator runs protoc/buf in a container). Rerun after changing any command/component/event struct in this plugin.

--proto-out ./pkg/plugin/physics2d/proto is optional. The generator compiles the schema in a temp dir, so nothing in the build reads a persisted copy. Add the flag when you want to read the wire contract directly — what a field became, or whether a type fell back to opaque JSON.

Registration:

w, err := cardinal.NewWorld(cardinal.WorldOptions{TickRate: 60})
if err != nil {
    panic(err)
}
physics := physics2d.NewPlugin(physics2d.Config{
    Gravity:      physics2d.Vec2{X: 0, Y: -9.8},
    TickRate:     60, // match WorldOptions.TickRate
    SubStepCount: 4,
})
w.RegisterPlugin(physics)
w.StartGame()

RegisterPlugin registers the physics components and the plugin's Init and PreUpdate systems. Systems in one hook run in registration order, so a game system that must run before the plugin's (for example an Init spawner whose bodies the first rebuild should see) is registered before RegisterPlugin. That order needs no extra step for components: a system resolves its archetypes on its first Contains, Exact, or Create call inside Run, not when it is registered, and every Register* call panics once the world has started.

w.RegisterSystem(&spawnBodiesSystem{}, cardinal.WithHook(cardinal.Init))
w.RegisterPlugin(physics)

Only code that creates physics entities before RegisterPlugin runs (a test harness seeding a scene) needs the components earlier. Call physics2d.RegisterComponents(w) first; RegisterPlugin registering them again is a no-op.

Keep the *physics2d.Plugin value: queries, Engine, and Reset are methods on it. All simulation state belongs to that instance — the package holds no globals, and multiple plugin instances in one process simulate fully independently.

Enrolling an entity into physics

An entity participates in the simulation when it carries all three of these components. Missing any one → the reconciler skips the entity and no body is created in the engine.

Use the NewPhysicsBody2D constructor — bare struct literals leave Active, Awake, SleepingAllowed at false and GravityScale at 0, which produces an inactive, sleeping, gravity-less body.

Example: a dynamic circle

import (
    "github.com/argus-labs/world-engine/pkg/cardinal"
    "github.com/argus-labs/world-engine/pkg/plugin/physics2d"
)

func SpawnBallSystem(ctx cardinal.WorldContext) error {
    id, err := cardinal.Create(ctx,
        physics2d.Transform2D{
            Position: physics2d.Vec2{X: 0, Y: 10},
            Rotation: 0,
        },
        physics2d.Velocity2D{
            Linear:  physics2d.Vec2{X: 0, Y: 0},
            Angular: 0,
        },
        physics2d.NewPhysicsBody2D(
            physics2d.BodyTypeDynamic,
            physics2d.ColliderShape{
                ShapeType:    physics2d.ShapeTypeCircle,
                Radius:       0.5,
                Density:      1.0,
                Friction:     0.3,
                Restitution:  0.2,
                CategoryBits: 0x0001,
                MaskBits:     0xFFFF,
            },
        ),
    )
    _ = id
    return err
}

Example: a static box (world geometry)

cardinal.Create(ctx,
    physics2d.Transform2D{Position: physics2d.Vec2{X: 0, Y: 0}},
    physics2d.Velocity2D{},
    physics2d.NewPhysicsBody2D(
        physics2d.BodyTypeStatic,
        physics2d.ColliderShape{
            ShapeType:    physics2d.ShapeTypeBox,
            HalfExtents:  physics2d.Vec2{X: 25, Y: 1},
            Friction:     0.5,
            CategoryBits: 0x0002,
            MaskBits:     0xFFFF,
        },
    ),
)

Body-type cheat sheet

• BodyTypeStatic — immovable world geometry. No writeback.
• BodyTypeDynamic — full simulation: forces, gravity, collisions. Writeback updates Transform2D/Velocity2D each tick.
• BodyTypeKinematic — velocity-driven; Box2D integrates position. Writeback on.
• BodyTypeManual — gameplay owns position/velocity; Box2D is used only for contact detection. No writeback; the reconciler pushes ECS → Box2D each tick. Use for characters/enemies driven by input or AI.

Compound colliders

PhysicsBody2D.Shapes is an immutable.Slice — each entry is a child fixture with its own LocalOffset, LocalRotation, material, and filter. Shape identity is by index (slot i in Shapes ↔ fixture slot i), so don't reorder shapes after creation if you care about per-shape references in contact events.

Read it with Len, At, and All; change it with Append, With, Without and friends, then Set the component. Those derivations edit the array the component already holds, so a Set after each one is required rather than tidy — see immutable.Slice.

pb := entity.Get[physics2d.PhysicsBody2D]()
sh := pb.Shapes.At(0)
sh.Friction = 0.9
pb.Shapes = pb.Shapes.With(0, sh)
entity.Set(pb)

Polygon vertices

A convex polygon's vertices live in a fixed [MaxPolygonVertices]Vec2 array with VertexCount saying how many slots are live — the same shape box2d.Polygon uses, and the same bound (8) Box2D compiles in. Build one with WithVertices, which sets the count and zeroes the unused tail:

tri := physics2d.ColliderShape{
    ShapeType:    physics2d.ShapeTypeConvexPolygon,
    Density:      1,
    Friction:     0.4,
    CategoryBits: 0xFFFF,
    MaskBits:     0xFFFF,
}.WithVertices(
    physics2d.Vec2{X: 0, Y: 0},
    physics2d.Vec2{X: 2, Y: 0},
    physics2d.Vec2{X: 1, Y: 1.5},
)

Past MaxPolygonVertices, WithVertices returns a shape that fails Validate (vertex_count: must be between 0 and 8) rather than truncating or panicking — an over-long polygon is a bad asset, and the reconciler refuses the fixture the same way it refuses any other bad geometry. PolygonVertices() reads back the live prefix. A chain has no such bound, so ChainPoints is an immutable.Slice[Vec2]; build one with immutable.SliceOf(pts...).

Built-in queries

Use these first; they cover most needs:

• (*physics2d.Plugin).Raycast(RaycastRequest) RaycastResult
• (*physics2d.Plugin).OverlapAABB(AABBOverlapRequest) AABBOverlapResult
• (*physics2d.Plugin).CircleSweep(CircleSweepRequest) CircleSweepResult

All three return zero results when no engine world exists yet (e.g. before the first reconcile, or right after Plugin.Reset).

Custom read-only queries via Engine()

If you need to read something the built-in queries don't cover (shape casts, custom query filters, sensor-only overlap, contact walks, body/shape inspection, debug draw), call the pure-Go engine directly. (*physics2d.Plugin).Engine() returns the underlying *box2d.World, or nil when no world exists (before the first PreUpdate reconcile and after Plugin.Reset).

Engine() is a read-only escape hatch, not an extension point. The reconciler owns body and shape lifecycle and derives it from the ECS components every tick, so engine-side mutations do not survive: changes to solver-owned state (transform, velocity, shape geometry, filters, body flags) are overwritten on the next reconcile, and bodies/shapes/joints you create directly on the engine are untracked and are destroyed by any rebuild (Plugin.Reset, snapshot restore, or a structural component change). Make changes that must persist through the ECS components instead.

Entity → engine object lookup

Engine() alone gives you a world with no way back to your entities. Two lookups close that gap:

• (*physics2d.Plugin).BodyID(cardinal.EntityID) (box2d.BodyID, bool)
• (*physics2d.Plugin).ShapeIDs(cardinal.EntityID) ([]box2d.ShapeID, bool)

Both return ok == false when no world exists or the entity has no body yet. ShapeIDs is indexed by collider slot (slot i ↔ PhysicsBody2D.Shapes[i]) and returns a copy you own. The ids are valid only until the next tick's reconcile, which may destroy and recreate the body — look them up again each tick rather than caching them.

// Read the solver's mass and per-shape contact state for one entity.
func InspectMass(physics *physics2d.Plugin, id cardinal.EntityID) (float64, bool) {
    w := physics.Engine()
    if w == nil {
        return 0, false // no world yet: before init or after Plugin.Reset
    }
    bodyID, ok := physics.BodyID(id)
    if !ok {
        return 0, false // entity has no body this tick
    }
    return w.BodyMass(bodyID), true
}

// Does any of this entity's shapes contain the point? (query, not mutation)
func ContainsPoint(physics *physics2d.Plugin, id cardinal.EntityID, p box2d.Vec2) bool {
    w := physics.Engine()
    if w == nil {
        return false
    }
    shapeIDs, ok := physics.ShapeIDs(id)
    if !ok {
        return false
    }
    for _, shapeID := range shapeIDs {
        if w.ShapeTestPoint(shapeID, p) {
            return true
        }
    }
    return false
}

Userdata encoding

The plugin stuffs identity into Box2D userdata (see internal/create.go):

• Body userdata = entity ID: cardinal.EntityID(uint32(w.BodyUserData(bodyID))).
• Shape userdata = shape slot index (the index into PhysicsBody2D.Shapes): int(uint32(w.ShapeUserData(shapeID))).

So inside any engine callback you can recover the ECS entity with one line.

Example: custom AABB overlap that returns every hit, including sensors

package myphysics

import (
    "github.com/argus-labs/world-engine/pkg/box2d"
    "github.com/argus-labs/world-engine/pkg/cardinal"
    "github.com/argus-labs/world-engine/pkg/plugin/physics2d"
)

func OverlapAll(physics *physics2d.Plugin, minX, minY, maxX, maxY float64) []cardinal.EntityID {
    w := physics.Engine()
    if w == nil {
        return nil // no world yet: before init or after Plugin.Reset
    }
    var out []cardinal.EntityID
    aabb := box2d.AABB{
        LowerBound: box2d.Vec2{X: minX, Y: minY},
        UpperBound: box2d.Vec2{X: maxX, Y: maxY},
    }
    w.OverlapAABB(aabb, box2d.DefaultQueryFilter(), func(shapeID box2d.ShapeID, _ any) bool {
        bodyID := w.ShapeBody(shapeID)
        out = append(out, cardinal.EntityID(uint32(w.BodyUserData(bodyID))))
        return true // keep going
    }, nil)
    return out
}

Rules of engagement

• Always nil-check Engine() — it returns nil before the first PreUpdate reconcile and after Plugin.Reset. Treat nil as "no world, skip the query."
• Reads and queries only. Raycasts, overlaps, shape casts, sensor iteration, contact walks, body/shape getters — safe any time after you've confirmed Engine() != nil.
• Mutation is not supported. SetBodyTransform / DestroyBody / shape setters bypass the plugin's ECS shadow copy and are overwritten on the next reconcile. Write the ECS components instead; the reconciler pushes them to Box2D before each step.
• Engine-created objects are not tracked. Bodies, shapes, or joints you create directly on the engine are invisible to ECS and are destroyed by any rebuild — Plugin.Reset, snapshot restore, or a structural component change.
• Don't cache the world pointer or ids across ticks. Engine(), BodyID, and ShapeIDs are cheap; call them at the top of each query. After Plugin.Reset (e.g. snapshot restore) the old pointer refers to a destroyed world, and reconcile can recreate a body under a new id.

Contact events

Contacts and triggers flow through Cardinal's system-event bus. The plugin's own pipeline system sets the emitter each tick and flushes ContactBeginEvent / ContactEndEvent / TriggerBeginEvent / TriggerEndEvent each tick. The events carry both entity IDs and both shape indices, so you can look up the exact ColliderShape that produced the contact.