jBox2D

Java bindings for Box2D, generated by jParser for desktop JNI, desktop FFM, TeaVM C, WebAssembly, and Android.

The Java API follows Box2D's handle-based model. Worlds own bodies, bodies own shapes and chains, contacts are read through buffered events, and all runtime variants are generated from one WebIDL contract plus a small C++ facade.

Targets

Module	Purpose
:box2d:download	Downloads the pinned upstream Box2D source archive into its build directory.
:box2d:builder	Owns box2d.idl, the C++ facade, jParser generation, and native build targets.
:box2d:base, :box2d:core	Runtime loader input and generated platform-neutral Java API.
:box2d:shared:jni, :box2d:desktop:jni	Generated JNI bindings and packaged desktop native libraries.
:box2d:desktop:ffm	Generated Java 25 Foreign Function & Memory bindings.
:box2d:shared:c, :box2d:desktop:c	TeaVM C bindings and desktop native packaging.
:box2d:web:wasm	TeaVM WebAssembly API and Emscripten side module.
:box2d:android:jni, :box2d:android:c	Android JNI and TeaVM C runtimes.
:samples:shared	One Java binding port per active Box2D sample, plus the shared registry.
:samples:core	Cross-platform libGDX sample selector and renderer.
:samples:desktop:jni, :samples:desktop:ffm	LWJGL3 launchers for the JNI and FFM runtimes.
:samples:web	TeaVM JavaScript and WasmGC browser launchers.
:samples:android	Android JNI sample-browser application.

The binding contract is box2d/builder/src/main/cpp/box2d.idl. The facade in box2d/builder/src/main/cpp/custom converts opaque Box2D IDs and C structs into a Java-friendly API while preserving the upstream semantics.

Samples

The Java ports of the official Box2D sample suite live in :samples:shared. The shared libGDX sample browser, UI, and renderer live in :samples:core.

Web version: https://xpenatan.github.io/jBox2D

libGDX WebGL sample launchers:

• :samples:desktop:jni
• :samples:desktop:ffm
• :samples:web
• :samples:android

The web launcher publishes both TeaVM JavaScript and WasmGC builds. The browser contains Java ports of all 110 active scenarios registered by the official Box2D sample target. Each scenario is a separate class under samples/shared/src/main/java/com/github/xpenatan/box2d/sample/shared/samples, and the registry maps the official category/name to its Java factory. There is no embedded C++ sample suite; desktop, Android, and web all use the same generated bindings.

Requirements

• JDK 25 for the full build and FFM runtime.
• A platform C/C++ toolchain: MSVC on Windows, clang/gcc on Linux, or Xcode command-line tools on macOS.
• Emscripten for the WebAssembly target.
• Android SDK/NDK for Android native targets (compile SDK 36; API 29 minimum).
• The current jParser snapshot artifacts, resolved from Maven Local or Maven Central snapshots.

The Gradle wrapper is pinned to 9.4.1 so the build can run on JDK 25.

Generate bindings

PowerShell:

.\gradlew.bat :box2d:download:box2d_download_source
.\gradlew.bat :box2d:builder:jParser_generate

The source download is build output; upstream Box2D is not copied into this repository.

For a from-scratch verification, regenerate after clean because the generated Java source sets are deliberately removed by their module clean tasks:

.\gradlew.bat clean
.\gradlew.bat :box2d:builder:jParser_generate
.\gradlew.bat build

Build native runtimes

Windows examples:

.\gradlew.bat :box2d:builder:jParser_build_windows64_jni
.\gradlew.bat :box2d:builder:jParser_build_windows64_ffm
.\gradlew.bat :box2d:builder:jParser_build_windows64_teavm_c
.\gradlew.bat :box2d:builder:jParser_build_web_wasm

Equivalent linux64, mac64, and macArm desktop tasks are provided by the builder. Android tasks are:

.\gradlew.bat :box2d:builder:jParser_build_android_jni
.\gradlew.bat :box2d:builder:jParser_build_android_teavm_c

The builder also exposes :box2d:builder:jParser_build_ios_jni; this repository does not yet include an iOS packaging module.

Running Samples

Desktop:

.\gradlew.bat :samples:desktop:jni:box2d_sample_jni_run
.\gradlew.bat :samples:desktop:ffm:box2d_sample_ffm_run

Like jBox3D, the desktop run tasks consume the native libraries already packaged by the binding modules; they do not invoke the native builder. Run the matching jParser_build_*_jni or jParser_build_*_ffm task explicitly after changing native code.

Web JavaScript and WasmGC distributions:

.\gradlew.bat :samples:web:gdx_teavm_web_js_build
.\gradlew.bat :samples:web:gdx_teavm_web_wasm_build
.\gradlew.bat :samples:web:gdx_teavm_web_js_run
.\gradlew.bat :samples:web:gdx_teavm_web_wasm_run

GitHub Pages packages both web variants behind a platform selector:

.\gradlew.bat :samples:web:box2d_samples_pages_build

The static site is written to samples/web/build/pages, with the JavaScript build under gdx/gl/js and the WasmGC build under gdx/gl/wasm. The .github/workflows/gh-pages.yml workflow builds and deploys this site from master; the repository's Pages source must be set to GitHub Actions.

Android (API 29 or newer):

.\gradlew.bat :samples:android:box2d_samples_android_build
.\gradlew.bat :samples:android:box2d_samples_android_run

Select a scenario from the left panel. The right panel exposes global solver/debug settings and the selected sample's original controls. Drag with the primary pointer to interact with bodies, drag with the right or middle mouse button to pan, use the wheel to zoom, and press Home to reset the camera. Keyboard-driven samples receive the same letter, number, space, enter, and arrow keys as the upstream GLFW application.

Launchers accept a sample name or Category/Name through jbox2d.sample.sample, or an index through jbox2d.sample.sampleIndex. For example:

$env:GRADLE_OPTS = '-Djbox2d.sample.sample=Benchmark/Cast'
.\gradlew.bat :samples:desktop:jni:box2d_sample_jni_run

License

jBox2D is licensed under the Apache License 2.0. Upstream Box2D is developed by Erin Catto and is licensed under the MIT license.