Box2Dxt — Box2D v3 physics for OpenXTalk

Box2Dxt wraps the real Box2D v3 physics engine and exposes it to OpenXTalk (OXT) — and the wider xTalk language family — as a loadable extension. You get Box2D's full feature set (joints, continuous collision, island sleep, the Soft Step solver) at native speed, and you render the results with ordinary OpenXTalk graphics.

Built for OpenXTalk, compatible with LiveCode. Box2Dxt is designed in and for OpenXTalk, but because OXT shares the xTalk/.lcb/.livecodescript formats it also runs unchanged in LiveCode 9.6.3+.

on openCard
   b2kQuickStart                          -- world + gravity + card-edge walls + go
   get b2kSpawnBall(200, 80, 50)          -- drop a 50px ball
   get b2kSpawnBox(260, 80, 60, 40, "orange")
end openCard
on mouseDown ; get b2kGrab(the mouseH, the mouseV) ; end mouseDown
on mouseUp   ; b2kRelease ; end mouseUp
on closeCard ; b2kStop ; end closeCard

That's a full, draggable, gravity-driven physics scene — see Getting Started to run it.

---

Contents

• What's in the box
• How it fits together
• Quick start
• Prebuilt libraries
• Build from source
• Documentation
• Repository layout
• Contributing
• License & credits

---

What's in the box

Piece	File	What it is
Native module	src/box2d_lc.c + Box2D	A thin C shim compiled with Box2D into one shared library, box2dxt.
Extension	src/box2dxt.lcb	The xTalk Builder (LCB) library: foreign handler bindings wrapped in friendly b2… handlers.
The Kit	src/box2dxt-kit.livecodescript	A batteries-included, pure-xTalk helper (b2k…) that works in pixels/degrees and hides the loop.
Demo	examples/box2dxt-demo.livecodescript	A self-building, multi-scene testbed showing every feature.
Contraption Builder	examples/box2dxt-contraption-builder.livecodescript	An interactive GUI: drop parts (incl. images) and terrain, wire up joints + motors, then Run.
Prebuilt binaries	prebuilt/	Drop-in native libraries so you can run without a toolchain.

There are two layers you can call:

• The Kit (b2k…) — the friendly way. Pixels, screen coordinates, degrees; it owns the world and the fixed-timestep loop and moves your controls for you. Start here. → Kit reference
• The core API (b2…) — the full, low-level Box2D surface in metres and radians. Reach for it when you need something the Kit doesn't expose. → API reference

How it fits together

There are three pieces. Box2D v3 is the upstream engine (a full C rewrite with a handle-based API). src/box2d_lc.c is a thin C shim: Box2D's identifiers are small structs passed by value, and the LCB FFI prefers plain scalars, so the shim stores every Box2D id in a handle table and hands the script a simple 1-based integer instead, with all reals crossing as double and booleans as int. The shim and Box2D compile together into one shared library, box2dxt. src/box2dxt.lcb is the extension: it declares foreign handler bindings to the shim's symbols and wraps them in public b2… handlers that xTalk can call directly. You keep your own simulation loop and draw each body with OpenXTalk controls (the Kit and demo show the pattern).

Every handle is validated before use (Box2D v3 ids carry a generation counter), so calling any handler with a stale, destroyed, or never-created handle is a harmless no-op — getters return 0, actions do nothing — instead of crashing the engine. That makes the binding safe to drive from a high-level scripting environment where stale references happen.

For the full design walkthrough, see docs/architecture.md.

Quick start

1. Get a native library for your platform (no toolchain needed) — see Prebuilt libraries — and place it next to your stack, renamed to the bare name (libbox2dxt.so / libbox2dxt.dylib / box2dxt.dll).
2. Load the extension src/box2dxt.lcb (IDE: Tools → Extension Manager, or from script load extension from file).
3. Add the Kit: paste src/box2dxt-kit.livecodescript into your stack/card script, then use the openCard/mouseDown snippet at the top of this README.

Full walkthrough, sanity checks, and the "attach controls you designed in the IDE" path: docs/getting-started.md.

Prebuilt libraries (no toolchain needed)

Grab a library from prebuilt/ (committed for convenience) or from the per-tag Releases (built and tested on native runners):

Platform	File
Linux x86-64	prebuilt/linux-x86_64/libbox2dxt.so
macOS (Intel + Apple Silicon)	prebuilt/libbox2dxt-macos-universal.dylib
Windows x64	prebuilt/box2dxt-windows-x64.dll

Rename the file to the bare platform name (libbox2dxt.so / libbox2dxt.dylib / box2dxt.dll) when you deploy — that's what the c:box2dxt>… binding strings resolve to. Details: prebuilt/README.md.

Build from source

You need a C toolchain and CMake 3.22+. CMake fetches Box2D automatically.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

This produces one shared library (libbox2dxt.so / libbox2dxt.dylib / box2dxt.dll). Per-platform notes, the optional test build, and CPU/SIMD options are in docs/building.md.

Documentation

Doc	What you'll find
Getting Started	Install, load, and run your first scene step by step.
Kit Reference	The friendly b2k… API (pixels/degrees).
API Reference	The full low-level b2… API (metres/radians).
Building	Build from source on every platform, run the tests.
Architecture	How the shim, handle tables, and binding work — and how to extend them.
Changelog	Notable changes per release.
Contributing	Dev setup, conventions, and how to add a handler.

Repository layout

Box2Dxt/
├── src/
│   ├── box2d_lc.c                  # C shim (compiles with Box2D -> box2dxt)
│   ├── box2dxt.lcb                 # xTalk Builder extension (b2… handlers)
│   └── box2dxt-kit.livecodescript  # the Kit (b2k… pixel/degree helpers)
├── examples/
│   ├── box2dxt-demo.livecodescript # self-building multi-scene testbed
│   └── box2dxt-contraption-builder.livecodescript # interactive build-a-machine GUI
├── docs/                           # all guides and references
├── tests/
│   └── smoke_test.c                # runtime smoke test (ctest)
├── prebuilt/                       # drop-in native libraries
├── CMakeLists.txt                  # build (fetches Box2D v3.1.0)
└── .github/workflows/build.yml     # CI: build + test + release on all platforms

Contributing

Contributions are welcome! See CONTRIBUTING.md for dev setup, coding conventions, and a step-by-step recipe for exposing more of Box2D. By participating you agree to abide by our Code of Conduct.

License & credits

Box2Dxt is released under the MIT License.

• Box2D © Erin Catto — also MIT. Fetched and statically linked at build time; pinned to v3.1.0.
• OpenXTalk — the open-source xTalk development environment Box2Dxt is built for.

Box2Dxt is an independent project and is not affiliated with or endorsed by Erin Catto, the OpenXTalk project, or LiveCode Ltd.