Merge pull request #2 from GoetzDeBouville/dev

Refactor stepping & units; add polygon utilities (v2.0.0)

Author: GoetzDeBouville

docs/shapes.md

@@ -39,6 +39,73 @@ Modifier.physicsBody(
 )
 ```
 
+### Polygon utilities
+
+#### regularPolygonNormalized(...)
+`regularPolygonNormalized(...)` returns a regular convex `PhysicsShape.Polygon` in
+`PhysicsShape.Polygon.VertexSpace.Normalized`.
+
+In normalized space, `x` and `y` values in `-0.5..0.5` map to the Composable's width and height.
+On non-square Composables, the polygon stretches with the measured bounds in the same way as the
+physics fixture.
+
+Vertices use screen-oriented coordinates. Because of that, `rotationDegrees` is clockwise. The default `-90f` places the first vertex at the top.
+
+- `sides` must be in `3..8` (backend limit).
+- `radius` must be finite and `> 0`.
+- `rotationDegrees` must be finite.
+
+```kotlin
+val hex = regularPolygonNormalized(sides = 6)
+
+Modifier.physicsBody(key = "hex", shape = hex)
+```
+
+```kotlin
+val tri = regularPolygonNormalized(
+    sides = 3,
+    radius = 0.45f,
+    rotationDegrees = 0f,
+)
+
+Modifier.physicsBody(key = "tri", shape = tri)
+```
+
+#### polygonComposeShape(...)
+`polygonComposeShape(...)` converts a `PhysicsShape.Polygon` to a Compose `Shape`
+(`GenericShape`) so the visual clip can match the collision geometry.
+
+It supports both `PhysicsShape.Polygon.VertexSpace.Normalized` and
+`PhysicsShape.Polygon.VertexSpace.Px`, using the same local-origin mapping as the physics fixture
+adapter.
+
+If the polygon has fewer than 3 vertices, or if the Composable size is zero, the resulting path is
+empty and the shape is effectively a no-op.
+
+```kotlin
+val poly = regularPolygonNormalized(6)
+
+Modifier
+    .clip(polygonComposeShape(poly))
+    .physicsBody(key = "poly", shape = poly)
+```
+
+```kotlin
+val pxPoly = PhysicsShape.Polygon(
+    vertices = listOf(
+        PhysicsVector2(-40f, -30f),
+        PhysicsVector2(40f, -30f),
+        PhysicsVector2(20f, 50f),
+        PhysicsVector2(-20f, 50f),
+    ),
+    space = PhysicsShape.Polygon.VertexSpace.Px,
+)
+
+Modifier
+    .clip(polygonComposeShape(pxPoly))
+    .physicsBody(key = "pxPoly", shape = pxPoly)
+```
+
 ### Constraints
 - **Convex only** (no concave or self‑intersecting shapes).
 

gradle/libs.versions.toml

@@ -4,14 +4,13 @@ compileSdk = "36"
 targetSdk = "36"
 minSdk = "23"
 
-packageVersion = "1.0.3"
+packageVersion = "1.0.4"
 
 kotlin = "2.3.0"
-compose-multiplatform = "1.10.0"
+compose-multiplatform = "1.10.1"
 material3 = "1.10.0-alpha05"
 agp = "8.13.2"
-androidx-activityCompose = "1.12.3"
-kermit = "2.0.8"
+androidx-activityCompose = "1.12.4"
 kotlinx-coroutines = "1.10.2"
 
 jbox2d = "2.2.1.1"
@@ -32,7 +31,6 @@ compose-ui-tooling = { module = "org.jetbrains.compose.ui:ui-tooling", version.r
 compose-material3 = { module = "org.jetbrains.compose.material3:material3", version.ref = "material3" }
 
 androidx-activityCompose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activityCompose" }
-kermit = { module = "co.touchlab:kermit", version.ref = "kermit" }
 
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "kotlinx-coroutines" }

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/PhysicsBoxState.kt

@@ -174,24 +174,25 @@ class PhysicsBoxState internal constructor(
     /**
      * Queues a linear impulse for the body associated with [key].
      *
-     * Units are interpreted by the runtime (typically physics units).
+     * Impulse components are expressed in container pixels (Px) and converted internally
+     * to physics impulse units by the runtime [dev.zinchenko.physicsbox.units.PhysicsUnits].
      *
      * @param key Body key used in `Modifier.physicsBody(key = ...)`.
-     * @param impulseX Impulse X component.
-     * @param impulseY Impulse Y component.
+     * @param impulseXPx Impulse X component in container pixels (Px).
+     * @param impulseYPx Impulse Y component in container pixels (Px).
      * @param wake Whether to wake the body if the backend supports sleeping.
      */
     fun enqueueImpulse(
         key: Any,
-        impulseX: Float,
-        impulseY: Float,
+        impulseXPx: Float,
+        impulseYPx: Float,
         wake: Boolean = true,
     ) {
         enqueueCommand(
             PhysicsCommand.EnqueueImpulse(
                 key = key,
-                impulseX = impulseX,
-                impulseY = impulseY,
+                impulseXPx = impulseXPx,
+                impulseYPx = impulseYPx,
                 wake = wake,
             ),
         )
@@ -200,12 +201,13 @@ class PhysicsBoxState internal constructor(
     /**
      * Queues a linear velocity update for the body associated with [key].
      *
-     * Units are interpreted by the runtime (some implementations may treat these as physics units,
-     * others as pixel units; prefer runtime-specific helpers if available).
+     * Velocity components are expressed in container pixels per second (Px/s) and converted
+     * internally to meters per second by the runtime
+     * [dev.zinchenko.physicsbox.units.PhysicsUnits].
      *
      * @param key Body key used in `Modifier.physicsBody(key = ...)`.
-     * @param velocityX Velocity X component.
-     * @param velocityY Velocity Y component.
+     * @param velocityX Velocity X component in container pixels per second (Px/s).
+     * @param velocityY Velocity Y component in container pixels per second (Px/s).
      */
     fun enqueueVelocity(
         key: Any,
@@ -215,8 +217,8 @@ class PhysicsBoxState internal constructor(
         enqueueCommand(
             PhysicsCommand.EnqueueVelocity(
                 key = key,
-                velocityX = velocityX,
-                velocityY = velocityY,
+                velocityXPxPerSec = velocityX,
+                velocityYPxPerSec = velocityY,
             ),
         )
     }
@@ -278,10 +280,6 @@ class PhysicsBoxState internal constructor(
         callbacksByKey.remove(key)
     }
 
-    internal fun dispatchCollisionToBody(event: CollisionEvent) {
-        callbacksByKey[event.selfKey]?.onCollision?.invoke(event)
-    }
-
     internal fun dispatchDragToBody(event: DragEvent) {
         val callbacks = callbacksByKey[event.key] ?: return
         when (event.phase) {
@@ -290,10 +288,6 @@ class PhysicsBoxState internal constructor(
             DragPhase.End, DragPhase.Cancel -> callbacks.onDragEnd?.invoke(event)
         }
     }
-
-    internal fun dispatchSleepToBody(key: Any, isSleeping: Boolean) {
-        callbacksByKey[key]?.onSleepChanged?.invoke(isSleeping)
-    }
 }
 
 /**

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/PhysicsCommand.kt

@@ -18,28 +18,32 @@ sealed interface PhysicsCommand {
      * Applies a linear impulse to a body.
      *
      * @param key Body key used in `Modifier.physicsBody(key = ...)`.
-     * @param impulseX X component of impulse (runtime-defined units).
-     * @param impulseY Y component of impulse (runtime-defined units).
+     * @param impulseXPx X component of impulse in container pixels (Px).
+     * Converted internally to physics impulse units by [dev.zinchenko.physicsbox.units.PhysicsUnits].
+     * @param impulseYPx Y component of impulse in container pixels (Px).
+     * Converted internally to physics impulse units by [dev.zinchenko.physicsbox.units.PhysicsUnits].
      * @param wake Whether the backend should wake the body if supported.
      */
     data class EnqueueImpulse(
         val key: Any,
-        val impulseX: Float,
-        val impulseY: Float,
+        val impulseXPx: Float,
+        val impulseYPx: Float,
         val wake: Boolean = true,
     ) : PhysicsCommand
 
     /**
      * Sets/overwrites linear velocity of a body.
      *
      * @param key Body key used in `Modifier.physicsBody(key = ...)`.
-     * @param velocityX X component (runtime-defined units).
-     * @param velocityY Y component (runtime-defined units).
+     * @param velocityXPxPerSec X component in container pixels per second (Px/s).
+     * Converted internally to meters per second by [dev.zinchenko.physicsbox.units.PhysicsUnits].
+     * @param velocityYPxPerSec Y component in container pixels per second (Px/s).
+     * Converted internally to meters per second by [dev.zinchenko.physicsbox.units.PhysicsUnits].
      */
     data class EnqueueVelocity(
         val key: Any,
-        val velocityX: Float,
-        val velocityY: Float,
+        val velocityXPxPerSec: Float,
+        val velocityYPxPerSec: Float,
     ) : PhysicsCommand
 
     /**

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/engine/PhysicsEventSink.kt

@@ -11,11 +11,3 @@ internal interface PhysicsEventSink {
 
     fun onDrag(event: DragEvent)
 }
-
-internal object NoOpEventSink : PhysicsEventSink {
-    override fun onCollision(event: CollisionEvent) = Unit
-
-    override fun onStep(event: StepEvent) = Unit
-
-    override fun onDrag(event: DragEvent) = Unit
-}

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/engine/PhysicsWorldEngine.kt

@@ -5,6 +5,7 @@ import dev.zinchenko.physicsbox.PhysicsBoxConfig
 import dev.zinchenko.physicsbox.PhysicsCommand
 import dev.zinchenko.physicsbox.PhysicsWorldSnapshot
 import dev.zinchenko.physicsbox.SolverIterations
+import dev.zinchenko.physicsbox.StepConfig
 import dev.zinchenko.physicsbox.physicsbody.CollisionFilter
 import dev.zinchenko.physicsbox.physicsbody.PhysicsBodyConfig
 import dev.zinchenko.physicsbox.physicsbody.PhysicsBodyRegistration
@@ -20,7 +21,11 @@ internal expect class PhysicsWorldEngine(
 ) {
     fun setPaused(paused: Boolean)
 
-    fun step(deltaSeconds: Float): StepResult
+    fun step(
+        deltaSeconds: Float,
+        stepConfig: StepConfig,
+        solverIterations: SolverIterations,
+    ): StepResult
 
     fun apply(command: PhysicsCommand)
 

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/events/CollisionEvent.kt

@@ -7,8 +7,13 @@ package dev.zinchenko.physicsbox.events
  * registration keys from `Modifier.physicsBody(key = ...)`.
  *
  * ### Impulse and normal
- * - [impulse] is a scalar magnitude representing the strength of the contact resolution for this
- * event (engine-specific; typically proportional to momentum exchange).
+ * - [impulse] is a scalar collision impulse magnitude that has already been converted for UI-space
+ * scaling.
+ * - In the JVM backend it is produced by taking the Box2D impulse in physics units and converting
+ * it via [dev.zinchenko.physicsbox.units.PhysicsUnits] (PxPerMeter/worldScale).
+ * - Treat this as a px-scaled magnitude suitable for UX effects (sound/haptics/FX thresholds),
+ * not as raw physics units.
+ * - Treat as px-scaled magnitude (UI scale), not N·s and not m·kg/s.
  * - ([normalX], [normalY]) is the contact normal in world/container space as reported by the engine.
  * In the current backend the normal points from this body toward the other body; conventions may
  * differ across physics engines.
@@ -18,7 +23,7 @@ package dev.zinchenko.physicsbox.events
  *
  * @param selfKey Key of the body that owns the listener (the “this” body).
  * @param otherKey Key of the other body involved in the collision.
- * @param impulse Contact impulse magnitude (engine-defined units).
+ * @param impulse Contact impulse magnitude converted to UI px-scale via PhysicsUnits.
  * @param normalX X component of the reported collision normal.
  * @param normalY Y component of the reported collision normal.
  */

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/layout/PhysicsBox.kt

@@ -114,6 +114,7 @@ private fun PhysicsBoxImpl(
     }
     val solverIterations = state.solverIterations
     val units = remember(runtimeConfig.worldScale) { runtimeConfig.units() }
+    val engineSyncState = remember { EngineSyncState() }
 
     val eventSink = remember(state) {
         object : PhysicsEventSink {
@@ -127,9 +128,9 @@ private fun PhysicsBoxImpl(
         }
     }
 
-    val engine = remember(runtimeConfig, solverIterations, units, eventSink) {
+    val engine = remember(runtimeConfig.boundaries, units, eventSink) {
         PhysicsWorldEngine(
-            config = runtimeConfig,
+            config = config.copy(step = state.stepConfig),
             solverIterations = solverIterations,
             boundariesConfig = runtimeConfig.boundaries,
             units = units,
@@ -140,6 +141,10 @@ private fun PhysicsBoxImpl(
     val isPaused = state.isPaused
     SideEffect {
         engine.setPaused(isPaused)
+        if (engineSyncState.gravitySyncedEngine !== engine) {
+            engine.apply(PhysicsCommand.SetWorldGravity(state.gravity))
+            engineSyncState.gravitySyncedEngine = engine
+        }
         if (pendingCommandVersion >= 0L) {
             val commands = state.drainPendingCommands()
             if (commands.isNotEmpty()) {
@@ -222,8 +227,8 @@ interface PhysicsBoxScope {
      * @param isDraggable Enables pointer dragging for this body.
      * @param dragConfig Drag tuning parameters (max force, spring frequency, damping, fling limits).
      * @param onCollision Optional body-level collision callback.
-     * @param onSleepChanged Optional callback invoked when the body enters/leaves “sleep” state
-     * (engine-specific; typically means it stopped moving and is excluded from simulation work).
+     * @param onSleepChanged Optional callback invoked when the body enters/leaves “sleep” state.
+     * Callback parameter is `isSleeping` (`true` when sleeping, `false` when awake).
      * @param onDragStart Optional callback invoked when a drag starts for this body.
      * @param onDragEnd Optional callback invoked when a drag ends (including cancel).
      */
@@ -276,3 +281,7 @@ internal val LocalPhysicsBoxConfig = staticCompositionLocalOf { PhysicsBoxConfig
 
 @Deprecated("Not yet implented")
 internal val LocalPhysicsDebugConfig = staticCompositionLocalOf { PhysicsDebugConfig() }
+
+private class EngineSyncState {
+    var gravitySyncedEngine: PhysicsWorldEngine? = null
+}

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/layout/PhysicsSimulationLoop.kt

@@ -2,6 +2,7 @@ package dev.zinchenko.physicsbox.layout
 
 import androidx.compose.runtime.withFrameNanos
 import dev.zinchenko.physicsbox.PhysicsBoxState
+import dev.zinchenko.physicsbox.SolverIterations
 import dev.zinchenko.physicsbox.StepConfig
 import dev.zinchenko.physicsbox.engine.PhysicsWorldEngine
 import kotlinx.coroutines.currentCoroutineContext
@@ -43,6 +44,10 @@ internal class PhysicsSimulationLoop(
 
                 val stepConfig = stepConfigProvider()
                 val fixedDeltaSeconds = 1f / stepConfig.hz
+                val solverIterations = SolverIterations(
+                    velocity = stepConfig.velocityIterations,
+                    position = stepConfig.positionIterations,
+                )
 
                 val frameDeltaNanos = (frameTimeNanos - lastFrameNanos).coerceAtLeast(0L)
                 lastFrameNanos = frameTimeNanos
@@ -58,7 +63,11 @@ internal class PhysicsSimulationLoop(
                     accumulatorSeconds + FIXED_STEP_EPSILON >= fixedDeltaSeconds &&
                     subSteps < stepConfig.maxSubSteps
                 ) {
-                    engine.step(fixedDeltaSeconds)
+                    engine.step(
+                        deltaSeconds = fixedDeltaSeconds,
+                        stepConfig = stepConfig,
+                        solverIterations = solverIterations,
+                    )
                     accumulatorSeconds -= fixedDeltaSeconds
                     subSteps++
                 }

physicsbox/src/commonMain/kotlin/dev/zinchenko/physicsbox/physicsbody/PhysicsBody.kt

@@ -32,7 +32,8 @@ import dev.zinchenko.physicsbox.events.DragEvent
  * @param isDraggable Enables pointer-driven dragging for this body.
  * @param dragConfig Drag tuning parameters.
  * @param onCollision Optional callback for contact events involving this body.
- * @param onSleepChanged Optional callback when sleeping state changes (engine-defined).
+ * @param onSleepChanged Optional callback when sleeping state changes.
+ * Callback parameter is `isSleeping` (`true` when the body is sleeping).
  * @param onDragStart Optional callback when drag interaction starts.
  * @param onDragEnd Optional callback when drag interaction ends (including cancel).
  */