feat: add Box2D physics2d plugin with CGO

[AnthonyWadham]

Add 2D Physics Plugin with Box2D Integration

This pull request introduces a comprehensive 2D physics plugin for Cardinal using Box2D as the simulation backend.

Components

• Transform2D: World-space position and rotation
• Velocity2D: Linear and angular velocity
• Rigidbody2D: Body type (static/dynamic/kinematic) and simulation parameters
• Collider2D: Compound collider with multiple shapes (circle, box, polygon, chain)
• ActiveContacts: Singleton component tracking active contact pairs for event deduplication

Core Systems

• InitPhysicsSystem: Creates Box2D world and performs initial ECS→Box2D rebuild
• ReconcilePhysicsSystem: Incrementally syncs ECS changes to Box2D using shadow-copy diffing
• PhysicsStepSystem: Steps the simulation and emits contact/trigger events

Contact Events

• ContactBeginEvent/ContactEndEvent: Non-sensor collision events
• TriggerBeginEvent/TriggerEndEvent: Sensor overlap events
• Proper event deduplication after world rebuilds using persisted contact state

Query API

• Raycast: Cast rays through the physics world
• OverlapAABB: Find fixtures overlapping an axis-aligned bounding box
• CircleSweep: Sweep a circle along a path for continuous collision detection

Runtime Management

• Shadow-copy reconciliation for efficient incremental updates
• Structural vs mutable change detection (fixture recreation vs in-place updates)
• Deterministic rebuild ordering and contact event handling
• Proper cleanup of orphaned bodies and contact pairs

The plugin integrates seamlessly with Cardinal's ECS architecture while providing a complete 2D physics simulation with collision detection, rigid body dynamics, and comprehensive query capabilities.

[AnthonyWadham]

• feat: add Box2D physics2d plugin with CGO #880 : 2 dependent PRs (#882 , #883 ) 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label graphite/merge to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[darkmavis]

As was just disccussed, I'm fine with accepting that for a change with this level of complexity, we simply need to merge and test in the real-world. I'd be shocked if we didn't encounter issues, but that's ok. We'll find out what they are and fix them.

In some ways, this carries less risk than the initial decision to use an unofficial port of Box2D from C to Go, and for that, we had to real-world test and find out if it was stable and deterministic, and what to avoid if anything. We did and it worked. We can do the same here, but with more confidence that we're picking up the latest changes and nothing in the core library was lost in translation.

fwiw - I reviewed code with help from Claude. The gameplay test footage is enough of a sanity check for me. I'm not expecting perfection, and if we get it, great.

Also stoked for the performance and stability improvements provided by v3. Thanks for thinking to do this and making it happen.

I'm fine with having this merged in once Ryan's requested changes are resolved.