internal

func AttachColliderFixtures ¶

func AttachColliderFixtures(entityID cardinal.EntityID, shapes []component.ColliderShape) error

AttachColliderFixtures creates one shape per ColliderShape on the C-side body identified by entityID. shapeIndex is the slice index i in shapes. Local offsets and rotations are applied so geometry defined in shape space is placed correctly in body space.

func ColliderShapeMutableFieldsEqual ¶

func ColliderShapeMutableFieldsEqual(a, b component.ColliderShape) bool

ColliderShapeMutableFieldsEqual compares per-shape fields that Box2D can update without recreating the fixture shape.

func CreateBody ¶

func CreateBody(
	entityID cardinal.EntityID,
	transform component.Transform2D,
	velocity component.Velocity2D,
	pb component.PhysicsBody2D,
) error

CreateBody creates a body on the C-side Box2D world via cbridge. It does not attach shapes; use AttachColliderFixtures next.

func CreateBodyWithCollider ¶

func CreateBodyWithCollider(
	entityID cardinal.EntityID,
	transform component.Transform2D,
	velocity component.Velocity2D,
	pb component.PhysicsBody2D,
) error

CreateBodyWithCollider creates a body and attaches all shapes. If shape attachment fails, the body is destroyed and an error is returned.

func FlushBufferedContacts ¶

func FlushBufferedContacts()

FlushBufferedContacts turns buffered contact records into physics2d events via the runtime emitter, then clears the buffer and nils Emitter.

On normal ticks, every Begin adds to rt.ActiveContacts and every End removes from it. After applying the step buffer, sustained overlaps are refreshed from the live contact list so IsSensor and filter bits stay aligned if a shape toggles sensor/solid or filters change while the pair remains touching.

On the first step after a rebuild (SuppressContactsStep was true), the buffer is empty because the listener suppressed callbacks. Instead, we diff rt.ActiveContacts (loaded from the persisted ECS component) against the live contact list:

• Pairs in live but not in the map -> emit Begin, add to map
• Pairs in the map but not in live -> emit End, remove from map
• Pairs in both -> no event (game already knows)

If NoPersistedActiveContactsBaseline is set (missing singleton on a suppressed step), the suppressed flush adopts live contacts into the map without emitting events so one-shot Begin handlers do not all fire spuriously; the flag is cleared.

func FullRebuildFromECS ¶

func FullRebuildFromECS(gravity component.Vec2, entries []PhysicsRebuildEntry) error

FullRebuildFromECS replaces all derived physics state for the package Runtime in one deterministic pass: destroys every body in the C-side world, clears maps and contact buffer, optionally applies gravity, recreates bodies/shapes from entries, then writes shadow snapshots. Entries are sorted by EntityID before processing; creation order follows that sort.

Requires ResetRuntime (or prior init) so Runtime() is non-nil. World is created on first rebuild using gravity; later rebuilds reuse the world and call SetGravity.

On any creation error, bodies created in this pass are destroyed and runtime maps are left empty (same as post-clear); the world remains allocated with no bodies.

After a successful rebuild, Emitter is cleared and SuppressContactsStep is set true for the next simulation step. The step driver must call SetStepEmitter before the step and FlushBufferedContacts after; that flush clears SuppressContactsStep automatically.

func ReconcileFromECS ¶

func ReconcileFromECS(entries []PhysicsRebuildEntry) error

ReconcileFromECS incrementally syncs the C-side Box2D world from authoritative ECS entries using shadow-copy diffing. It is the hot-path counterpart to FullRebuildFromECS.

Structural vs mutable changes:

• Structural: anything that changes shape identity -- shape count/order, per-shape type, local offset/rotation, or geometry (radius, half-extents, vertices, chain points). Handled by destroying all shapes on the body and re-attaching from ECS.

• Mutable: body transform, linear/angular velocity, body type/damping/gravity scale, and per-shape sensor, friction, restitution, density, and filter category/mask/group. Applied in place without recreating shapes.

Requires non-nil Runtime() with a live C-side world (for example after an initial FullRebuildFromECS). Entries are sorted by EntityID; duplicate IDs are an error. Entities absent from entries are removed from the runtime (body destroyed, shadow dropped).

ReconcileFromECS does not touch SuppressContactsStep or Emitter; it does not step the world.

func ResetRuntime ¶

func ResetRuntime()

ResetRuntime replaces the package runtime with a fresh PhysicsRuntime. If a C-side world exists, it is destroyed first.

func SetBufferedContactsFromStep ¶

func SetBufferedContactsFromStep(events []cbridge.ContactEvent)

SetBufferedContactsFromStep converts cbridge.ContactEvent results from Step into BufferedContactEvents and stores them in rt.BufferedContacts for the next flush. Called by the pipeline between cbridge.Step and FlushBufferedContacts.

func SetStepEmitter ¶

func SetStepEmitter(emitter event.ContactEventEmitter)

SetStepEmitter stores the contact event sink for the upcoming simulation step. The step driver should set this before the step and call FlushBufferedContacts after the step.

func ShapesStructuralEqual ¶

func ShapesStructuralEqual(a, b []component.ColliderShape) bool

ShapesStructuralEqual reports whether two shape slices match for Box2D fixture shape definition: shape count/order (topology) and, per index, shape type, local transform, and geometry. Differences confined to sensor flag, friction, restitution, density, or filter (category, mask, group) are not structural and can be applied with fixture setters.

func WritebackFromStepResults ¶

func WritebackFromStepResults(states []cbridge.BodyState, entries []WritebackEntry)

WritebackFromStepResults reads post-step positions, rotations, and velocities from the cbridge.Step body states and writes them into the corresponding ECS Transform2D and Velocity2D components. It also updates the shadow state so the next ReconcileFromECS tick sees no diff for these values.

Writeback applies to dynamic and kinematic bodies only. Static bodies (BodyType==1) never move. Manual bodies (ECS BodyTypeManual==4) are skipped because ECS/gameplay code owns their position. Since both BodyTypeKinematic and BodyTypeManual map to Box2D kinematic bodies, the ECS body type is checked rather than the bridge body type.