Rigid body simulation is the primary feature of Box3D. It is the most complex part of Box3D and is the part you will likely interact with the most. Simulation sits on top of the foundation and collision layers, so you should be somewhat familiar with those by now.
Rigid body simulation contains:
There are many dependencies between these objects so it is difficult to describe one without referring to another. In the following, you may see some references to objects that have not been described yet. Therefore, you may want to quickly skim this section before reading it closely.
Box3D has a C interface. Typically in a C/C++ library when you create an object with a long lifetime you will keep a pointer (or smart pointer) to the object.
Box3D works differently. Instead of pointers, you are given an id when you create an object. This id acts as a handle which helps avoid problems with dangling pointers.
This also allows Box3D to use data-oriented design internally. This helps to reduce cache misses drastically and also allows for SIMD optimizations.
So you will be dealing with b3WorldId, b3BodyId, etc. These are small opaque structures that you will pass around by value, just like pointers. Box3D creation functions return an id. Functions that operate on Box3D objects take ids.
There are functions to check if an id is valid. Box3D functions will assert if you use an invalid id. This makes debugging easier than using dangling pointers.
Null ids can be established in a couple of ways. You can use predefined constants or zero initialization.
You can test if an id is null using some helper macros:
The Box3D world contains the bodies and joints. It manages all aspects of the simulation and allows for asynchronous queries (like AABB queries and ray-casts). Much of your interactions with Box3D will be with a world object, using b3WorldId.
Worlds are created using a definition structure. This is a temporary structure that you can use to configure options for world creation. You must initialize the world definition using b3DefaultWorldDef().
The world definition has lots of options, but for most you will use the defaults. You may want to set the gravity:
Box3D has no built-in concept of an up direction. Gravity is simply a b3Vec3 applied to every dynamic body each step.
If your game doesn't need sleep, you can get a performance boost by completely disabling sleep:
You can also configure multithreading to improve performance:
Multithreading is not required but it can improve performance substantially.
Creating a world is done using a world definition.
You can create up to 128 worlds. These worlds do not interact and may be simulated in parallel.
When you destroy a world, every body, shape, and joint is also destroyed. This is much faster than destroying individual objects.
The world is used to drive the simulation. You specify a time step and a sub-step count. For example:
After the time step you can examine your bodies and joints for information. Most likely you will grab the position off the bodies so that you can update your game objects and render them. Or more optimally, you will use b3World_GetBodyEvents().
You can perform the time step anywhere in your game loop, but you should be aware of the order of things. For example, you must create bodies before the time step if you want to get collision results for the new bodies in that frame.
You should use a fixed time step. By using a larger time step you can improve performance in low frame rate scenarios. But generally you should use a time step of 1/30 seconds (30Hz) or smaller. A time step of 1/60 seconds (60Hz) will usually deliver a high quality simulation.
The sub-step count is used to increase accuracy. By sub-stepping the solver divides up time into small increments and the bodies move by a small amount. This allows joints and contacts to respond with finer detail. The recommended sub-step count is 4. However, increasing the sub-step count may improve accuracy. For example, long joint chains will stretch less with more sub-steps.
Rigid bodies, or just bodies, have position and velocity. You can apply forces, torques, and impulses to bodies. Bodies can be static, kinematic, or dynamic.
A 3D rigid body has 6 degrees of freedom: 3 translational (position along x, y, z) and 3 rotational (rotation about x, y, z axes). Orientation is represented as a quaternion (b3Quat), and angular velocity and torque are both b3Vec3 quantities.
Here are the body type definitions:
b3_staticBody: A static body does not move under simulation and behaves as if it has infinite mass. Internally, Box3D stores zero for the mass and the inverse mass. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies.
b3_kinematicBody: A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. A kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box3D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other kinematic or static bodies. Generally you should use a kinematic body if you want a shape to be animated and not affected by forces or collisions.
b3_dynamicBody: A dynamic body is fully simulated and moves according to forces and torques. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass.
Caution: Generally you should not set the transform on bodies after creation. Box3D treats this as a teleport and may result in undesirable behavior and/or performance problems.
Bodies carry shapes and move them around in the world. Bodies are always rigid bodies in Box3D. That means two shapes attached to the same rigid body never move relative to each other, and shapes attached to the same body don't collide.
Shapes have collision geometry and density. Normally, bodies acquire their mass properties from the shapes. However, you can override the mass properties after a body is constructed.
You usually keep ids to all the bodies you create. This way you can query the body positions to update the positions of your graphical entities. You should also keep body ids so you can destroy them when you are done with them.
Before a body is created you must create a body definition (b3BodyDef). The body definition holds the data needed to create and initialize a body correctly.
Because Box3D uses a C API, a function is provided to create a default body definition.
This ensures the body definition is valid and this initialization is mandatory.
Box3D copies the data out of the body definition; it does not keep a pointer to the body definition. This means you can recycle a body definition to create multiple bodies.
As discussed previously, there are three different body types: static, kinematic, and dynamic. b3_staticBody is the default. You should establish the body type at creation because changing the body type later is expensive.
You can initialize the body position and orientation in the body definition. This has far better performance than creating the body at the world origin and then moving the body.
Caution: Do not create a body at the origin and then move it. If you create several bodies at the origin, then performance will suffer.
A body has two main points of interest. The first point is the body's origin. Shapes and joints are attached relative to the body's origin. The second point of interest is the center of mass. The center of mass is determined from the mass distribution of the attached shapes or is explicitly set using b3MassData. Much of Box3D's internal computations use the center of mass position. For example the body stores the linear velocity for the center of mass, not the body origin.
When you are building the body definition, you may not know where the center of mass is located. Therefore you specify the position of the body's origin. You may also specify the body's orientation as a b3Quat. If you later change the mass properties of the body, then the center of mass may move on the body, but the origin position and orientation do not change and the attached shapes and joints do not move.
To read the axis and angle back from a quaternion:
A rigid body is a frame of reference. You can define shapes and joints in that frame. Those shapes and joint anchors never move in the local frame of the body.
Damping is used to reduce the world velocity of bodies. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and the two effects are used together.
Damping parameters are non-negative. Normally you will use a damping value between 0 and 1. Linear damping is generally undesirable because it makes bodies look like they are floating.
Damping is approximated to improve performance. At small damping values the damping effect is mostly independent of the time step. At larger damping values, the damping effect will vary with the time step. This is not an issue if you use a fixed time step (recommended).
You can use the gravity scale to adjust the gravity on a single body. Be careful though, a large gravity magnitude can decrease stability.
When a body comes to rest, Box3D can stop simulating it to save CPU time. This is called sleeping. When Box3D determines that a body (or group of bodies) has come to rest, the body enters a sleep state which has very little CPU overhead. If a body is awake and collides with a sleeping body, then the sleeping body wakes up. Bodies will also wake up if a joint or contact attached to them is destroyed. You can also wake a body manually.
The body definition lets you specify whether a body can sleep and whether a body is created sleeping.
The isAwake flag is ignored if enableSleep is false.
In 3D you sometimes want to restrict a body to a subset of its six degrees of freedom. For example, you might want a door hinge that only rotates about the Y axis, or a platform that only translates along X. Box3D provides b3MotionLocks for this:
You can also update locks after creation:
Locking all three angular axes is equivalent to fixing the rotation entirely.
Game simulation usually generates a sequence of transforms that are played at some frame rate. This is called discrete simulation. In discrete simulation, rigid bodies can move by a large amount in one time step. If a physics engine doesn't account for the large motion, you may see some objects incorrectly pass through each other. This effect is called tunneling.
By default, Box3D uses continuous collision detection (CCD) to prevent dynamic bodies from tunneling through static bodies. This is done by sweeping shapes from their old position to their new positions. The engine looks for new collisions during the sweep and computes the time of impact (TOI) for these collisions. Bodies are moved to their first TOI at the end of the time step.
Normally CCD is not used between dynamic bodies. This is done to keep performance reasonable. In some game scenarios you need dynamic bodies to use CCD. For example, you may want to shoot a high speed bullet at a stack of dynamic bricks. Without CCD, the bullet might tunnel through the bricks.
Fast moving objects in Box3D can be configured as bullets. Bullets will perform CCD with all body types, but not other bullets. You should decide what bodies should be bullets based on your game design. If you decide a body should be treated as a bullet, use the following setting.
The bullet flag only affects dynamic bodies. Bullets should be used sparingly.
You may wish a body to be created but not participate in collision or simulation. This state is similar to sleeping except the body will not be woken by other bodies and the body's shapes will not collide with anything. This means the body will not participate in collisions, ray casts, etc.
You can create a body as disabled and later enable it.
Joints may be connected to disabled bodies. These joints will not be simulated. You should be careful when you enable a body that its joints are not distorted.
Note that enabling a body is almost as expensive as creating the body from scratch. So you should not use body disabling for streaming worlds. Instead, use creation/destruction for streaming worlds to save memory.
User data is a void pointer. This gives you a hook to link your application objects to bodies. You should be consistent to use the same object type for all body user data.
This is useful when you receive results from a query such as a ray-cast or event and you want to get back to your game object. You can acquire the user data from a body using b3Body_GetUserData().
Bodies are created and destroyed using a world id. This lets the world create the body with an efficient allocator and add the body to the world data structure.
Box3D does not keep a reference to the body definition or any of the data it holds (except user data pointers). So you can create temporary body definitions and reuse the same body definitions.
Box3D allows you to avoid destroying bodies by destroying the world directly using b3DestroyWorld(), which does all the cleanup work for you. However, you should be mindful to nullify body ids that you keep in your application.
When you destroy a body, the attached shapes and joints are automatically destroyed. This has important implications for how you manage shape and joint ids. You should nullify these ids after destroying a body.
After creating a body, there are many operations you can perform on the body. These include setting mass properties, accessing position and velocity, applying forces, and transforming points and vectors.
A body has mass (scalar), center of mass (b3Vec3), and a rotational inertia tensor (b3Matrix3). For static bodies, the mass and rotational inertia are set to zero. When all angular motion locks are active, the rotational inertia is effectively zero.
Normally the mass properties of a body are established automatically when shapes are added to the body. You can also adjust the mass of a body at run-time. This is usually done when you have special game scenarios that require altering the mass.
After setting a body's mass directly, you may wish to revert to the mass determined by the shapes. You can do this with:
The body's mass data is available through the following functions:
There are many aspects to the body's state. You can access this state data through the following functions:
Please see the comments on these functions for more details.
You can access the position and orientation of a body. This is common when rendering your associated game object. You can also set the position and orientation, although this is less common since you will normally use Box3D to simulate movement.
You can access the center of mass position in local and world coordinates. Much of the internal simulation in Box3D uses the center of mass. However, you should normally not need to access it. Instead you will usually work with the body transform. For example, you may have a body that is a box. The body origin might be a corner of the box, while the center of mass is located at the center of the box.
You can access the linear and angular velocity. The linear velocity is for the center of mass. The angular velocity is a b3Vec3 whose direction is the axis of rotation and whose magnitude is the rotation rate in radians per second.
You can drive a body to a specific transform. This is useful for kinematic bodies.
You can apply forces, torques, and impulses to a body. When you apply a force or an impulse, you can provide a world point where the load is applied. This often results in a torque about the center of mass.
All force, torque, and impulse values are b3Vec3 in world space. Applying a force, torque, or impulse optionally wakes the body. If you don't wake the body and it is asleep, then the force or impulse will be ignored.
You can also apply a force and linear impulse to the center of mass to avoid rotation.
Caution: Since Box3D uses sub-stepping, you should not apply a steady impulse for several frames. Instead you should apply a force which Box3D will spread out evenly across the sub-steps, resulting in smoother movement.
The body has some utility functions to help you transform points and vectors between local and world space. If you don't understand these concepts, I recommend reading "Essential Mathematics for Games and Interactive Applications" by Jim Van Verth and Lars Bishop.
You can access the shapes on a body. You can get the number of shapes first.
If you have bodies with many shapes, you can allocate an array or if you know the number is limited you can use a fixed size array.
You can similarly get an array of the joints on a body.
While you can gather transforms from all your bodies after every time step, this is inefficient. Many bodies may not have moved because they are sleeping. Also iterating across many bodies will have lots of cache misses.
Box3D provides b3BodyEvents that you can access after every call to b3World_Step() to get an array of body movement events. Since this data is contiguous, it is cache friendly.
The body event also indicates if the body fell asleep this time step. This might be useful to optimize your application.
A body may have zero or more shapes. A body with multiple shapes is sometimes called a compound body.
Shapes hold the following:
These are described in the following sections.
The geometry types (sphere, capsule, hull, mesh, height field) are documented in detail in collision.md. Compound shapes are documented in compound.md. This section covers the shape lifecycle and material properties.
Shapes are created by initializing a shape definition and a shape primitive. These are passed to a creation function specific to each shape type.
This creates a hull shape and attaches it to the body. You do not need to store the shape id since the shape will automatically be destroyed when the parent body is destroyed. However, you may wish to store the shape id if you plan to change properties on it later.
You can create multiple shapes on a single body. They all can contribute to the mass of the body. These shapes never collide with each other and may overlap.
You can destroy a shape on the parent body. You may do this to model a breakable object. Otherwise you can just leave the shape alone and let the body destruction take care of destroying the attached shapes.
The second argument controls whether the parent body's mass is updated immediately.
Material properties such as density, friction, and restitution are associated with shapes instead of bodies. Since you can attach multiple shapes to a body, this allows for more possible setups. For example, you can make a vehicle that is heavier in the back.
The shape density is used to compute the mass properties of the parent body. The density can be zero or positive. You should generally use similar densities for all your shapes. This will improve stacking stability.
The mass of a body is not adjusted when you set the density. You must call b3Body_ApplyMassFromShapes() for this to occur. Generally you should establish the shape density in b3ShapeDef and avoid modifying it later because this can be expensive, especially on a compound body.
Friction is used to make objects slide along each other realistically. Box3D supports static and dynamic friction, but uses the same parameter for both. Box3D attempts to simulate friction accurately and the friction strength is proportional to the normal force. This is called Coulomb friction. The friction parameter is usually set between 0 and 1, but can be any non-negative value. A friction value of 0 turns off friction and a value of 1 makes the friction strong. When the friction force is computed between two shapes, Box3D must combine the friction parameters of the two parent shapes. This is done with the geometric mean:
If one shape has zero friction then the mixed friction will be zero.
Friction is stored as part of the shape's base surface material:
Restitution is used to make objects bounce. The restitution value is usually set to be between 0 and 1. Consider dropping a ball on a table. A value of zero means the ball won't bounce. This is called an inelastic collision. A value of one means the ball's velocity will be exactly reflected. This is called a perfectly elastic collision. Restitution is combined using the following formula.
Restitution is combined this way so that you can have a bouncy super ball without having a bouncy floor.
When a shape develops multiple contacts, restitution is simulated approximately. This is because Box3D uses a sequential solver. Box3D also uses inelastic collisions when the collision velocity is small. This is done to prevent jitter. See b3WorldDef::restitutionThreshold.
Restitution is stored as part of the shape's base surface material:
Advanced users can override friction and restitution mixing using b3FrictionCallback and b3RestitutionCallback. These should be very lightweight functions because they are called frequently. The callbacks receive the two friction (or restitution) values and the user material ids from each shape's surface material.
Collision filtering allows you to efficiently prevent collision between shapes. For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Box3D supports such collision filtering using categories, masks, and groups.
Box3D supports 64 collision categories (stored as uint64_t). For each shape you can specify which category it belongs to. You can also specify what other categories this shape can collide with. For example, you could specify in a multiplayer game that players don't collide with each other. Rather than identifying all the situations where things should not collide, I recommend identifying all the situations where things should collide. This way you don't get into situations where you are using double negatives. You can specify which things can collide using mask bits. For example:
Here is the rule for a collision to occur:
Another filtering feature is collision groups. Collision groups let you specify a group index. You can have all shapes with the same group index always collide (positive index) or never collide (negative index). Group indices are usually used for things that are somehow related, like the parts of a vehicle. In the following example, shape1 and shape2 always collide, but shape3 and shape4 never collide.
Collisions between shapes of different group indices are filtered according the category and mask bits. If two shapes have the same non-zero group index, then this overrides the category and mask. Collision groups have a higher priority than categories and masks.
Note that additional collision filtering occurs automatically in Box3D. Here is a list:
Sometimes you might need to change collision filtering after a shape has already been created. You can get and set the b3Filter structure on an existing shape using b3Shape_GetFilter() and b3Shape_SetFilter(). Changing the filter is expensive because it causes contacts to be destroyed.
Sometimes game logic needs to know when two shapes overlap yet there should be no collision response. This is done by using sensors. A sensor is a shape that detects overlap but does not produce a response.
You can flag any shape as being a sensor. Sensors may be static, kinematic, or dynamic. Remember that you may have multiple shapes per body and you can have any mix of sensors and solid shapes. Sensors can also detect other sensors. Sensor shapes have mass like regular shapes. You can set the density to zero if you don't want a sensor to have mass.
For both sensors and non-sensors, sensor events must also be enabled. There is a performance cost to generate sensor events, so they are disabled by default.
Both shapes involved must have this flag set to true. This allows a game to disable a specific sensor using b3Shape_EnableSensorEvents.
Sensors are processed at the end of the world step and generate begin and end events without delay. User operations may cause overlaps to begin or end. These are processed the next time step. Such operations include:
Sensors do not detect objects that pass through the sensor shape within one time step. So sensors do not have continuous collision detection. If you have a fast moving object and/or small sensors then you should use a ray or shape cast to detect these events.
You can access the current sensor overlaps from the previous world step. Be careful because some shape ids may be invalid due to a shape being destroyed. Use b3Shape_IsValid to ensure an overlapping shape is still valid.
Sensor overlap can also be determined using events, which are described below.
Sensor events are available after every call to b3World_Step(). Sensor events are the best way to get information about sensor overlaps. There are events for when a shape begins to overlap with a sensor.
And there are events when a shape stops overlapping with a sensor. Be careful with end touch events because they may be generated when shapes are destroyed. Test the shape ids with b3Shape_IsValid.
Sensor events should be processed after the world step and before other game logic. This should help you avoid processing stale data.
Sensor events are only enabled for shapes if b3ShapeDef::enableSensorEvents is set to true.
Note: A shape cannot start or stop being a sensor. Such a feature would break sensor events, potentially causing bugs in game logic.
Contacts are internal objects created by Box3D to manage collision between pairs of shapes. They are fundamental to rigid body simulation in games.
Contacts have a fair bit of terminology that are important to review.
A contact point is a point where two shapes touch. Box3D approximates contact with a small number of points.
A contact normal is a unit vector that points from one shape to another. By convention, the normal points from shapeA to shapeB.
Separation is the opposite of penetration. Separation is negative when shapes overlap.
Contact between two convex shapes may generate multiple contact points. These points share the same normal, so they are grouped into a contact manifold, which is an approximation of a continuous region of contact.
The normal force is the force applied at a contact point to prevent the shapes from penetrating. For convenience, Box3D uses impulses. The normal impulse is just the normal force multiplied by the time step. Since Box3D uses sub-stepping, this is the sub-step time step.
The tangent force is generated at a contact point to simulate friction. For convenience, this is stored as an impulse.
Box3D tries to re-use the contact impulse results from a time step as the initial guess for the next time step. Box3D uses contact point ids to match contact points across time steps. The ids contain geometric feature indices that help to distinguish one contact point from another.
When two shapes are close together, Box3D will create contact points even if the shapes are not touching. This lets Box3D anticipate collision to improve behavior. Speculative contact points have positive separation.
Contacts are created when two shapes' AABBs (bounding boxes) begin to overlap. Sometimes collision filtering will prevent the creation of contacts. Contacts are destroyed when the AABBs cease to overlap.
So you might gather that there may be contacts created for shapes that are not touching (just their AABBs). Well, this is correct. It's a "chicken or egg" problem. We don't know if we need a contact object until one is created to analyze the collision. We could delete the contact right away if the shapes are not touching, or we can just wait until the AABBs stop overlapping. Box3D takes the latter approach because it lets the system cache information to improve performance.
As mentioned before, the contact is created and destroyed by Box3D automatically. Contact data is not created by the user. However, you are able to access the contact data.
You can get contact data from shapes or bodies. The contact data on a shape is a sub-set of the contact data on a body. The contact data is only returned for touching contacts. Contacts that are not touching provide no meaningful information for an application.
Contact data is returned in arrays. So first you can ask a shape or body how much space you'll need in your array. This number is conservative and the actual number of contacts you'll receive may be less than this number, but never more.
You could allocate array space to get all the contact data in all cases, or you could use a fixed size array and get a limited number of results.
b3ContactData contains the two shape ids and the manifold array.
Getting contact data off shapes and bodies is not the most efficient way to handle contact data. Instead you should use contact events.
Contact events are available after each world step. Like sensor events these should be retrieved and processed before performing other game logic. Otherwise you may be accessing orphaned/invalid data.
You can access all contact events in a single data structure. This is much more efficient than using functions like b3Body_GetContactData().
None of this data applies to sensors because they are handled separately. All events involve at least one dynamic body.
There are three kinds of contact events:
b3ContactBeginTouchEvent is recorded when two shapes begin touching.
b3ContactEndTouchEvent is recorded when two shapes stop touching.
Similar to b3SensorEndTouchEvent, b3ContactEndTouchEvent may be generated due to a user operation, such as destroying a body or shape. These events are included with simulation events after the next b3World_Step.
Shapes only generate begin and end touch events if b3ShapeDef::enableContactEvents is true.
Typically in games you are mainly concerned about getting contact events for when two shapes collide at a significant speed so you can play a sound and/or particle effect. Hit events are the answer for this.
Shapes only generate hit events if b3ShapeDef::enableHitEvents is true. Only enable this for shapes that need hit events because it creates some overhead. Box3D also only reports hit events that have an approach speed larger than b3WorldDef::hitEventThreshold.
Often in a game you don't want all objects to collide. For example, you may want to create a door that only certain characters can pass through. This is called contact filtering, because some interactions are filtered out.
Contact filtering is setup on shapes and is covered herehere.
For the best performance, use the contact filtering provided by b3Filter. However, in some cases you may need custom filtering. You can do this by registering a custom filter callback that implements b3CustomFilterFcn().
This function must be thread-safe and must not read from or write to the Box3D world. Otherwise you will get a race condition.
This is called after collision detection, but before collision resolution. This gives you a chance to disable the contact based on the contact geometry. For example, you can implement a one-sided platform using this callback.
The contact will be re-enabled each time through collision processing, so you will need to disable the contact every time-step. This function must be thread-safe and must not read from or write to the Box3D world.
The pre-solve callback for Box3D receives the two shape ids, the contact point, and the contact normal:
Note this currently does not work with high speed collisions, so you may see a pause in those situations.
Joints are used to constrain bodies to the world or to each other. Typical examples in games include ragdolls, teeters, and pulleys. Joints can be combined in many different ways to create interesting motions.
Some joints provide limits so you can control the range of motion. Some joints provide motors which can be used to drive the joint at a prescribed speed until a prescribed force/torque is exceeded. And some joints provide springs with damping.
Joint motors can be used in many ways. You can use motors to control position by specifying a joint velocity that is proportional to the difference between the actual and desired position. You can also use motors to simulate joint friction: set the joint velocity to zero and provide a small, but significant maximum motor force/torque. Then the motor will attempt to keep the joint from moving until the load becomes too strong.
Each joint type has an associated joint definition that embeds a b3JointDef base. All joints are connected between two different bodies. One body may be static. Joints between static and/or kinematic bodies are allowed, but have no effect and use some processing time.
If a joint is connected to a disabled body, that joint is effectively disabled. When both bodies on a joint become enabled, the joint will automatically be enabled as well. In other words, you do not need to explicitly enable or disable a joint.
You can specify user data for any joint type and you can provide a flag to prevent the attached bodies from colliding with each other. This is the default behavior and you must set collideConnected to true to allow collision between two connected bodies.
Many joint definitions require that you provide some geometric data. In Box3D joints use local frames (b3Transform localFrameA and b3Transform localFrameB) rather than anchor points. The local frame specifies both the attachment point and the orientation axes used to measure joint quantities. These frames are specified in the local space of the attached bodies. This way the joint can be specified even when the current body transforms violate the joint constraint.
Joints are created using creation functions supplied for each joint type. They are destroyed with a shared function. All joint types share a single id type b3JointId.
Here's an example of the lifetime of a revolute joint:
It is always good to nullify your ids after they are destroyed.
Joint lifetime is related to body lifetime. Joints cannot exist detached from a body. So when a body is destroyed, all joints attached to that body are automatically destroyed. This means you need to be careful to avoid using joint ids when the attached body was destroyed. Box3D will assert if you use a dangling joint id.
Caution: Joints are destroyed when an attached body is destroyed.
Fortunately you can check if your joint id is valid.
Many simulations create the joints and don't access them again until they are destroyed. However, there is a lot of useful data contained in joints that you can use to create a rich simulation.
First of all, you can get the type, bodies, local frames, and user data from a joint.
All joints have a reaction force and torque. Reaction forces are related to the free body diagram. The Box3D convention is that the reaction force is applied to body B at the anchor point. You can use reaction forces to break joints or trigger other game events. These functions may do some computations, so don't call them if you don't need the result.
One of the simplest joints is a distance joint which says that the distance between two anchor points on two bodies must be constant. When you specify a distance joint the two bodies should already be in place. Then you specify the two anchor points via local frames. These points imply the length of the distance constraint.
Here is an example of a distance joint definition:
The distance joint can also be made soft, like a spring-damper connection. Softness is achieved by enabling the spring and tuning two values in the definition: Hertz and damping ratio.
The hertz is the frequency of a harmonic oscillator (like a guitar string). Typically the frequency should be less than a half the frequency of the time step. So if you are using a 60Hz time step, the frequency of the distance joint should be less than 30Hz. The reason is related to the Nyquist frequency.
The damping ratio controls how fast the oscillations dissipate. A damping ratio of one is critical damping and prevents oscillation.
It is also possible to define a minimum and maximum length for the distance joint. You can even motorize the distance joint to adjust its length dynamically. See b3DistanceJointDef and the DistanceJoint sample for details.
A revolute joint (also called a hinge or pin joint) forces two bodies to share a common anchor point and allows relative rotation about a single axis — the z-axis of the local frame. It has one rotational degree of freedom.
The joint angle is measured as the twist of frame B's z-axis relative to frame A's z-axis.
In some cases you might wish to control the joint angle. For this, the revolute joint can simulate a joint limit and/or a motor.
A joint limit forces the joint angle to remain between a lower and upper angle. The limit will apply as much torque as needed to make this happen. The limit range should include zero, otherwise the joint will lurch when the simulation begins.
A joint motor allows you to specify the joint speed. The speed can be negative or positive. A motor can have infinite torque, but this is usually not desirable. Recall the eternal question:
What happens when an irresistible force meets an immovable object?
I can tell you it's not pretty. So you can provide a maximum torque for the joint motor. The joint motor will maintain the specified speed unless the required torque exceeds the specified maximum. When the maximum torque is exceeded, the joint will slow down and can even reverse.
You can use a joint motor to simulate joint friction. Just set the joint speed to zero, and set the maximum torque to some small, but significant value. The motor will try to prevent the joint from rotating, but will yield to a significant load.
Here's an example revolute joint with a limit and a motor enabled. The motor is setup to simulate joint friction.
You can access a revolute joint's angle, speed, and motor torque.
You can also update the motor parameters each step.
Joint motors have some interesting abilities. You can update the joint speed every time step so you can make the joint move back-and-forth like a sine-wave or according to whatever function you want.
A prismatic joint (also called a slider joint) allows for relative translation of two bodies along the x-axis of local frame A. A prismatic joint prevents relative rotation. Therefore, a prismatic joint has a single degree of freedom.
The prismatic joint definition is similar to the revolute joint description; just substitute translation for angle and force for torque. Using this analogy provides an example prismatic joint definition with a joint limit and a friction motor:
The slide axis is the x-axis of local frame A.
The prismatic joint translation is zero when the frame origins coincide.
Using a prismatic joint is similar to using a revolute joint. Here are the relevant functions:
The weld joint attempts to constrain all relative motion between two bodies. Both translation and rotation can have spring-damper softness. See b3WeldJointDef and the Cantilever sample for details.
It is tempting to use the weld joint to define breakable structures. However, the Box3D solver is approximate so the joints can be soft in some cases regardless of the joint settings. So chains of bodies connected by weld joints may flex.
A motor joint lets you control the motion of a body by specifying target linear and angular velocities. You can set the maximum motor force and torque that will be applied. If the body is blocked, it will stop and the contact forces will be proportional to the maximum motor force and torque.
The motor joint also has an optional position spring that drives the relative transform toward a target. See b3MotorJointDef and the MotorJoint sample for details.
The wheel joint is designed specifically for vehicles. Body A is the chassis and body B is the wheel. The wheel:
The translation has a spring and damper to simulate vehicle suspension. The spin allows the wheel to rotate. You can specify a rotational motor to drive the wheel and to apply braking. Steering adds a rotation about the suspension axis. See b3WheelJointDef and the Drive sample for details.
A spherical joint (also called a ball-in-socket or point-to-point joint) fixes a point on body B to a point on body A and allows free rotation about all three axes. This gives 3 rotational degrees of freedom with no translation.
The cone limit restricts how far the z-axis of frame B can deviate from the z-axis of frame A. The twist limit restricts rotation about the z-axis of frame B.
At runtime you can query and adjust the limits:
The spherical joint also supports an optional alignment spring. When enabled it drives the relative orientation toward a target quaternion using a spring-damper:
And an angular velocity motor:
The parallel joint constrains the z-axis of body B to remain parallel to the z-axis of body A, using a spring-damper. This is useful for keeping a body upright without fully fixing its translation or other rotation axes.
You can also adjust the spring and torque limit at runtime:
The filter (or null) joint is used to disable collision between two specific bodies. As a side effect of being a joint, it also keeps the two bodies in the same simulation island, which can be useful for performance.
Spatial queries allow you to inspect the world geometrically. There are overlap queries, ray-casts, and shape-casts. These allow you to do things like:
Sometimes you want to determine all the shapes in a region. The world has a fast log(N) method for this using the broad-phase data structure. Box3D provides these overlap tests:
A basic understanding of query filtering is needed before considering the specific queries. Shape versus shape filtering was discussed herehere. A similar setup is used for queries. This lets your queries only consider certain categories of shapes, and also lets your shapes ignore certain queries.
Just like shapes, queries themselves can have a category. For example, you can have a CAMERA or PROJECTILE category.
If you want to query everything you can use b3DefaultQueryFilter().
You provide a b3AABB in world coordinates and an implementation of b3OverlapResultFcn(). The world calls your function with each shape whose AABB overlaps the query AABB. Return true to continue the query, otherwise return false. For example, the following code finds all the shapes that potentially intersect a specified AABB and wakes up all of the associated bodies.
Do not make any assumptions about the order of the callback. The order shapes are returned to your callback may seem arbitrary.
The AABB overlap is very fast but not very accurate because it only considers the shape bounding box. If you want an accurate overlap test, you can use a shape overlap query.
The overlap function uses a b3ShapeProxy which is an abstract shape consisting of some points and a radius. You can think of it as a cloud of spheres that has been shrink wrapped. This can represent a point, a sphere, a capsule, a convex hull, and so on.
In this example, I'm creating a shape proxy from a sphere and then calling b3World_OverlapShape(). This takes a b3OverlapResultFcn() to receive results and control the search progress.
You can use ray-casts to do line-of-sight checks, fire guns, etc. You perform a ray-cast by implementing the b3CastResultFcn() callback function and providing the origin point and translation. The world calls your function with each shape hit by the ray. Your callback is provided with the shape, the point of intersection, the unit normal vector, and the fractional distance along the ray. You cannot make any assumptions about the order of the points sent to the callback. The callback may receive points that are further away before receiving points that are closer.
You control the continuation of the ray-cast by returning a fraction. Returning a fraction of zero indicates the ray-cast should be terminated. A fraction of one indicates the ray-cast should continue as if no hit occurred. If you return the fraction from the argument list, the ray will be clipped to the current intersection point. So you can ray-cast any shape, ray-cast all shapes, or ray-cast the closest shape by returning the appropriate fraction.
You may also return a fraction of -1 to filter the shape. Then the ray-cast will proceed as if the shape does not exist.
Here is an example:
There is also a convenience function for the closest hit:
Ray-cast results may be delivered in an arbitrary order. When you are collecting multiple hits along the ray, you may want to sort them according to the hit fraction.
Shape-casts are similar to ray-casts. You can view a ray-cast as tracing a point along a line. A shape-cast allows you to trace a shape along a line. Like the shape overlap query, the shape cast uses a b3ShapeProxy to represent an arbitrary shape.
Shape-casts are setup similarly to ray-casts. Shape-casts are generally slower than ray-casts, so only use a shape-cast if a ray-cast won't do.
Like ray-casts, shape-cast results may be sent to the callback in any order. If you need multiple sorted results, you will need to write some code to collect and sort the results.
The Box3D simulation loop can be useful to understand when you process results.
Multithreading is represented in the diagram.
Let's review each of these stages.
The game starts the simulation by calling b3World_Step supplying the time step.
Box3D maintains a record of every shape that has moved. For each of these shapes the broad-phase (BVH) is queried for overlaps. New overlaps are recorded for processing in the next step. Existing overlaps are tracked in a hash set of all existing shape pairs. This operation is a parallel-for. Box3D maintains separate BVH trees for static, kinematic, and dynamic bodies.
This takes the pair results and creates the internal contact pair structure. This structure is persistent across time steps. It is used for the island graph and holding contact manifolds. This operation is single-threaded but most of the work is done in find pairs.
After the new shape pairs are known the BVH is not considered until later in the time step. Therefore the BVH for dynamic and kinematic shapes may be optimized. This involves identifying the part of the collision tree that is stale from refitting and then performing a rebuild of that sub-tree. This is a single-threaded operation that is done concurrently with other work.
This is where the contact manifolds and points are computed. Each active contact pair is confirmed as touching or non-touching. If the touching state changes then contact begin and end events are generated. This is a parallel-for operation.
Contact points are computed at the beginning of the time step, before bodies have moved and before impulses are known. This is necessary for obtaining good simulation results efficiently. If contacts were computed at the end of the time step then new contact points would not be known to the constraint solver and shapes would sink into each other.
The b3PreSolveFcn is called within the parallel-for so it should be efficient and thread-safe. This is only called for shapes that have enablePreSolveEvents == true.
Simulation islands are merged when shapes begin touching. Existing islands that have shapes that stop touching are flagged as candidates for splitting. This stage is single-threaded.
A split island task may be generated if:
Splitting an island may result in several new islands being created. Only a single island will be split per time step because it is expensive. Delaying the split may delay some bodies from sleeping. This is a single-threaded operation that is done concurrently with other work.
This solves contact and joint constraints and applies restitution. This is a parallel-for with multiple internal stages.
This stage does several tasks:
This stage is a parallel-for.
Note that continuous collision does not generate events. Instead they are generated the next time step. However, continuous collision will issue a b3PreSolveFcn callback.
Active contacts are scanned for fast approach velocities and added to a buffer. This considers contact points that have an impulse. This includes touching contacts and speculative contacts that generated an impulse (they are confirmed). So you may get hit events for contact points that have a positive separation. This is a single-threaded operation.
This updates the BVH for shapes that have moved significantly. This is done by enlarging the shapes' bounding box and all ancestor bounding boxes in the BVH. This is a single-threaded operation.
This can result in an inefficient BVH, which is why the rebuild BVH stage exists. Refitting is faster than rebuilding the BVH but is necessary to ensure the BVH is valid for subsequent queries, such as ray casts.
This is where bullets are processed. Note that this comes after hit events because continuous collision in Box3D does not generate events until the next time step.
When an island goes to sleep the simulation data associated with that island is moved to separate storage. This keeps the active simulation data contiguous and cache friendly.
Sensor overlaps are checked in the final stage. The overlap state reflects the final body transform. Sensors do not consider sleep so they may react to the user setting a body transform or creating a sleeping body. This is a parallel-for operation. The cost is roughly proportional to the number of sensors.
Box3D is designed to be deterministic across thread counts and platforms. This is important for debugging and game design.
Multithreaded determinism is achieved by basing simulation order on creation order. This includes bodies, shapes, and joint creation order. Determinism includes results reported to users (events). These events must be in deterministic order.
Cross-platform determinism is achieved on 64-bit platforms by using compiler flags and by avoiding non-deterministic library functions.
Determinism is on by default and there is no explicit option to disable it. However, you can break determinism by choosing different compiler flags. Box3D was designed to provide determinism with minimal cost. So there is no advantage to attempting to disable determinism.
A unit test for determinism is run for every pull request. Determinism is easy to break, so it is important to have regular validation.
Caution: Box3D determinism does not mean your application will be deterministic. Consider using similar strategies to make your application deterministic as have been used for Box3D.
1.17.0 