Overview

Box3d is a 3D rigid body simulation library extended from 2D to 3D with reference to Erin Catto's Box2d, so the names of many classes are consistent with Box2d, such as Body, Fixture, Shape and so on.Programmers can use it to do some interesting things to make the movement of objects more realistic and more in line with real physics.

Box3D is written in C++11. Most of the types defined in the engine begin with the b3 prefix. Hopefully this can avoid name conflicts with your application.

Prerequisites

In this wiki, we assume you are familiar with basic physics concepts such as density, force, torque, and impulse. If not, please refer to relevant materials for study first.

Box3D can be used for teaching physics in middle and high schools, simulating physical phenomena such as ball collisions.

Since Box3D is written in C++, you need to have experience with C++ programming. Box3D should not be your first C++ programming project! You should be familiar with C++ project development.

Scope

This wiki covers most aspects of the Box3D API. However, it does not cover everything. Please refer to the testbed included with Box3D for more information.

This wiki is updated with the release of new versions. The latest version of Box3D might not be consistent with this wiki.

Feedback and Bugs

Please file bugs and feature requests here: Box3D Issues

If you provide enough details, we can help you resolve the related issues. A testbed example that reproduces the issue is a good option. You can read about the testbed platform later in this wiki.

Core Concepts

Box3D uses some basic concepts and objects. We briefly define these objects here, with more details provided later in this wiki.

shape

Shapes are three-dimensional geometric objects, such as spheres or cubes.

rigid body

A rigid body is an idealized solid object in which deformation is negligible, meaning that the distances between any two points within the body remain constant regardless of external forces or moments applied to it. In the context of physics simulations like Box3D, rigid bodies are used to model and simulate the behavior of solid objects that do not bend, stretch, or compress.

fixture

A fixture is a component that attaches a shape to a rigid body for collision detection. Fixtures contain a shape, density, friction, and restitution properties, and they are used to define the physical properties and behavior of a rigid body in the simulation. Fixtures are responsible for providing collision geometry, which helps the physics engine determine when and how objects collide and interact with each other.

constraint

A constraint is a rule or condition that restricts the movement of objects to enforce certain behaviors or relationships between them. Constraints are used to simulate interactions such as joints, hinges, springs, or other mechanical connections that limit the degrees of freedom of the involved objects. By applying constraints, the physics engine can ensure that the objects move in a realistic manner according to the defined relationships.

contact constraint

A contact constraint is a type of constraint used in physics simulations to prevent interpenetration between objects and to simulate realistic collisions and contacts. When two objects come into contact, a contact constraint is applied to ensure that they do not pass through each other and to calculate the appropriate reaction forces and impulses.

world

A world (or sometimes referred to as a physics world or simulation world) is the environment or container that holds and manages all the physics entities and interactions. It serves as the central hub for the simulation, orchestrating the dynamics and updates of various objects and their interactions.

solver

A solver in the context of a physics engine or simulation is a component responsible for calculating the forces, accelerations, velocities, and positions of objects over time to simulate realistic physical behavior.

continuous collision

Continuous collision refers to the technique used in physics simulations to accurately detect and handle collisions between fast-moving objects to prevent them from tunneling through each other. This is particularly important for simulations involving high-speed objects, where discrete collision detection might miss collisions due to the objects moving too quickly between frames.

Modules

Box3D consists of four modules: Common, Collision, Dynamics, and Geometry. The Common module contains code for memory allocation, mathematics, and settings. The Collision module defines shapes, broad-phase, and collision functions/queries. The Dynamics module provides simulation of worlds, bodies, and fixtures. Finally, the Geometry module defines models of the related shapes.

Units

Box3D uses floating-point numbers, so tolerances must be employed for optimal performance. These tolerances are tuned to work well with the meter-kilogram-second (MKS) units. Specifically, Box3D is calibrated to work well with moving shapes that are between 0.1 to 10 meters. This means that objects ranging in size from a pencil to a bus should function well. Static shapes can be up to 100 meters in length without issues.

As a 3D physics engine, it might be tempting to use pixels as units. However, this would result in poor simulation performance and potentially strange issues. An object that is 200 pixels long would be interpreted as the size of a 45-story building in Box3D.

It's best to think of Box3D bodies as moving billboards to which you can attach your artwork. The billboards can move in meters, but you can use a scale factor to convert to pixel coordinates. Then, you can use these pixel coordinates to place your artwork, etc.

Another limitation to consider is the overall size of the world. If your world is larger than about 2 kilometers, the loss of precision will affect the stability of the system.

Box3D uses radians to represent angles. Rotations are stored in radians, which may lead to angles growing indefinitely. If the magnitude of the angles becomes too large, consider normalizing the angles of the bodies.

Factories and Definitions

Efficient memory management plays a central role in the design of the Box3D API. Therefore, when you create a b3_Body, you need to call the factory function on b3_World. You should not attempt to allocate these types in any other way.

There are creation functions:

b3Body* create_body(const b3BodyDef& def);

When you create a body, you need to provide a definition. These definitions contain all the information needed to construct the body. By using this approach, we can prevent construction errors, keep the number of function parameters low, provide reasonable default values, and reduce the number of accessors.

Since fixtures (shapes) must be associated with a body, fixtures are created and destroyed using factory methods on b3Body:

b3Fixture* create_fixture(const b3FixtureDef& def);

void destroy_fixtures();