hlbox3d

Box3D physics for Heaps — HashLink and JS/WebGL
https://github.com/StepanZaletskiy/hlbox3d

To install, run:

haxelib install hlbox3d 0.1.0 

See using Haxelib in Haxelib documentation for more information.

README.md


<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

🛠️  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.

Contributors
stepanzaletskii
Version
0.1.0
Published
2 months ago
License
MIT

All libraries are free

Every month, more than a thousand developers use Haxelib to find, share, and reuse code — and assemble it in powerful new ways. Enjoy Haxe; It is great!

Explore Haxe

Haxe Manual

Haxe Code Cookbook

Haxe API documentation

You can try Haxe in the browser! try.haxe.org

Join us on GitHub!

Haxe is being developed on GitHub. Feel free to contribute or report issues to our projects.

Haxe on GitHub

⌂