Box3DUnreal: Chaos stays enabled while Box3D does the simulating

The clone needs submodules and the plugin is one level down

Installation is a clone with submodules and a copy:

git clone --recurse-submodules https://github.com/alattanzio/Box3DUnreal.git

The plugin folder then goes in one of two places. At the project level it is <Project>/Plugins/Box3DUnreal. At the engine level it is <UnrealEngine>/Engine/Plugins/Box3DUnreal, and if it is not enabled automatically you enable it from the Plugins window in the Unreal Editor. After that you generate project files and build your project.

The engine-level route is the one that catches people. It puts the plugin outside your project, so it affects every project on that engine install, and it survives a project re-clone, which is useful until you forget it is there and debug the wrong copy.

One layout detail: the repository root holds .gitignore, .gitmodules, LICENSE, README.md and a Box3DUnreal/ directory, so a fresh clone gives you a folder that contains the plugin folder rather than being the plugin itself. The documented destination path assumes you copy the inner one.

The first build runs CMake once and caches the library

Nothing extra is required for the library itself: the first build compiles Box3D and links it, and that section only matters when you want control over how.

What happens is that Box3DUnreal.Build.cs runs CMake on the vendored submodule once, caches the result under ThirdParty/Intermediate/<Platform>/, and reuses it on every later build. Deleting that folder forces a rebuild, which is the escape hatch when a stale library is in the way.

CMake is resolved in a specific order, and the order matters more than it looks. First BOX3D_CMAKE, a full path to a specific executable. Then the CMake that ships with Unreal Engine, at Engine/Extras/ThirdPartyNotUE/CMake, described as the same one Epic's own third party build scripts use. Then cmake on PATH. Then Visual Studio's bundled CMake from the C++ CMake tools component, and finally a standalone install.

The caveat on step two is the useful detail: a source build of the engine has that CMake, but an Epic Games Launcher install ships only the licence notice for it, so on a Launcher engine the fallbacks apply and a machine with no CMake anywhere fails at this point.

A prebuilt drop skips CMake but not the layout

The alternative to building Box3D is pointing the plugin at a static library that already exists, which is the route for a machine with no CMake or for a binary checked into your own game repository.

Two ways to do it. Either set the environment variable:

BOX3D_PREBUILT_DIR=<path to the drop>

or place the drop where the plugin looks by default, which needs no environment variable at all:

Box3DUnreal/ThirdParty/Prebuilt/<Win64|Mac|Linux>/

The expected layout names the two library names per platform, and marks headers optional:

<root>/lib/box3d.lib       (Win64)   |   <root>/lib/libbox3d.a   (Mac/Linux)
<root>/include/box3d/*.h

The include line is marked optional in the original layout, since the submodule headers are used when that directory is absent.

If the drop carries its own headers, the Box3D submodule does not have to be checked out at all, which the page notes is handy for a shallow clone without --recurse-submodules. So a binary drop plus its headers turns a recursive clone into a plain one, and that is the main reason to take this path rather than building.

The library may also sit directly in the root of the drop rather than under lib/.

Two mismatches fail at link time with a misleading error

Two things must match the plugin or the build fails, and both fail in the same unhelpful place.

The first is the C runtime. On Windows you build with /MD, the dynamic CRT, because that is what Unreal uses. A Box3D library built against the static CRT links against a different heap and does not mix.

The second is precision, and it is the more interesting of the two. The plugin assumes double precision, which is what this repository's ThirdParty/CMakeLists.txt produces. A single precision library needs BOX3D_PREBUILT_PRECISION=float, and if you do not set it, Box3D's own ABI guard rejects the link on the symbol b3CreateWorldDoublePrecision.

That error names an obscure entry point rather than saying precision mismatch, so anyone integrating this by hand should expect to spend time reading Box3D's source before they read the plugin's. The guard is deliberate, and the environment variable is the documented override.

Everything else about a prebuilt drop is layout only. These two are the ones that turn a working binary into an unexplained link failure.

Chaos keeps running, it just never sees the object

The compatibility story is stated in three sentences and it is unusual enough to be worth quoting closely. Chaos Physics remains enabled in Unreal Engine, but the object is not simulated by Chaos. From Chaos' perspective, the mesh remains static. And if you want Chaos to completely ignore the object, set the Collision Profile to No Collision.

So this is coexistence rather than replacement. You get two physics worlds in the same project, with an object that Box3D moves and that Unreal treats as an immovable piece of level geometry.

That has consequences beyond the physics. Anything in Unreal that queries Chaos for a hit against this object gets an answer about a static mesh, not about the simulation, so a ray trace or an overlap query in Chaos will not follow the body once Box3D has moved it. Queries against the Box3D world are the ones that see the truth, and the plugin exposes raycasts, overlaps and shape casts against it.

Collision setup is separate and short: if Convex is selected, Box3D imports the static mesh's simple collision geometry and uses that for the simulation.

Hit has a speed threshold, contact does not

Physics events work the way they do in Chaos: tick a checkbox on the Box3DBody Component, then bind the matching event in the actor's Blueprint graph. Five checkboxes and the events they produce:

Simulation Generates Hit Events fires On Box3D Hit. Generate Contact Events fires On Box3D Begin Contact and On Box3D End Contact. Generate Overlap Events fires On Box3D Begin Overlap and On Box3D End Overlap. Is Trigger turns the body into a trigger volume that never blocks. Generate Sleep Events fires On Box3D Sleep and On Box3D Wake.

The distinction that decides which one you want is stated directly. Hit only fires for collisions above a speed threshold, and it carries the impact location, the normal and the closing speed, which is what lets you scale damage, sound or decals by how hard the impact was. Contact fires for every touch, however gentle, so it is for when the touch itself is the point.

That threshold is inherited from Box3D rather than chosen by the plugin author, and it is the kind of behaviour that silently changes a game feel: a slow nudge against a wall produces a contact event and no hit event, and code written against Chaos will not always hear about it.

Overlap needs the checkbox on both bodies, and triggers must not be Dynamic

Two event behaviours differ from Chaos, both inherited from Box3D, and both are the kind of detail that costs an afternoon if you learn them at runtime.

The first is asymmetric. Hit and contact only need the checkbox on one of the two bodies, so a prop can hear about hitting level geometry that has no events of its own. Overlap needs it on both. A trigger is blind to anything without Generate Overlap Events, so you tick it on the trigger and on whatever should be detected.

That is the asymmetry to remember: two checkboxes for a trigger to see anything, one for a solid to hear about a hit.

The second rule is about the trigger body itself. A trigger should be Static or Kinematic, because a Dynamic one never collides. The sentence explaining why is cut off in what is readable here, but the rule is unambiguous, and a Dynamic trigger volume is a configuration that fails silently rather than loudly.

Beyond events the plugin covers joints, spherical, revolute, prismatic and weld, with limits, motors, springs and breaking, ragdolls built from a skeletal mesh's existing Physics Asset rather than a new asset, a kinematic character controller with spring-based ground contact, and profiling through stat box3d alongside Box3D's own debug renderer.

Early development, with a physics engine author and a game attached

The status line is not decoration. The plugin is marked early development, focused on the core Box3D integration, with APIs, features and documentation still to evolve.

The reason to care is the pedigree. Box3D was created by Erin Catto and is described as a lightweight engine used in many games and simulations, and the stated reason to bring it into Unreal at all is Chaos. The cases named are a lightweight physics solution, deterministic simulation, custom gameplay physics systems, and experimentation with alternative engines. Determinism is the one an Unreal team cannot get from the built-in world, and ragdolls plus a spring-based kinematic controller are the two features most people actually want from a second engine.

The author is a Principal Engineer at Empty Vessel working on DEFECT, a multiplayer immersive action game on Steam, and the founder of Mental Drink, an independent studio. So the plugin has a consumer, which is the best argument for it settling.

Licensing is MIT, the default branch is main, there are no GitHub releases, and the last push is dated 27 September 2026. With no version tags, the commit you build from is the version, so keep a record of it.

Editorial conclusion

Box3DUnreal is worth building against if you need deterministic Box3D simulation inside an Unreal project and have accepted that Chaos will remain on but will not touch the object. It is a young plugin, marked early development with APIs and documentation still moving, so pin your own copy rather than tracking the branch. Before you build, decide how Box3D gets linked: the CMake path needs one of four resolvable CMake installations, the prebuilt path needs the CRT and precision to match, and the latter is the one that produces a link error you will read as a compiler problem.

Frequently asked questions

Official sources

1. alattanzio/Box3DUnreal on GitHub
2. Issues
3. License: MIT
4. README