update physicsBody naming

update documentation
update examples

Author: GoetzDeBouville

docs/bodies.md

@@ -1,6 +1,6 @@
 # Bodies
 
-Bodies are registered via `Modifier.physicsBody(...)`. The modifier binds a Composable to a physics body and allows the runtime to drive its translation and rotation.
+Bodies (childs) are registered via `Modifier.physicsBody(...)` as a first childs of the PhysicsBox. The modifier binds a Composable to a physics body and allows the runtime to drive its translation and rotation.
 
 ## Basic usage
 ```kotlin
@@ -16,24 +16,31 @@ Box(
 - Use immutable types (`String`, `Long`, enums) when possible.
 
 ## PhysicsBodyConfig
-`PhysicsBodyConfig` defines material and motion parameters:
-- `bodyType`: `Dynamic`, `Static`, `Kinematic`
-- `density`, `friction`, `restitution`
-- `linearDamping`, `angularDamping`
-- `fixedRotation`, `allowSleep`, `isBullet`, `gravityScale`
-- `initialTransform` (position in px, rotation in degrees)
+`PhysicsBodyConfig` defines material and motion parameters for a physics body:
+- `bodyType`: Dynamic, Static, Kinematic
+- `density`: body density (applied only to Dynamic bodies; must be >= 0)
+- `friction`: surface friction coefficient (must be >= 0)
+- `restitution`: bounciness coefficient (must be >= 0)
+- `linearDamping`: linear velocity damping (must be >= 0)
+- `angularDamping`: angular velocity damping (must be >= 0)
+- `fixedRotation`: prevents rotation when true
+- `allowSleep`: enables sleeping/auto-deactivation (default true)
+- `isBullet`: enables continuous collision detection for fast-moving bodies
+- `gravityScale`: gravity multiplier for this body
+- `initialTransform`: initial position (px) and rotation (degrees)
 
 Example:
 ```kotlin
-.physicsBody(
+modifier = Modifier.physicsBody(
     key = "floor",
     config = PhysicsBodyConfig(
         bodyType = BodyType.Static,
+        density = 1f,
         friction = 0.6f,
-        restitution = 0.1f,
+        restitution = 0.5f,
         initialTransform = PhysicsTransform(
             vector2 = PhysicsVector2(160f, 360f)
-        )
+        ), // ...
     )
 )
 ```
@@ -43,10 +50,31 @@ Example:
 - `vector2`: position in container px
 - `rotationDegrees`: rotation in degrees (clockwise in Y‑down screen space)
 
+## Shapes
+Collision shape (Physical shape) used by the engine.
+
+## CollisionFilter
+Collision filtering rules (category/mask/group or equivalent).
+
+## Draggability
+`isDraggable` - enables pointer dragging for this body.
+
+## DragConfig
+This configuration controls how a body follows the pointer (finger/mouse) during dragging and what happens when the drag ends (fling).
+
+## CallBacks
+- `onCollision()`
+- `onSleepChanged()`
+- `onDragStart()`
+- `onDragEnd()`
+
 ## Common pitfalls
 !!! tip "Avoiding body re-creation"
     PhysicsBox tracks bodies by key. Reusing the same key for a different Composable can cause callbacks
     to be delivered to the wrong element. Make keys stable and unique.
 
 !!! warning "Config changes"
     Changing shape or size triggers fixture rebuilds. This is supported but can be expensive if done every frame.
+
+## Note
+PhysicsBox can also be a child of another PhysicsBox and contains its own rules and laws.

docs/concepts.md

@@ -11,12 +11,12 @@ PhysicsBox is built around a small set of concepts: a simulation container, a st
 ## PhysicsBoxState
 `PhysicsBoxState` is the mutable controller for the world. It exposes:
 - pause/resume (`pause()`, `resume()`, `isPaused`)
-- gravity (`setWorldGravity(...)`, `gravity`)
+- gravity (`setWorldGravity(...)`, `gravity`, `updateGravity(...)`)
 - step configuration (`stepConfig`, `updateStepConfig(...)`)
 - command helpers (`enqueueImpulse`, `enqueueVelocity`)
 - step callback (`setOnStepListener`)
-
-The runtime drains commands and applies them to the physics backend.
+- apply an impulse or set velocity for bodies by their keys (`enqueueImpulse(...)`, `enqueueVelocity(...)`).
+- etc. (see API)
 
 ## Fixed‑step stepping
 PhysicsBox uses a fixed timestep to keep simulation stable across frame rates. See `StepConfig`:
@@ -30,7 +30,7 @@ Gravity is configured in **physics units** (m/s²). The default is:
 ```kotlin
 PhysicsDefaults.Gravity // (0f, 9.8f)
 ```
-Update it via `PhysicsBoxState.setWorldGravity(...)`.
+Update it using `PhysicsBoxState.updateGravity(...)`.
 
 ## Boundaries
 `BoundariesConfig` creates static walls around the container. This keeps bodies inside the visible area and lets you control restitution/friction at the edges.

docs/getting-started.md

@@ -38,43 +38,50 @@ dependencies {
 }
 ```
 
-## Minimal example
+## Minimal example with two childs (dynamic and static) with minimum of parameters
 ```kotlin
-import androidx.compose.foundation.background
-import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.size
-import androidx.compose.runtime.Composable
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.platform.LocalDensity
-import androidx.compose.ui.unit.dp
-import dev.zinchenko.physicsbox.PhysicsVector2
-import dev.zinchenko.physicsbox.layout.PhysicsBox
-import dev.zinchenko.physicsbox.physicsbody.PhysicsBodyConfig
-import dev.zinchenko.physicsbox.physicsbody.PhysicsTransform
-import dev.zinchenko.physicsbox.physicsbody.physicsBody
-import dev.zinchenko.physicsbox.rememberPhysicsBoxState
-
 @Composable
 fun SimplePhysicsScene() {
-    val state = rememberPhysicsBoxState()
-    val density = LocalDensity.current
-
-    val start = with(density) { PhysicsVector2(120.dp.toPx(), 40.dp.toPx()) }
 
-    PhysicsBox(modifier = Modifier.fillMaxSize(), state = state) {
+    PhysicsBox(
+        modifier = Modifier
+            .fillMaxSize(),
+        state = rememberPhysicsBoxState()
+    ) {
         Box(
             Modifier
                 .size(80.dp)
+                .clip(CircleShape)
+                .physicsBody(
+                    key = "dynamic_circle",
+                    shape = PhysicsShape.Circle(),
+                    config = PhysicsBodyConfig(
+                        initialTransform = PhysicsTransform(
+                            vector2 = PhysicsVector2(x = 781f, y = 0f)
+                        ),
+                        restitution = 0.8f
+                    ),
+                )
                 .background(Color.Red)
+        )
+
+        Box(
+            Modifier
+                .size(80.dp)
                 .physicsBody(
-                    key = "box",
+                    key = "static_box",
                     config = PhysicsBodyConfig(
-                        initialTransform = PhysicsTransform(vector2 = start),
+                        bodyType = BodyType.Static,
+                        initialTransform = PhysicsTransform(
+                            vector2 = PhysicsVector2(780f, 860f),
+                            rotationDegrees = 45f
+                        ),
                     ),
                 )
+                .background(Color.LightGray)
         )
     }
 }
 ```
+
+The default shape for any .physicsBody() is Square. As you can see from the example, the Compose shape should match the PhysicsShape (but it is not required). You also do not have to define the size for PhysicsShape: it takes the size from the composable (but you can override it if you need different sizes for the physical and composable shapes).

docs/index.md

@@ -17,17 +17,19 @@ The runtime uses JBox2D on JVM platforms, providing stable rigid‑body simulati
 - `Modifier.physicsBody` to register Composables as physics bodies.
 - Shapes: box, circle, polygon.
 - Dragging with joint‑style or direct control.
-- Collision, drag, and step events.
+- Collision, gravity simulation and step events.
 
 ## Minimal snippet
 ```kotlin
 val state = rememberPhysicsBoxState()
 
 PhysicsBox(modifier = Modifier.fillMaxSize(), state = state) {
     Box(
-        Modifier
-            .size(80.dp)
-            .physicsBody(key = "box")
+        modifier = Modifier
+            .size(64.dp)
+            .clip(CutCornerShape(0.dp))
+            .physicsBody(key = "default_shape")
+            .background(Color.Red),
     )
 }
 ```

docs/recipes/dragging.md

@@ -4,7 +4,7 @@ PhysicsBox exposes pointer dragging via `Modifier.physicsBody(...)` using `DragC
 
 ## Joint‑style drag (default)
 ```kotlin
-.physicsBody(
+Modifier.physicsBody(
     key = "ball",
     dragConfig = DragConfig(
         useJointStyleDrag = true,
@@ -19,7 +19,7 @@ Joint‑style drag uses a spring‑like constraint (similar to a MouseJoint). Th
 
 ## Direct drag
 ```kotlin
-.physicsBody(
+Modifier.physicsBody(
     key = "card",
     dragConfig = DragConfig(
         useJointStyleDrag = false,

docs/recipes/restitution.md

@@ -4,7 +4,7 @@
 
 ## Body tuning
 ```kotlin
-.physicsBody(
+Modifier.physicsBody(
     key = "ball",
     config = PhysicsBodyConfig(
         restitution = 0.8f,

docs/shapes.md

@@ -6,14 +6,14 @@ Shapes are provided by `PhysicsShape` and define collision geometry. The engine
 `PhysicsShape.Box` uses the Composable bounds as a rectangle.
 
 ```kotlin
-.physicsBody(key = "box", shape = PhysicsShape.Box)
+Modifier.physicsBody(key = "box", shape = PhysicsShape.Box)
 ```
 
 ## Circle
 `PhysicsShape.Circle(radiusPx)` optionally specifies a radius in pixels. If `radiusPx` is null, the runtime derives it from the Composable size.
 
 ```kotlin
-.physicsBody(
+Modifier.physicsBody(
     key = "ball",
     shape = PhysicsShape.Circle(radiusPx = 40f)
 )
@@ -30,7 +30,7 @@ val verts = listOf(
     PhysicsVector2(-0.2f, 0.5f),
 )
 
-.physicsBody(
+Modifier.physicsBody(
     key = "poly",
     shape = PhysicsShape.Polygon(
         vertices = verts,

gradle/libs.versions.toml

@@ -4,7 +4,7 @@ compileSdk = "36"
 targetSdk = "36"
 minSdk = "23"
 
-packageVersion = "1.0.1"
+packageVersion = "1.0.2"
 
 kotlin = "2.3.0"
 compose-multiplatform = "1.10.0"

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

@@ -259,7 +259,7 @@ private object PhysicsBoxScopeImpl : PhysicsBoxScope {
         key = key,
         config = config,
         shape = shape,
-        filter = filter,
+        collisionFilter = filter,
         isDraggable = isDraggable,
         dragConfig = dragConfig,
         onCollision = onCollision,
@@ -269,6 +269,11 @@ private object PhysicsBoxScopeImpl : PhysicsBoxScope {
     )
 }
 
+@Deprecated("Not yet implented")
 internal val LocalPhysicsBoxModifier = staticCompositionLocalOf<Modifier> { Modifier }
+
+@Deprecated("Not yet implented")
 internal val LocalPhysicsBoxConfig = staticCompositionLocalOf { PhysicsBoxConfig() }
+
+@Deprecated("Not yet implented")
 internal val LocalPhysicsDebugConfig = staticCompositionLocalOf { PhysicsDebugConfig() }

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

@@ -9,8 +9,8 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.TransformOrigin
 import androidx.compose.ui.layout.Layout
 import androidx.compose.ui.layout.LayoutCoordinates
-import androidx.compose.ui.layout.onGloballyPositioned
 import androidx.compose.ui.layout.Placeable
+import androidx.compose.ui.layout.onGloballyPositioned
 import androidx.compose.ui.unit.Constraints
 import dev.zinchenko.physicsbox.LocalPhysicsBoxCoordinates
 import dev.zinchenko.physicsbox.engine.PhysicsWorldEngine
@@ -91,17 +91,14 @@ internal fun PhysicsBoxLayout(
             )
         }
 
-        if (!hasValidBounds) {
+        if (hasValidBounds.not()) {
             return@Layout layout(layoutWidth, layoutHeight) {
                 for (child in measuredChildren) {
                     child.placeable.placeRelative(0, 0)
                 }
             }
         }
 
-        @Suppress("UNUSED_VARIABLE")
-        val tick = frameTick.value
-
         val snapshot = engine.snapshotPx()
         val bodyByKey = snapshot.bodiesByKey