<picture>
<source media="(prefers-color-scheme: dark)" srcset="/api/public/p/aHR0cHM6Ly9saWIuaGF4ZS5vcmcvcC9kb2NzL2ltYWdlcy9sb2dvLWRhcmsuc3Zn">
<img width="50%" src="/api/public/p/aHR0cHM6Ly9saWIuaGF4ZS5vcmcvcC9kb2NzL2ltYWdlcy9sb2dvLnN2Zw" alt="hlbox3d">
</picture>
<a href="/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL2VyaW5jYXR0by9ib3gzZA" target="_blank">Box3D</a> physics for
<a href="/api/public/p/aHR0cHM6Ly9oZWFwcy5pby8" target="_blank">Heaps</a> —
<a href="/api/public/p/aHR0cHM6Ly9oYXNobGluay5oYXhlLm9yZy8" target="_blank">HashLink</a> and JS/WebGL
<a href="/api/public/p/aHR0cHM6Ly9saWIuaGF4ZS5vcmcvcC9MSUNFTlNF" target="_blank">
<img src="/api/public/p/aHR0cHM6Ly9pbWcuc2hpZWxkcy5pby9naXRodWIvbGljZW5zZS9TdGVwYW5aYWxldHNraXkvaGxib3gzZC5zdmc" alt="GitHub license">
</a>
<a href="/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL1N0ZXBhblphbGV0c2tpeS9obGJveDNkL3JlbGVhc2Vz" target="_blank">
<img src="/api/public/p/aHR0cHM6Ly9pbWcuc2hpZWxkcy5pby9naXRodWIvdGFnL1N0ZXBhblphbGV0c2tpeS9obGJveDNkLnN2Zw" alt="GitHub tag (latest SemVer)">
</a>
<a href="/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL1N0ZXBhblphbGV0c2tpeS9obGJveDNkL2FjdGlvbnM" target="_blank">
<img src="/api/public/p/aHR0cHM6Ly9pbWcuc2hpZWxkcy5pby9naXRodWIvYWN0aW9ucy93b3JrZmxvdy9zdGF0dXMvU3RlcGFuWmFsZXRza2l5L2hsYm94M2QvYnVpbGQueW1s" alt="Build workflow status">
</a>
<a href="/api/public/p/aHR0cHM6Ly9naXRodWIuY29tL1N0ZXBhblphbGV0c2tpeS9obGJveDNkL2NvbW1pdHM" target="_blank">
<img src="/api/public/p/aHR0cHM6Ly9pbWcuc2hpZWxkcy5pby9naXRodWIvY29tbWl0LWFjdGl2aXR5L3kvU3RlcGFuWmFsZXRza2l5L2hsYm94M2Quc3Zn" alt="GitHub commit activity">
</a>
<a href="/api/public/p/aHR0cHM6Ly9saWIuaGF4ZS5vcmcvcC9obGJveDNk" target="_blank">
<img src="/api/public/p/aHR0cHM6Ly9pbWcuc2hpZWxkcy5pby9iYWRnZS9oYXhlbGliLWhsYm94M2Qtb3JhbmdlLnN2Zw" alt="haxelib">
</a>
hlbox3d is Box3D, Erin Catto's 3D rigid body engine, for Haxe. The solver is Box3D itself, compiled as it is into a native module for HashLink and into wasm for the browser; the Haxe side, the box3d package, is the same code on every target. Bodies, shapes, joints, queries and events, meshes and height fields, a character mover and a ragdoll, recording and replay, with a fixed step and interpolated drawing for Heaps.
This repository contains the library: the C shim, the Haxe package, a minimal sample and the ports of Box3D's unit tests.
🚀 Installation
Install Haxe
Download and install Haxe 4.3 or later.
Check with haxe --version.
Install HashLink and Heaps
Follow the Heaps installation guide:
HashLink on your PATH, then haxelib install heaps and hlsdl or hldx.
Check with hl in a terminal. Skip this for a browser-only game.
Install hlbox3d
The Haxe side comes from git, the way Heaps does:
haxelib git hlbox3d https://github.com/StepanZaletskiy/hlbox3d
Or as a submodule of the game, with -cp hlbox3d/src instead of -lib.
Install the native module
HashLink loads box3d.hdll from next to hl.exe on Windows and from
the library path on Linux. This downloads the prebuilt one for this
version from the GitHub release and puts it there:
haxelib run hlbox3d install # or: haxelib run hlbox3d install <dir>
No compiler is needed. For the browser, --web <dir> fetches box3d.js
and box3d.wasm instead, see docs/web.md.
Verify the installation
Add -lib hlbox3d to your hxml, put the first world below in Main.hx and run
it with hl. A crate falls on a floor.
🌍 First world
Inside an hxd.App, where s3d is the scene and dt the frame time:
var world = new box3d.World();
world.setGravity(0, 0, -10);
world.addBox(20, 20, 0.5, 0, 0, -0.5, Static).attach(s3d); // a floor
world.addBox(0.4, 0.4, 0.4, 0, 0, 3).attach(s3d); // a crate above it
// once a frame
world.update(dt); // steps at a fixed rate and moves what it draws
attach gives a body one mesh per shape under the object you pass;
replace body.object with your own model whenever you have one. Box
sizes are half extents, as in Box3D. docs/first_world.md
is the complete program with what each line does; everything past it,
from joints to queries to characters, starts at docs/overview.md.
🎮 Sample
samples/Main.hx is the complete program: a floor, a hundred spheres and boxes falling on it, an orbit camera, Space to start over, and the bodies still awake in the window title as the pile settles. The same file builds to both targets.
HashLink:
cd samples && haxe sample.hxml
cd ../build/samples && hl sample.hl # with box3d.hdll and sdl.hdll beside hl
Browser:
cd samples && haxe sample_js.hxml
haxelib run hlbox3d install --web ../build/samples-web
cp sample.html ../build/samples-web/
then serve build/samples-web over http and open sample.html; a page
cannot fetch the wasm from file://.
🌐 Web
The same shim compiled to wasm, box3d.js and box3d.wasm, for Haxe's
JavaScript target. Using them needs nothing beyond haxe -js:
haxelib run hlbox3d install --web <dir> puts both files where the page
is. Load box3d.js by a script tag before your own, and wait for the
module before the first world:
box3d.Wasm.load().then(_ -> new Main());
Everything else is the same code on both. Building the module yourself is under Working on it below.
📖 Documentation
- docs/overview.md: where to start, units and axes, which classes a game uses.
- docs/first_world.md: the complete first program, line by line.
- docs/simulation.md: the world, bodies and shapes, stepping, forces, sleep, events, joints.
- docs/collision.md: hulls, meshes, height fields, compounds; rays, casts, overlaps; collision without a world.
- docs/drawing.md: what
attachdraws, and drawing a body yourself. - docs/character.md: the capsule mover and the ragdoll.
- docs/recording.md: recording a world and replaying it.
- docs/loose_ends.md: user data, coordinates, lifetimes, threads, Box3D's limits.
- docs/faq.md: the questions and the mistakes everyone makes once.
- docs/web.md, docs/large_worlds.md, docs/tests.md.
- docs/reference.md: every public member of every class, with its doc line.
- CHANGELOG.md: what changed in each release.
🛠️ Working on it
For a change to the binding, or a Box3D newer than the release.
Build from source
CMake fetches Box3D and HashLink itself, nothing to clone by hand; the
same commands on Windows and Linux. Linux wants build-essential cmake git
first, Windows a Visual Studio with C.
git clone https://github.com/StepanZaletskiy/hlbox3d
cd hlbox3d
cmake -S . -B build && cmake --build build --config Release
haxelib dev hlbox3d .
haxelib run hlbox3d install
haxelib dev points the library at the checkout, so every rebuild is
what the game runs. The shim is src/box3d_hl.c, the Haxe side
src/box3d. -DHLBOX3D_LARGE_WORLD=ON configures the double-precision
module, into a build directory of its own. Box3D's assertions come with
the configuration, as they do for Box3D itself: --config RelWithDebInfo
keeps them in the module, Release drops them.
Build the web module
Takes the Emscripten SDK, the C-to-wasm compiler, the way the module for HashLink takes a C compiler. Once, anywhere, then activate it in the shell that builds:
git clone https://github.com/emscripten-core/emsdk
cd emsdk
./emsdk install latest && ./emsdk activate latest # emsdk.bat on Windows
source ./emsdk_env.sh # emsdk_env.bat on Windows
That puts emcc, emcmake and node on PATH. The build wants
Ninja too, one file,
since Visual Studio's generator cannot drive emcc. Then, from the library:
emcmake cmake -S . -B build-web -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-web
CI does the same in the web job, so a change to the shim is tried
there even on a machine without the SDK.
Run the checks
Box3D's own unit tests, through the binding, on whichever module the build directory holds; on the web build they run under node:
cmake --build build --config Release --target check
cmake --build build-web --target check
docs/tests.md says how to compare the output with Box3D's own test run.
🤝 Found a bug? Missing a feature?
File an issue on StepanZaletskiy/hlbox3d, with a recording if the world misbehaves: world.record writes one, and it replays exactly, see docs/recording.md. If you already have the fix, a pull request is welcome; the shim follows Box3D's own style and the Haxe side follows Heaps', and cmake --build build --target check must stay green.
✅ Requirements
hlbox3d needs Haxe 4.3 or later. A desktop game needs HashLink 1.16, the version the module is built against, and Heaps; a browser game needs only a browser with WebAssembly. Without Heaps on the class path the physics compiles alone with -D box3d_no_heaps. The Box3D inside is the commit pinned in CMakeLists.txt.
📘 License
hlbox3d is released under the terms of the MIT License. Box3D is MIT.