PhysicsBox/dev.zinchenko.physicsbox/PhysicsBoxState

PhysicsBoxState

@Stable

class PhysicsBoxState

Mutable controller for a physics world hosted by dev.zinchenko.physicsbox.layout.PhysicsBox.

This state is intended to be the primary API surface for:

pausing/resuming simulation (pause, resume, isPaused)
updating world gravity (setWorldGravity, gravity)
configuring stepping/solver parameters (stepConfig, solverIterations)
queuing one-off actions for the runtime (enqueueCommand and helpers)

The state keeps a queue of PhysicsCommand objects. The runtime drains it and applies changes to the underlying physics engine. UI code should treat command helpers as fire-and-forget.

Notes:

This class is Stable to avoid unnecessary recompositions when only internal bookkeeping changes.
Values such as gravity and stepConfig are exposed as Compose state (mutable) and will trigger recomposition when changed. Per-body transforms are intentionally not mirrored here.

Properties

var gravity: PhysicsVector2

Current world gravity vector.

var isPaused: Boolean

Whether the simulation is paused.

pendingCommandVersion

val pendingCommandVersion: Long

Monotonic marker that changes when the command queue receives new commands.

solverIterations

val solverIterations: SolverIterations

Convenience view over solver iteration counts derived from stepConfig.

var stepConfig: StepConfig

Current step configuration (timestep/iterations/etc.).

Functions

fun enqueueCommand(command: PhysicsCommand)

Generic command extension point for advanced integrations.

fun enqueueImpulse(key: Any, impulseX: Float, impulseY: Float, wake: Boolean = true)

Queues a linear impulse for the body associated with key.

enqueueVelocity

fun enqueueVelocity(key: Any, velocityX: Float, velocityY: Float)

Queues a linear velocity update for the body associated with key.

fun pause()

Pauses simulation stepping.

fun reset()

Resets world-level settings and requests runtime world reset.

fun resume()

Resumes simulation stepping.

setOnStepListener

fun setOnStepListener(listener: (StepEvent) -> Unit?)

Registers a world step callback.

setSolverIterations

fun setSolverIterations(velocityIterations: Int, positionIterations: Int)

Convenience helper for updating solver iteration counts.

setWorldGravity

fun setWorldGravity(gravity: PhysicsVector2)

Sets world gravity and enqueues PhysicsCommand.SetWorldGravity.

fun snapshot(): PhysicsWorldSnapshot

Creates an immutable snapshot of the current world-level configuration.

fun updateGravity(gravity: PhysicsVector2)

fun updateGravity(x: Float, y: Float)

Updates gravity and enqueues the change for the runtime.

updateStepConfig

fun updateStepConfig(stepConfig: StepConfig)

Replaces current stepConfig.