physics

type GPUBody struct {
	Position        [4]float32  // offset   0: world-space center of mass (xyz), w unused       — §29.1.1 Eq. 3
	Quaternion      [4]float32  // offset  16: orientation quaternion (xyzw)                     — §29.1.2 Eq. 8
	LinearMomentum  [4]float32  // offset  32: linear momentum (xyz), w unused                  — §29.1.1 Eq. 1
	AngularMomentum [4]float32  // offset  48: angular momentum (xyz), w unused                 — §29.1.2 Eq. 4
	InvInertiaTBody [12]float32 // offset  64: body-space inverse inertia tensor (mat3x3<f32>)  — §29.1.2 Eq. 6
	InverseMass     float32     // offset 112: 1/mass (0 for static bodies)                    — §29.1.1 Eq. 2
	ParticleStart   uint32      // offset 116: start index into the global particle buffer      — §29.2.2
	ParticleCount   uint32      // offset 120: number of particles belonging to this body       — §29.2.2
	Flags           uint32      // offset 124: bit-packed: active (bit 0), static (1), kinematic (2)
	ExternalForce   [4]float32  // offset 128: CPU-uploaded force for this frame (xyz), w unused
	ExternalTorque  [4]float32  // offset 144: CPU-uploaded torque for this frame (xyz), w unused
}

type GPUGridCell struct {
	Indices0 [4]uint32 // offset  0: slots  0-3  particle indices (0xFFFFFFFF = empty) — §29.2.4
	Indices1 [4]uint32 // offset 16: slots  4-7  particle indices (0xFFFFFFFF = empty)
	Indices2 [4]uint32 // offset 32: slots  8-11 particle indices (0xFFFFFFFF = empty)
	Indices3 [4]uint32 // offset 48: slots 12-15 particle indices (0xFFFFFFFF = empty)
}

type GPUGridParams struct {
	GridOrigin [4]float32 // offset  0: world-space grid origin (xyz), w unused  — §29.1.4 Eq. 9
	GridDims   [4]uint32  // offset 16: grid dimensions (x, y, z), w = total cell count — §29.2.2
}

type GPUParticle struct {
	WorldPosition [4]float32 // offset  0: current world-space position (xyz), w unused              — §29.2.3 Eq. 19
	Velocity      [4]float32 // offset 16: current velocity (xyz), w unused                          — §29.2.3 Eq. 20
	RelPosition   [4]float32 // offset 32: current relative position to body center (xyz), w unused  — §29.2.3 Eq. 18
	Force         [4]float32 // offset 48: accumulated collision force (xyz), w unused                — §29.2.5 Eqs. 10–12
	LocalPosition [4]float32 // offset 64: body-local rest position (xyz), w = bitcast<f32>(bodyIndex) — §29.2.3
	SurfaceNormal [4]float32 // offset 80: outward surface normal (xyz), w = 1.0 if valid (static)  — Fix A
}

type GPUPhysicsGlobals struct {
	DeltaTime        float32       // offset  0: simulation timestep in seconds                         — Eqs. 1, 3, 4, 7–8
	ParticleDiameter float32       // offset  4: diameter of all particles (2 × radius)                 — §29.1.4
	SpringCoeff      float32       // offset  8: DEM spring coefficient k                               — §29.1.5 Eq. 10
	DampingCoeff     float32       // offset 12: DEM damping coefficient η                              — §29.1.5 Eq. 11
	ShearCoeff       float32       // offset 16: DEM tangential friction coefficient μ_t                — §29.1.5 Eq. 12
	BodyCount        uint32        // offset 20: number of active rigid bodies
	ParticleCount    uint32        // offset 24: total particle count across all bodies
	MaxGridCells     uint32        // offset 28: maximum total grid cells (x*y*z cap for AABB reduction)
	BoundaryCount    uint32        // offset 32: number of active boundary planes (0–6)
	GravityX         float32       // offset 36: gravitational acceleration X component (m/s²)
	GravityY         float32       // offset 40: gravitational acceleration Y component (m/s²)
	GravityZ         float32       // offset 44: gravitational acceleration Z component (m/s²)
	BoundaryPlanes   [6][4]float32 // offset  48: up to 6 half-plane definitions (normal.xyz, d)
	BoundaryYRanges  [6][4]float32 // offset 144: per-plane Y activation range (y_min, y_max, 0, 0)
}

type Particle struct {
	LocalPosition [3]float32
	SurfaceNormal [3]float32
	BodyIndex     uint32
	BoneIndex     uint32
}

type Physics interface {
	// Enabled returns whether the physics system is active. It becomes true when
	// at least one body is registered and false when all bodies are removed.
	//
	// Returns:
	//   - bool: true if physics simulation is active
	Enabled() bool

	// BodiesCount returns the number of body slots currently allocated (including
	// slots on the free list that have been deactivated but not yet reclaimed).
	//
	// Returns:
	//   - int: the total number of allocated body slots
	BodiesCount() int

	// ParticleCount returns the total number of particles across all registered bodies.
	//
	// Returns:
	//   - int: the total particle count
	ParticleCount() int

	// Buffers returns the primary BindGroupProvider that owns the physics storage
	// buffers (bodies at binding 0, particles at binding 1, etc.).
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the physics buffer provider
	Buffers() bind_group_provider.BindGroupProvider

	// Bgp returns the BindGroupProvider associated with the given compute stage key
	// (e.g. "collision", "integrate", "grid_insert").
	//
	// Parameters:
	//   - key: the stage identifier
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider for the requested stage, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of compute-stage BindGroupProviders keyed by stage name.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all compute-stage providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// PipelineKey returns the compute pipeline cache key for the given stage name.
	//
	// Parameters:
	//   - key: the stage identifier
	//
	// Returns:
	//   - string: the pipeline cache key associated with the stage
	PipelineKey(key string) string

	// MaxBodies returns the upper limit of rigid bodies the system can hold.
	//
	// Returns:
	//   - uint32: the maximum body count
	MaxBodies() uint32

	// MaxParticles returns the upper limit of particles across all bodies.
	//
	// Returns:
	//   - uint32: the maximum particle count
	MaxParticles() uint32

	// MaxGridCells returns the upper limit of spatial grid cells (x*y*z cap).
	//
	// Returns:
	//   - uint32: the maximum grid cell count
	MaxGridCells() uint32

	// SetPipelineKey associates a compute pipeline cache key with the given stage name.
	//
	// Parameters:
	//   - name: the stage identifier
	//   - key: the pipeline cache key to store
	SetPipelineKey(name, key string)

	// RegisterBody registers a rigid body in the physics system, uploading its GPU
	// data (body struct, particles, sync mapping) via staged buffer writes. If a
	// previously freed slot exists it is reused; otherwise a new slot is allocated.
	//
	// Parameters:
	//   - objID: the unique game-object identifier used for lookup
	//   - position: world-space spawn position (XYZ)
	//   - rotation: Euler rotation angles in radians (XYZ)
	//   - rb: the RigidBody carrying mass, particles, and physics properties
	//   - instanceID: the Animator instance ID written to the sync map
	//
	// Returns:
	//   - int: the body slot index assigned to this registration
	RegisterBody(objID uint64, position, rotation [3]float32, rb RigidBody, instanceID uint32) int

	// RemoveBody deactivates a body by zeroing its GPU flags and inverse mass,
	// and returns the body slot to the free list for reuse by future registrations.
	//
	// Parameters:
	//   - objID: the unique game-object identifier to remove
	RemoveBody(objID uint64)

	// BodyIndex returns the GPU body buffer slot index for the given object ID.
	//
	// Parameters:
	//   - objID: the unique object identifier
	//
	// Returns:
	//   - int: the zero-based body slot index
	//   - bool: true if the object was found
	BodyIndex(objID uint64) (int, bool)

	// BodyParticleInfo returns the particle start index and count for a given body slot.
	//
	// Parameters:
	//   - bodyIndex: the body slot index returned by RegisterBody
	//
	// Returns:
	//   - start: the first particle index in the global particle buffer
	//   - count: the number of particles belonging to this body
	BodyParticleInfo(bodyIndex int) (start, count uint32)

	// StagedWriteData drains and returns all pending GPU buffer writes that have been
	// queued since the last call. The internal queue is reset after draining.
	//
	// Returns:
	//   - []bind_group_provider.BufferWrite: the accumulated buffer writes
	StagedWriteData() []bind_group_provider.BufferWrite

	// PrepareStep advances the physics accumulator by dt and determines how many
	// fixed-timestep substeps to execute this frame. It also drains pending
	// per-body forces/torques into staged buffer writes and builds the
	// GPUPhysicsGlobals uniform data.
	//
	// Parameters:
	//   - dt: wall-clock frame delta time in seconds
	//
	// Returns:
	//   - substeps: the number of fixed-timestep substeps to dispatch (0 if none)
	//   - globalsData: serialized GPUPhysicsGlobals bytes for GPU upload, or nil if substeps is 0
	PrepareStep(dt float32) (substeps int, globalsData []byte)

	// RequestReadback flags that a GPU-to-CPU readback of the body buffer should
	// be initiated on the next command submission.
	RequestReadback()

	// ConsumeReadbackRequest checks whether a readback was requested, clears the
	// request flag, and sets readbackPending so the scene knows a copy is in-flight.
	//
	// Returns:
	//   - bool: true if a readback was requested and consumed
	ConsumeReadbackRequest() bool

	// ReadbackPending returns whether a GPU readback copy is currently in-flight.
	//
	// Returns:
	//   - bool: true if a readback is pending
	ReadbackPending() bool

	// ClearReadbackPending resets the pending readback flag after the mapping
	// callback has completed.
	ClearReadbackPending()

	// StagingBuffer returns the GPU staging buffer used for readback mapping.
	//
	// Returns:
	//   - *wgpu.Buffer: the staging buffer, or nil if not yet created
	StagingBuffer() *wgpu.Buffer

	// SetStagingBuffer sets the GPU staging buffer used for readback mapping.
	//
	// Parameters:
	//   - buf: the staging buffer to store
	SetStagingBuffer(buf *wgpu.Buffer)

	// ProcessReadback unmarshals body positions and quaternions from the raw GPU
	// body buffer readback data and updates the corresponding CPU-side RigidBody
	// state. Each GPUBody is 160 bytes; only the Position (offset 0, 16 bytes)
	// and Quaternion (offset 16, 16 bytes) are extracted.
	//
	// Parameters:
	//   - data: the raw byte slice containing bodiesCount × 160 bytes of GPUBody data
	ProcessReadback(data []byte)
}

type PhysicsBuilderOption func(*physicsImpl)

type RigidBody interface {
	common.Delegate[RigidBody]

	// Position returns the world-space position of the rigid body.
	// This value is updated from GPU readback after each physics frame.
	//
	// Returns:
	//   - [3]float32: A 3D vector representing the world-space position.
	Position() [3]float32

	// Quaternion returns the orientation quaternion (xyzw) of the rigid body.
	// This value is updated from GPU readback after each physics frame.
	//
	// Returns:
	//   - [4]float32: The orientation quaternion in xyzw order.
	Quaternion() [4]float32

	// Velocity returns the linear velocity of the rigid body as a 3D vector.
	//
	// Returns:
	//   - [3]float32: A 3D vector representing the linear velocity of the rigid body.
	Velocity() [3]float32

	// AngularVelocity returns the angular velocity of the rigid body as a 3D vector.
	//
	// Returns:
	//   - [3]float32: A 3D vector representing the angular velocity of the rigid body.
	AngularVelocity() [3]float32

	// Mass returns the mass of the rigid body.
	//
	// Returns:
	//   - float32: The mass of the rigid body.
	Mass() float32

	// InverseMass returns the inverse of the mass of the rigid body.
	//
	// Returns:
	//   - float32: The inverse of the mass of the rigid body.
	InverseMass() float32

	// Bounce returns the bounce factor of the rigid body, which determines how much it bounces when colliding with other objects.
	//
	// Returns:
	//   - float32: The bounce factor of the rigid body.
	Bounce() float32

	// Friction returns the friction factor of the rigid body, which determines how much it resists sliding against other objects.
	//
	// Returns:
	//   - float32: The friction factor of the rigid body.
	Friction() float32

	// InverseInertiaTensorBody returns the inverse of the inertia tensor of the rigid body in body-local space.
	//
	// Returns:
	//   - [9]float32: A 3x3 matrix (flattened to a 1D array) representing the inverse inertia tensor of the rigid body in body-local space.
	InverseInertiaTensorBody() [9]float32

	// Active returns whether the rigid body is active in the simulation.
	//
	// Returns:
	//   - bool: True if the rigid body is active, false otherwise.
	Active() bool

	// Static returns whether the rigid body is static (immovable) in the simulation.
	//
	// Returns:
	//   - bool: True if the rigid body is static, false otherwise.
	Static() bool

	// Kinematic returns whether the rigid body is kinematic (moves according to animation or script) in the simulation.
	//
	// Returns:
	//   - bool: True if the rigid body is kinematic, false otherwise.
	Kinematic() bool

	// Particles returns the set of spherical collision elements that compose the rigid body.
	//
	// Returns:
	//   - []Particle: A slice of Particle structs representing the collision elements of the rigid body.
	Particles() []Particle

	// ParticleRadius returns the radius of each spherical particle generated for the Rigid Body.
	//
	// Returns:
	//   - float32: The radius of each spherical particle generated for the Rigid Body.
	ParticleRadius() float32

	// SurfaceOnly returns whether only surface particles are generated during voxelization.
	//
	// Returns:
	//   - bool: True if only surface particles are generated during voxelization, false otherwise.
	SurfaceOnly() bool

	// SetVelocity sets the linear velocity of the rigid body.
	//
	// Parameters:
	//   - velocity: A 3D vector (XYZ) representing the linear velocity to set for the rigid body.
	SetVelocity(velocity [3]float32)

	// SetAngularVelocity sets the angular velocity of the rigid body.
	//
	// Parameters:
	//   - angularVelocity: A 3D vector (XYZ) representing the angular velocity to set for the rigid body.
	SetAngularVelocity(angularVelocity [3]float32)

	// SetMass sets the mass of the rigid body.
	//
	// Parameters:
	//   - mass: The mass to set for the rigid body.
	SetMass(mass float32)

	// SetInverseMass sets the inverse of the mass of the rigid body.
	//
	// Parameters:
	//   - inverseMass: The inverse of the mass to set for the rigid body.
	SetInverseMass(inverseMass float32)

	// SetBounce sets the bounce factor of the rigid body.
	//
	// Parameters:
	//   - bounce: The bounce factor to set for the rigid body.
	SetBounce(bounce float32)

	// SetFriction sets the friction factor of the rigid body.
	//
	// Parameters:
	//   - friction: The friction factor to set for the rigid body.
	SetFriction(friction float32)

	// SetActive sets whether the rigid body is active in the simulation.
	//
	// Parameters:
	//   - active: True to set the rigid body as active, false to set it as inactive.
	SetActive(active bool)

	// SetStatic sets whether the rigid body is static (immovable) in the simulation.
	//
	// Parameters:
	//   - static: True to set the rigid body as static, false to set it as non-static.
	SetStatic(static bool)

	// SetKinematic sets whether the rigid body is kinematic (moves according to animation or script) in the simulation.
	//
	// Parameters:
	//   - kinematic: True to set the rigid body as kinematic, false to set it as non-kinematic.
	SetKinematic(kinematic bool)

	// SetParticles sets the collision particles of the rigid body.
	//
	// Parameters:
	//   - particles: A slice of Particle structs representing the collision elements to set for the rigid body.
	SetParticles(particles []Particle)

	// SetParticleRadius sets the radius of each spherical particle generated for the Rigid Body.
	//
	// Parameters:
	//   - radius: The radius to set for each spherical particle generated for the Rigid Body.
	SetParticleRadius(radius float32)

	// SetSurfaceOnly sets whether only surface particles are generated during voxelization.
	//
	// Parameters:
	//   - surfaceOnly: True to set only surface particles to be generated during voxelization, false to allow internal particles as well.
	SetSurfaceOnly(surfaceOnly bool)

	// SetPosition sets the world-space position of the rigid body.
	// This is primarily called during GPU readback processing.
	//
	// Parameters:
	//   - position: A 3D vector (XYZ) representing the world-space position to set.
	SetPosition(position [3]float32)

	// SetQuaternion sets the orientation quaternion of the rigid body.
	// This is primarily called during GPU readback processing.
	//
	// Parameters:
	//   - quaternion: A quaternion (XYZW) representing the orientation to set.
	SetQuaternion(quaternion [4]float32)

	// ApplyForce adds a force vector to the pending force accumulator.
	// This is safe to call from any goroutine (e.g. the tick callback).
	// The accumulated force is drained by the physics controller each frame
	// and uploaded as GPUBody.ExternalForce.
	//
	// Parameters:
	//   - force: the force vector (XYZ) to accumulate.
	ApplyForce(force [3]float32)

	// ApplyTorque adds a torque vector to the pending torque accumulator.
	// This is safe to call from any goroutine (e.g. the tick callback).
	// The accumulated torque is drained by the physics controller each frame
	// and uploaded as GPUBody.ExternalTorque.
	//
	// Parameters:
	//   - torque: the torque vector (XYZ) to accumulate.
	ApplyTorque(torque [3]float32)
}

type RigidBodyOption func(*rigidBody)