kolt is Jolt Physics for Kotlin Multiplatform: the same rigid body, character, vehicle, soft body and ragdoll simulation on Android, iOS, the JVM and the Web (JS & Wasm), from one API in commonMain.

[!NOTE] Unofficial project. A community-maintained Kotlin wrapper around Jolt Physics, not affiliated with or endorsed by its authors.

Jolt.init()

val temp = TempAllocatorImpl(10 * 1024 * 1024)
val jobs = JobSystemThreadPool(2048, 8, 1)
// One object layer in one broad phase layer, colliding with itself.
val broadPhaseLayers = BroadPhaseLayerInterfaceTable(1, 1).also { it.mapObjectToBroadPhaseLayer(0, BroadPhaseLayer(0)) }
val layerPairs = ObjectLayerPairFilterTable(1).also { it.enableCollision(0, 0) }
val objectVsBroadPhase = ObjectVsBroadPhaseLayerFilterTable(broadPhaseLayers, 1, layerPairs, 1)
val system = PhysicsSystem().also { it.init(1024, 0, 1024, 1024, broadPhaseLayers, objectVsBroadPhase, layerPairs) }
val bodies = system.bodyInterface

val sphere = SphereShape(0.5f, null)
val ball = BodyCreationSettings(sphere, Vec3(0f, 10f, 0f), Quat.IDENTITY, EMotionType.Dynamic, 0).use { settings ->
    bodies.createAndAddBody(settings, EActivation.Activate)
}

repeat(60) { system.update(1f / 60, 1, temp, jobs) }
println(bodies.getPosition(ball)) // about 5 m lower, a second later

If you know Jolt, you know kolt: the classes, methods and enums are Jolt's, in the package of their header's directory (physics.body.BodyInterface). Getting Started continues this example, down to closing what it created.

Every platform runs on one C API generated from Jolt's C++ headers, and the Kotlin API is generated once, in commonMain, on top of it. The API and its behavior are the same everywhere:

What differs per platform (loading the native library, threads on the web) is in Platform Notes.

kolt is on Maven Central: one dependency, native code included on every target.

commonMain.dependencies { implementation("io.github.erkko68.kolt:kolt:0.1.0") }

On the web, serve kolt.js and kolt.wasm (each release's assets) next to your bundle; see Platform Notes.

To build it from source, clone with the Jolt submodule and run the tests:

git clone --recurse-submodules https://github.com/Erkko68/kolt.git
./gradlew :kotlin:kolt:jvmTest :kotlin:kolt:iosSimulatorArm64Test

The toolchain each target needs is listed in Getting Started.

samples/ is a wall of cubes to push over, simulated by kolt and rendered by filament-kmp in Compose Multiplatform, on every target. Its web build is live at erkko68.github.io/kolt; samples/README.md has the commands for the others.

The public API follows Jolt's C++ API, the one Jolt's documentation and headers describe, adapted only where Kotlin has its own shape:

• Kotlin properties for GetX/SetX pairs and fields (system.gravity, settings.motionType); statics lose their s (ConstraintSettings::sRestoreFromBinaryState is ConstraintSettings.restoreFromBinaryState).
• close() gives back what Kotlin created; what Jolt keeps is borrowed, and closing it does nothing.
• Subclass to listen: object : ContactListener() { override fun onContactAdded(…) }. A std::function is a Kotlin lambda.
• Results, not out-parameters: getPositionAndRotation(id) returns a Pair<Vec3, Quat>; an error result throws NativeException.
• Nothing invented: no wrappers C++ doesn't have. Of Jolt's bindable API, 3604 of 3622 functions are wrapped; c/api-coverage.txt names the rest.

The full set of rules is in API Conventions.

• API reference: every class, generated by Dokka.
• Getting Started: building from source, a first simulation, cleaning up.
• API Conventions: how Jolt's C++ reads in Kotlin: names, ownership, callbacks, out-parameters, arrays, casts.
• Platform Notes: targets, native libraries, what the web does differently.

• Repository Structure: what lives where, and what is generated.
• The Generator: from C++ headers to a C API to Kotlin, and its config.
• Native Builds: CMake, JNI, the wasm image.
• Testing: the suites, how to run them per target, coverage.
• Upgrading Jolt: moving the submodule to a new release.
• CI and Releasing: the workflows, the API reference on GitHub Pages, publishing to Maven Central.

• Jolt Physics documentation: architecture, layers, shapes, constraints.
• HelloWorld.cpp: the C++ this README's example mirrors.