PhysicsBox

PhysicsBox is a Compose Multiplatform physics layout container for Android and Desktop (JVM). It turns composables into 2D physics bodies and renders their motion by applying translation and rotation during layout.

The runtime uses JBox2D on JVM platforms, giving you stable rigid-body simulation with fixed-timestep stepping, boundaries, dragging, and collision callbacks.

Inspired by PhysicsLayout.

Demo Screencast

Quick Start

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.github.zinchenko-dev:physicsbox:<latest_release>")
            }
        }
    }
}

@Composable
fun PhysicsDemo() {
    PhysicsBox(modifier = Modifier.fillMaxSize()) {
        Box(
            modifier = Modifier
                .size(72.dp)
                .background(Color.Red)
                .physicsBody(key = "ball")
        )
    }
}

API docs: https://goetzdebouville.github.io/PhysicsBox/api/

Installation (Gradle Kotlin DSL)

Add Maven Central:

repositories {
    mavenCentral()
}

KMP (commonMain):

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.github.zinchenko-dev:physicsbox:<latest_release>")
            }
        }
    }
}

Android-only:

dependencies {
    implementation("io.github.zinchenko-dev:physicsbox-android:<latest_release>")
}

Desktop-only:

dependencies {
    implementation("io.github.zinchenko-dev:physicsbox-desktop:<latest_release>")
}

Features

• Physics-aware Compose container (PhysicsBox) with fixed-timestep simulation.
• Simple body registration via Modifier.physicsBody.
• Shapes: rectangle, circle, polygon.
• World boundaries, gravity, damping, solver iterations.
• Pointer dragging with joint or direct control modes.
• Collision, drag, and step events.

Documentation

Read the full documentation at https://goetzdebouville.github.io/PhysicsBox/.

Platforms

• Android (minSdk 23)
• Desktop (JVM)

Requirements and Limitations

• Compose Multiplatform (runtime, ui, foundation).
• JVM-only physics backend (JBox2D). iOS/JS are not supported.

Samples

Android:

• Run on device/emulator from Android Studio using the imported run configuration.
• Build debug APK: ./gradlew :androidApp:assembleDebug
• APK output: androidApp/build/outputs/apk/debug/androidApp-debug.apk

Desktop:

• Run desktop app: ./gradlew :desktopApp:run
• Run desktop hot reload app: ./gradlew :desktopApp:hotRun --auto

Roadmap

• iOS target
• JS/WASM target

License

Apache-2.0

Contributors