box3d/docs/faq.md
Erin Catto f42be210a2
64-bit hashes (#126)
- ContactEvent sample
- Improved shadows
- #120 
- Triangle collision fixes
2026-08-11 18:08:34 -07:00

8.2 KiB

FAQ

What is Box3D?

Box3D is a feature rich 3D rigid body physics engine, written in C17 by Erin Catto. It has been used in games and game engines as a 3D counterpart to the well-established Box2D engine.

Box3D uses the MIT license and can be used free of charge. Credit should be included if possible. Support is appreciated.

What platforms does Box3D support?

Box3D is developed using C17. It is portable and can be compiled for any platform with a conforming C17 compiler.

Erin Catto maintains the C version. Community ports and bindings for other languages are not officially supported.

Who makes it?

Erin Catto is the creator and primary author of Box3D. It is an open source project, and accepts community feedback via GitHub Issues and GitHub Discussions.

How do I get help?

You should read the documentation and the rest of this FAQ first. Also, you should study the examples included in the source distribution. Then you can visit the Discord to ask any remaining questions.

Please do not message or email Erin Catto directly for support. It is best to ask questions on the Discord server so that everyone can benefit from the discussion.

Documentation

Why isn't a feature documented?

If you grab the latest code from the git main branch you will likely find features that are not documented in the manual. New features are added to the manual after they are mature and a new point release is imminent. However, all major features added to Box3D are accompanied by example code in the samples application to test the feature and show the intended usage.

Prerequisites

Programming

You should have a working knowledge of C before you use Box3D. You should understand functions, structures, and pointers. There are plenty of resources on the web for learning C. You should also understand your development environment: compilation, linking, and debugging.

Math and Physics

You should have a basic knowledge of rigid bodies, force, torque, and impulses. In 3D you will also encounter quaternions for orientation and 3x3 inertia tensors for rotational dynamics. If you come across a math or physics concept you don't understand, please read about it on Wikipedia. Visit this page if you want a deeper knowledge of the algorithms used in Box3D.

Working with Unreal

You can use Box3D in Unreal as a plug-in. Here is the module file I use:

Box3D module

Unreal uses centimeters as units while Box3D has tolerances tuned for meters. You can either scale dimensions you send and recieve from Box3D or you can use this to set the length units:

b3SetLengthUnitsPerMeter(100.0f);

This doesn't scale the units. Instead it scales the tolerances used internally in Box3D to be more appropriate for centimeters.

Another issue is that Box3D is right-handed while Unreal is left-handed. Box3D has way too much math for it to be reasonable to support a left-handed option. However, it doesn't matter. In practice you don't need to do any conversions. Box3D will run in a mirrored world and the outputs from Box3D are fully compatible with the Unreal coordinates.

I would just be careful about using Box3D math functions like b3Cross and expecting it to give the same result as the Unreal cross product.

API

What units does Box3D use?

Box3D is tuned for meters-kilograms-seconds (MKS). This is recommended as the unit system for your game. However, you may use different units if you are careful. Call b3SetLengthUnitsPerMeter() at startup to change the length unit.

What coordinate system does Box3D use?

Box3D has no built-in notion of up. The gravity vector in b3WorldDef can point in any direction. The default is (0, -10, 0) (negative Y is down) but you can set it to whatever suits your application.

Why don't you use this awesome language?

Box3D is designed to be portable and easy to wrap with other languages, so I decided to use C17. I used C17 to get support for atomics.

Can I use Box3D in a DLL?

Yes. See the CMake option BUILD_SHARED_LIBS.

Is Box3D thread-safe?

No. Box3D will likely never be fully thread-safe from the outside. Box3D has a large API and trying to make such an API thread-safe would have a large performance and complexity impact. However, you can call read-only functions from multiple threads. For example, all the spatial query functions are read-only.

Box3D does use multithreading internally during b3World_Step. You supply your own task system via the enqueueTask and finishTask callbacks in b3WorldDef.

Build Issues

There are many reasons why a build can go bad. Here are a few that have come up:

  • Using old Box3D headers with new code
  • Not linking the Box3D library with your application
  • Using old project files that don't include some new source files

Rendering

What are Box3D's rendering capabilities?

Box3D is only a physics engine. How you draw stuff is up to you.

But the samples application draws stuff

Visualization is very important for debugging collision and physics. The samples application helps test Box3D and gives you examples of how to use Box3D. The samples are not part of the Box3D library.

How do I draw shapes?

Fill out a b3DebugDraw struct with your drawing callbacks and call b3World_Draw(worldId, &draw, maskBits). The mask bits let you filter which shape categories are drawn.

Accuracy

Box3D uses approximate methods for a few reasons.

  • Performance
  • Some differential equations don't have known solutions
  • Some constraints cannot be determined uniquely

What this means is that constraints are not perfectly rigid and sometimes you will see some bounce even when the restitution is zero. Box3D uses Gauss-Seidel to approximately solve constraints. Box3D also uses Semi-implicit Euler to approximately solve the differential equations. Box3D also does not have exact collision between dynamic shapes. Slow moving shapes may have small overlap for a few time steps. In extreme stacking scenarios, shapes may have sustained overlap.

Making Games

Tile / Voxel Based Environments

Using many boxes for terrain may not work well because box-like characters can get snagged on internal corners. Box3D provides capsules and convex hulls that may work better for characters. Consider the character mover API (b3World_CastMover, b3World_CollideMover) for smooth first/third person movement.

Asteroid Type Coordinate Systems

Box3D does not have any support for coordinate frame wrapping. You would likely need to customize Box3D for this purpose.

Determinism

Is Box3D deterministic?

For the same input Box3D will reproduce any simulation. Box3D does not use any random numbers nor base any computation on random events (such as timers, etc).

Box3D is also deterministic under multithreading. A simulation using two threads will give the same result as eight threads.

Box3D inherits cross-platform determinism from its design: floating-point contraction is disabled (-ffp-contract=off) and IEEE 754 arithmetic is relied upon consistently.

However, Box3D does not have rollback determinism. There is no mechanism to set a world back to a prior state and then resume simulation expecting identical results. Box3D caches a lot of internal state to improve simulation stability and performance.

But I really want determinism

This naturally leads to the question of fixed-point math. Box3D does not support fixed-point math. Fixed-point math is slower and more tedious to develop, and I have chosen not to use it.

What are the common mistakes made by new users?

  • Using non-metric units instead of meters
  • Expecting Box3D to give pixel-perfect results
  • Testing their code in release mode (always use Debug for testing — it enables assertions and validation)
  • Not learning C before using Box3D
  • Confusing b2 (Box2D) and b3 (Box3D) symbols when reading documentation