feat: physics2d component setup

Author: AnthonyWadham

pkg/plugin/physics2d/component/active_contacts.go

@@ -0,0 +1,33 @@
+package component
+
+// PhysicsSingletonTag marks the single entity that holds physics plugin state (ActiveContacts).
+type PhysicsSingletonTag struct{}
+
+func (PhysicsSingletonTag) Name() string { return "physics_singleton_tag" }
+
+// ContactPairEntry is one active contact pair tracked by the physics engine. Entries are
+// normalized: EntityA < EntityB (or if equal, ShapeIndexA <= ShapeIndexB).
+type ContactPairEntry struct {
+	EntityA     uint64 `json:"a"`
+	ShapeIndexA int    `json:"sa"`
+	EntityB     uint64 `json:"b"`
+	ShapeIndexB int    `json:"sb"`
+	IsSensor    bool   `json:"sensor"`
+	// Fixture filters for normalized EntityA/B (recovery End / trigger vs contact routing).
+	// Omitempty keeps older snapshots valid.
+	FilterACategoryBits uint16 `json:"fa_cat,omitempty"`
+	FilterAMaskBits     uint16 `json:"fa_mask,omitempty"`
+	FilterAGroupIndex   int16  `json:"fa_grp,omitempty"`
+	FilterBCategoryBits uint16 `json:"fb_cat,omitempty"`
+	FilterBMaskBits     uint16 `json:"fb_mask,omitempty"`
+	FilterBGroupIndex   int16  `json:"fb_grp,omitempty"`
+}
+
+// ActiveContacts persists which contact pairs have had Begin emitted (and not yet End).
+// After a rebuild, the physics step diffs this against Box2D's live contact list to emit
+// correct Begin/End events without duplicates or missed ends.
+type ActiveContacts struct {
+	Pairs []ContactPairEntry `json:"pairs"`
+}
+
+func (ActiveContacts) Name() string { return "active_contacts" }

pkg/plugin/physics2d/component/collider.go

@@ -0,0 +1,126 @@
+package component
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ShapeType selects which geometry fields in ColliderShape are valid.
+//
+// Callers must set ShapeType consistently with the populated geometry fields.
+// Box2D validates geometry internally (convexity, vertex count, welding) and will panic
+// on invalid input. This is caught during development.
+type ShapeType uint8
+
+const (
+	// ShapeTypeCircle uses Radius; fixture is a circle in the shape's local frame.
+	ShapeTypeCircle ShapeType = iota + 1
+	// ShapeTypeBox uses HalfExtents (half-width, half-height) for an axis-aligned box in the
+	// shape's local frame before applying LocalOffset/LocalRotation.
+	ShapeTypeBox
+	// ShapeTypeConvexPolygon uses Vertices as a convex polygon in the shape's local frame.
+	ShapeTypeConvexPolygon
+	// ShapeTypeStaticChain uses ChainPoints for open chain segments (static or kinematic
+	// bodies only; not for dynamic bodies which require mass).
+	ShapeTypeStaticChain
+	// ShapeTypeStaticChainLoop uses ChainPoints for closed chain loops (static or kinematic
+	// bodies only; not for dynamic bodies). Unlike ShapeTypeStaticChain, the last vertex
+	// automatically connects back to the first, creating a sealed boundary.
+	ShapeTypeStaticChainLoop
+	// ShapeTypeEdge uses EdgeVertices (exactly 2 points) for a single line segment
+	// (static or kinematic bodies only). Lighter than a 2-point chain for isolated barriers
+	// or triggers.
+	ShapeTypeEdge
+	// ShapeTypeCapsule uses CapsuleCenter1, CapsuleCenter2, and Radius; fixture is a capsule
+	// (two semicircles connected by a rectangle) in the shape's local frame.
+	ShapeTypeCapsule
+)
+
+// ColliderShape is one child shape inside a compound PhysicsBody2D.
+//
+// Each entry has its own local transform, sensor flag, material, and collision filter (category, mask, group).
+// Geometry fields are a tagged-union style: only the fields that match ShapeType are used.
+//   - ShapeTypeCircle → Radius
+//   - ShapeTypeBox → HalfExtents (half-width on X, half-height on Y, axis-aligned before LocalOffset/LocalRotation)
+//   - ShapeTypeConvexPolygon → Vertices (convex polygon, respect backend limits)
+//   - ShapeTypeStaticChain → ChainPoints (open polyline in local space)
+//   - ShapeTypeStaticChainLoop → ChainPoints (closed loop in local space)
+//   - ShapeTypeEdge → EdgeVertices (exactly 2 points in local space)
+//   - ShapeTypeCapsule → CapsuleCenter1, CapsuleCenter2, Radius (two semicircles connected by a rectangle)
+type ColliderShape struct {
+	ShapeType     ShapeType `json:"shape_type"`
+	LocalOffset   Vec2      `json:"local_offset"`
+	LocalRotation float64   `json:"local_rotation"`
+	IsSensor      bool      `json:"is_sensor"`
+
+	// Geometry (use fields matching ShapeType).
+	Radius       float64 `json:"radius,omitempty"`
+	HalfExtents  Vec2    `json:"half_extents,omitempty"`
+	Vertices     []Vec2  `json:"vertices,omitempty"`
+	ChainPoints  []Vec2  `json:"chain_points,omitempty"`
+	EdgeVertices   [2]Vec2 `json:"edge_vertices,omitempty"`
+	CapsuleCenter1 Vec2    `json:"capsule_center1,omitempty"`
+	CapsuleCenter2 Vec2    `json:"capsule_center2,omitempty"`
+
+	// Material and per-shape collision filtering (fixture-level in Box2D).
+	Friction     float64 `json:"friction"`
+	Restitution  float64 `json:"restitution"`
+	Density      float64 `json:"density"`
+	CategoryBits uint16  `json:"category_bits"`
+	MaskBits     uint16  `json:"mask_bits"`
+	GroupIndex   int16   `json:"group_index,omitempty"`
+}
+
+// Validate checks for NaN/Inf in all float fields and a valid ShapeType tag.
+func (s ColliderShape) Validate() error {
+	if err := validateVec2("local_offset", s.LocalOffset); err != nil {
+		return err
+	}
+	if !isFinite(s.LocalRotation) {
+		return errors.New("local_rotation: must be finite")
+	}
+	if !isFinite(s.Friction) {
+		return fmt.Errorf("friction: must be finite, got %v", s.Friction)
+	}
+	if !isFinite(s.Restitution) {
+		return fmt.Errorf("restitution: must be finite, got %v", s.Restitution)
+	}
+	if !isFinite(s.Density) {
+		return fmt.Errorf("density: must be finite, got %v", s.Density)
+	}
+	if !isFinite(s.Radius) {
+		return fmt.Errorf("radius: must be finite, got %v", s.Radius)
+	}
+	if err := validateVec2("half_extents", s.HalfExtents); err != nil {
+		return err
+	}
+	for i, v := range s.Vertices {
+		if err := validateVec2(fmt.Sprintf("vertices[%d]", i), v); err != nil {
+			return err
+		}
+	}
+	for i, v := range s.ChainPoints {
+		if err := validateVec2(fmt.Sprintf("chain_points[%d]", i), v); err != nil {
+			return err
+		}
+	}
+	for i, v := range s.EdgeVertices {
+		if err := validateVec2(fmt.Sprintf("edge_vertices[%d]", i), v); err != nil {
+			return err
+		}
+	}
+	if err := validateVec2("capsule_center1", s.CapsuleCenter1); err != nil {
+		return err
+	}
+	if err := validateVec2("capsule_center2", s.CapsuleCenter2); err != nil {
+		return err
+	}
+
+	switch s.ShapeType {
+	case ShapeTypeCircle, ShapeTypeBox, ShapeTypeConvexPolygon, ShapeTypeStaticChain,
+		ShapeTypeStaticChainLoop, ShapeTypeEdge, ShapeTypeCapsule:
+	default:
+		return fmt.Errorf("shape_type: unknown value %d", s.ShapeType)
+	}
+	return nil
+}

pkg/plugin/physics2d/component/physics_body.go

@@ -0,0 +1,166 @@
+//nolint:recvcheck // UnmarshalJSON must be pointer receiver to support json.Unmarshal
+package component
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/goccy/go-json"
+)
+
+// PhysicsBody2D holds simulation parameters for a rigid body and its collider shapes.
+//
+// BodyType selects static vs dynamic vs kinematic behavior. LinearDamping and AngularDamping
+// are simulation damping coefficients. GravityScale multiplies the world's gravity vector
+// for this body; world gravity itself is runtime configuration, not a component field.
+//
+// # Body flags
+//
+// Active controls whether the body participates in the simulation at all. An inactive body
+// has no contacts, no collisions, and is effectively removed from Box2D without destroying it.
+// Set Active=false to temporarily disable an entity's physics (e.g. a dormant trap).
+//
+// Awake controls whether the body is currently awake in the simulation. Setting Awake=true
+// wakes a sleeping body; Box2D may put it back to sleep on subsequent ticks if nothing
+// disturbs it and SleepingAllowed is true.
+//
+// SleepingAllowed controls whether Box2D is permitted to put the body to sleep when it comes
+// to rest. When false, the body stays awake indefinitely.
+//
+// Note: Box2D v3 processes sensors in a separate overlap pass that runs regardless of body
+// sleep state (only disabled bodies are skipped). Sensor contacts are not affected by sleeping.
+//
+// Bullet enables continuous collision detection (CCD) for fast-moving dynamic bodies to
+// prevent tunneling through thin geometry. Has a performance cost; only enable for
+// projectiles or similarly fast objects.
+//
+// FixedRotation prevents the body from rotating in response to torques or collisions.
+// Useful for top-down characters that should not spin.
+//
+// # Shapes
+//
+// Shapes holds the compound collider description. Cardinal allows one instance per component
+// type per entity, so compound colliders are modeled as multiple ColliderShape entries.
+// Shape identity (v1): index i in Shapes identifies fixture slot i.
+//
+// # Defaults
+//
+// Box2D defaults Active, Awake, and SleepingAllowed to true and GravityScale to 1. Use
+// [NewPhysicsBody2D] to create a PhysicsBody2D with these defaults set correctly. Bare struct
+// literals leave bool fields at false and GravityScale at 0, which produces an inactive,
+// sleeping body with no gravity — almost never what you want.
+//
+// When deserializing from JSON (e.g. snapshot recovery), missing fields are defaulted to
+// their Box2D values automatically via a custom UnmarshalJSON. Explicitly serialized false
+// values are preserved exactly.
+//
+// Bullet and FixedRotation default to false (off), matching Box2D defaults.
+//
+// # Post-step writeback
+//
+// Writeback applies to dynamic and kinematic bodies. Static and manual bodies are
+// not written back.
+type PhysicsBody2D struct {
+	BodyType        BodyType `json:"body_type"`
+	LinearDamping   float64  `json:"linear_damping"`
+	AngularDamping  float64  `json:"angular_damping"`
+	GravityScale    float64  `json:"gravity_scale"`
+	Active          bool     `json:"active"`
+	Awake           bool     `json:"awake"`
+	SleepingAllowed bool     `json:"sleeping_allowed"`
+	Bullet          bool     `json:"bullet"`
+	FixedRotation   bool     `json:"fixed_rotation"`
+
+	Shapes []ColliderShape `json:"shapes"`
+}
+
+// NewPhysicsBody2D returns a PhysicsBody2D with the given body type, Box2D-compatible defaults
+// (Active=true, Awake=true, SleepingAllowed=true, GravityScale=1), and the provided shapes.
+func NewPhysicsBody2D(bodyType BodyType, shapes ...ColliderShape) PhysicsBody2D {
+	return PhysicsBody2D{
+		BodyType:        bodyType,
+		GravityScale:    1,
+		Active:          true,
+		Awake:           true,
+		SleepingAllowed: true,
+		Shapes:          shapes,
+	}
+}
+
+// UnmarshalJSON decodes a PhysicsBody2D from JSON, applying Box2D-compatible defaults for
+// fields missing from the payload. This handles old snapshots that predate the body flags
+// (Active, Awake, SleepingAllowed default to true; GravityScale defaults to 1) while
+// preserving explicitly serialized values including false.
+func (p *PhysicsBody2D) UnmarshalJSON(data []byte) error {
+	type raw struct {
+		BodyType        BodyType        `json:"body_type"`
+		LinearDamping   float64         `json:"linear_damping"`
+		AngularDamping  float64         `json:"angular_damping"`
+		GravityScale    *float64        `json:"gravity_scale"`
+		Active          *bool           `json:"active"`
+		Awake           *bool           `json:"awake"`
+		SleepingAllowed *bool           `json:"sleeping_allowed"`
+		Bullet          bool            `json:"bullet"`
+		FixedRotation   bool            `json:"fixed_rotation"`
+		Shapes          []ColliderShape `json:"shapes"`
+	}
+	var aux raw
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+	*p = PhysicsBody2D{
+		BodyType:        aux.BodyType,
+		LinearDamping:   aux.LinearDamping,
+		AngularDamping:  aux.AngularDamping,
+		GravityScale:    1,
+		Active:          true,
+		Awake:           true,
+		SleepingAllowed: true,
+		Bullet:          aux.Bullet,
+		FixedRotation:   aux.FixedRotation,
+		Shapes:          aux.Shapes,
+	}
+	if aux.GravityScale != nil {
+		p.GravityScale = *aux.GravityScale
+	}
+	if aux.Active != nil {
+		p.Active = *aux.Active
+	}
+	if aux.Awake != nil {
+		p.Awake = *aux.Awake
+	}
+	if aux.SleepingAllowed != nil {
+		p.SleepingAllowed = *aux.SleepingAllowed
+	}
+	return nil
+}
+
+// Name returns the ECS component name.
+func (PhysicsBody2D) Name() string { return "physics_body_2d" }
+
+// Validate guards against NaN/Inf in float fields, an invalid body type tag, and invalid shapes.
+func (p PhysicsBody2D) Validate() error {
+	switch p.BodyType {
+	case BodyTypeStatic, BodyTypeDynamic, BodyTypeKinematic, BodyTypeManual:
+	default:
+		return fmt.Errorf("physics_body_2d.body_type: invalid value %d", p.BodyType)
+	}
+	if !isFinite(p.LinearDamping) {
+		return fmt.Errorf("physics_body_2d.linear_damping: must be finite, got %v", p.LinearDamping)
+	}
+	if !isFinite(p.AngularDamping) {
+		return fmt.Errorf("physics_body_2d.angular_damping: must be finite, got %v", p.AngularDamping)
+	}
+	if !isFinite(p.GravityScale) {
+		return fmt.Errorf("physics_body_2d.gravity_scale: must be finite, got %v", p.GravityScale)
+	}
+	if len(p.Shapes) == 0 {
+		return errors.New("physics_body_2d.shapes: at least one ColliderShape is required")
+	}
+	for i := range p.Shapes {
+		if err := p.Shapes[i].Validate(); err != nil {
+			return fmt.Errorf("physics_body_2d.shapes[%d]: %w", i, err)
+		}
+	}
+	return nil
+}

pkg/plugin/physics2d/component/rigidbody.go

@@ -0,0 +1,24 @@
+package component
+
+// BodyType selects how the rigid body participates in the simulation.
+type BodyType uint8
+
+const (
+	// BodyTypeStatic is immovable world geometry; zero velocity; does not respond to forces.
+	BodyTypeStatic BodyType = iota + 1
+	// BodyTypeDynamic is fully simulated: forces, collisions, and integration apply.
+	BodyTypeDynamic
+	// BodyTypeKinematic is moved by setting velocity from gameplay; Box2D integrates velocity
+	// into position each step. Does not respond to forces but can push dynamic bodies on
+	// contact. Post-step writeback keeps ECS in sync with Box2D's integrated position.
+	BodyTypeKinematic
+	// BodyTypeManual is for gameplay-driven entities that use Box2D only for contact detection.
+	// Under the hood it creates a kinematic body, but post-step writeback is skipped: ECS owns
+	// position and velocity, and the reconciler pushes ECS values into Box2D each tick.
+	// Use this for characters, enemies, and other entities where gameplay code (input handling,
+	// AI, pathfinding) computes position directly.
+	//
+	// Box2D collision rules apply: manual bodies generate contacts with dynamic bodies only,
+	// not with static or other kinematic/manual bodies.
+	BodyTypeManual
+)