Compute the point states given two manifolds. The states pertain to the transition from manifold1 to manifold2. So state1 is either persist or remove while state2 is either add or persist.
This is used to fatten AABBs in the dynamic tree. This allows proxies to move by a small amount without triggering a tree adjustment. This is in meters.
This is used to fatten AABBs in the dynamic tree. This is used to predict the future position based on the current displacement. This is a dimensionless multiplier.
This scale factor controls how fast overlap is resolved. Ideally this would be 1 so that overlap is removed in one time step. However using values close to 1 often lead to overshoot.
A small length used as a collision and constraint tolerance. Usually it is chosen to be numerically significant, but visually insignificant. In meters.
The maximum linear translation of a body per step. This limit is very large and is used to prevent numerical problems. You shouldn't need to adjust this. Meters.
The radius of the polygon/edge shape skin. This should not be modified. Making this smaller means polygons will have an insufficient buffer for continuous collision. Making it larger may create artifacts for vertex collision.
Apply a force at a world point. If the force is not applied at the center of mass, it will generate a torque and affect the angular velocity. This wakes up the body.
Apply an impulse at a point. This immediately modifies the velocity. It also modifies the angular velocity if the point of application is not at the center of mass. This wakes up the body.
Parameters
-
-
impulse
the world impulse vector, usually in N-seconds or kg-m/s.
Creates a fixture and attach it to this body. Use this function if you need to set some fixture parameters, like friction. Otherwise you can create the fixture directly from a shape. If the density is non-zero, this function automatically updates the mass of the body. Contacts are not created until the next time step.
Creates a fixture from a shape and attach it to this body. This is a convenience function. Use b2FixtureDef if you need to set parameters like friction, restitution, user data, or filtering. If the density is non-zero, this function automatically updates the mass of the body.
Parameters
-
-
shape
the shape to be cloned.
-
density
the shape density (set to zero for static bodies).
Destroy a fixture. This removes the fixture from the broad-phase and destroys all contacts associated with this fixture. This will automatically adjust the mass of the body if the body is dynamic and the fixture has positive density. All fixtures attached to a body are implicitly destroyed when the body is destroyed.
This resets the mass properties to the sum of the mass properties of the fixtures. This normally does not need to be called unless you called SetMassData to override the mass and you later want to reset the mass.
Allow a body to be disabled. A disabled body is not simulated and cannot be collided with or woken up. If you pass a flag of true, all fixtures will be added to the broad-phase. If you pass a flag of false, all fixtures will be removed from the broad-phase and all contacts will be destroyed. Fixtures and joints are otherwise unaffected. You may continue to create/destroy fixtures and joints on disabled bodies. Fixtures on a disabled body are implicitly disabled and will not participate in collisions, ray-casts, or queries. Joints connected to a disabled body are implicitly disabled. An diabled body is still owned by a b2World object and remains in the body list.
Set the mass properties to override the mass properties of the fixtures. Note that this changes the center of mass position. Note that creating or destroying fixtures can also alter the mass. This function has no effect if the body isn't dynamic.
Set the position of the body's origin and rotation. Manipulating a body's transform may cause non-physical behavior. Note: contacts are updated on the next call to b2World::Step.
Parameters
-
-
position
the world position of the body's local origin.
-
angle
the world rotation in radians.
-
-
-
-
-
-
-The documentation for this class was generated from the following file:
The broad-phase is used for computing pairs and performing volume queries and ray casts. This broad-phase does not persist pairs. Instead, this reports potentially new pairs. It is up to the client to consume the new pairs and to track subsequent overlap.
Ray-cast against the proxies in the tree. This relies on the callback to perform a exact ray-cast in the case were the proxy contains a shape. The callback also performs the any collision filtering. This has performance roughly equal to k * log(n), where k is the number of collisions and n is the number of proxies in the tree.
Parameters
-
-
input
the ray-cast input data. The ray extends from p1 to p1 + maxFraction * (p2 - p1).
-
callback
a callback class that is called for each proxy that is hit by the ray.
A chain shape is a free form sequence of line segments. The chain has one-sided collision, with the surface normal pointing to the right of the edge. This provides a counter-clockwise winding like the polygon shape. Connectivity information is used to create smooth collisions.
Warning
the chain will not collide properly if there are self-intersections.
The class manages contact between two shapes. A contact exists for each overlapping AABB in the broad-phase (except if filtered). Therefore a contact object may exist that has no contact points.
Enable/disable this contact. This can be used inside the pre-solve contact listener. The contact is only disabled for the current time step (or sub-step in continuous collisions).
Override the default restitution velocity threshold mixture. You can call this in b2ContactListener::PreSolve. The value persists until you set or reset.
-
-
-
-The documentation for this class was generated from the following file:
Implement this class to get contact information. You can use these results for things like sounds and game logic. You can also get contact results by traversing the contact lists after the time step. However, you might miss some contacts because continuous physics leads to sub-stepping. Additionally you may receive multiple callbacks for the same contact in a single time step. You should strive to make your callbacks efficient because there may be many callbacks per time step.
Warning
You cannot create/destroy Box2D entities inside these callbacks.
This lets you inspect a contact after the solver is finished. This is useful for inspecting impulses. Note: the contact manifold does not include time of impact impulses, which can be arbitrarily large if the sub-step is small. Hence the impulse is provided explicitly in a separate data structure. Note: this is only called for contacts that are touching, solid, and awake.
This is called after a contact is updated. This allows you to inspect a contact before it goes to the solver. If you are careful, you can modify the contact manifold (e.g. disable contact). A copy of the old manifold is provided so that you can detect changes. Note: this is called only for awake bodies. Note: this is called even when the number of contact points is zero. Note: this is not called for sensors. Note: if you set the number of contact points to zero, you will not get an EndContact callback. However, you may get a BeginContact callback the next step.
-
-
-
-The documentation for this class was generated from the following file:
Joints and fixtures are destroyed when their associated body is destroyed. Implement this listener so that you may nullify references to these joints and shapes.
A dynamic AABB tree broad-phase, inspired by Nathanael Presson's btDbvt. A dynamic tree arranges data in a binary tree to accelerate queries such as volume queries and ray casts. Leafs are proxies with an AABB. In the tree we expand the proxy AABB by b2_fatAABBFactor so that the proxy AABB is bigger than the client object. This allows the client object to move by small amounts without triggering a tree update.
-
Nodes are pooled and relocatable, so we use node indices rather than pointers.
Move a proxy with a swepted AABB. If the proxy has moved outside of its fattened AABB, then the proxy is removed from the tree and re-inserted. Otherwise the function returns immediately.
Ray-cast against the proxies in the tree. This relies on the callback to perform a exact ray-cast in the case were the proxy contains a shape. The callback also performs the any collision filtering. This has performance roughly equal to k * log(n), where k is the number of collisions and n is the number of proxies in the tree.
Parameters
-
-
input
the ray-cast input data. The ray extends from p1 to p1 + maxFraction * (p2 - p1).
-
callback
a callback class that is called for each proxy that is hit by the ray.
A line segment (edge) shape. These can be connected in chains or loops to other edge shapes. Edges created independently are two-sided and do no provide smooth movement across junctions.
Set this as a part of a sequence. Vertex v0 precedes the edge and vertex v3 follows. These extra vertices are used to provide smooth movement across junctions. This also makes the collision one-sided. The edge normal points to the right looking from v1 to v2.
A fixture is used to attach a shape to a body for collision detection. A fixture inherits its transform from its parent. Fixtures hold additional non-geometric data such as friction, collision filters, etc. Fixtures are created via b2Body::CreateFixture.
Get the mass data for this fixture. The mass data is based on the density and the shape. The rotational inertia is about the shape's origin. This operation may be expensive.
Get the child shape. You can modify the child shape, however you should not change the number of vertices because this will crash some collision caching mechanisms. Manipulating the shape may lead to non-physical behavior.
Set the density of this fixture. This will not automatically adjust the mass of the body. You must call b2Body::ResetMassData to update the body's mass.
Set the contact filtering data. This will not update contacts until the next time step when either parent body is active and awake. This automatically calls Refilter.
A gear joint is used to connect two joints together. Either joint can be a revolute or prismatic joint. You specify a gear ratio to bind the motions together: coordinate1 + ratio * coordinate2 = constant The ratio can be negative or positive. If one joint is a revolute joint and the other joint is a prismatic joint, then the ratio will have units of length or units of 1/length.
Warning
You have to manually destroy the gear joint if joint1 or joint2 is destroyed.
-
The documentation for this class was generated from the following file:
template<typename T, int32 N>
-class b2GrowableStack< T, N >
-
-
This is a growable LIFO stack with an initial capacity of N. If the stack size exceeds the initial capacity, the heap is used to increase the size of the stack.
-
The documentation for this class was generated from the following file:
Get collide connected. Note: modifying the collide connect flag won't work correctly because the flag is only checked when fixture AABBs begin to overlap.
-
-
-
-The documentation for this class was generated from the following file:
A motor joint is used to control the relative motion between two bodies. A typical usage is to control the movement of a dynamic body with respect to the ground.
-
The documentation for this class was generated from the following file:
A mouse joint is used to make a point on a body track a specified world point. This a soft constraint with a maximum force. This allows the constraint to stretch and without applying huge forces. NOTE: this joint is not documented in the manual because it was developed to be used in the testbed. If you want to learn how to use the mouse joint, look at the testbed.
-
The documentation for this class was generated from the following file:
A solid convex polygon. It is assumed that the interior of the polygon is to the left of each edge. Polygons have a maximum number of vertices equal to b2_maxPolygonVertices. In most cases you should not need many vertices for a convex polygon.
A prismatic joint. This joint provides one degree of freedom: translation along an axis fixed in bodyA. Relative rotation is prevented. You can use a joint limit to restrict the range of motion and a joint motor to drive the motion or to model joint friction.
-
The documentation for this class was generated from the following file:
The pulley joint is connected to two bodies and two fixed ground points. The pulley supports a ratio such that: length1 + ratio * length2 <= constant Yes, the force transmitted is scaled by the ratio. Warning: the pulley joint can get a bit squirrelly by itself. They often work better when combined with prismatic joints. You should also cover the the anchor points with static shapes to prevent one side from going to zero length.
-
The documentation for this class was generated from the following file:
Called for each fixture found in the query. You control how the ray cast proceeds by returning a float: return -1: ignore this fixture and continue return 0: terminate the ray cast return fraction: clip the ray to this point return 1: don't clip the ray and continue
Parameters
-
-
fixture
the fixture hit by the ray
-
point
the point of initial intersection
-
normal
the normal vector at the point of intersection
-
fraction
the fraction along the ray at the point of intersection
-
-
-
-
Returns
-1 to filter, 0 to terminate, fraction to clip the ray for closest hit, 1 to continue
-
-
-
-The documentation for this class was generated from the following file:
A revolute joint constrains two bodies to share a common point while they are free to rotate about the point. The relative rotation about the shared point is the joint angle. You can limit the relative rotation with a joint limit that specifies a lower and upper angle. You can use a motor to drive the relative rotation about the shared point. A maximum motor torque is provided so that infinite forces are not generated.
A rope joint enforces a maximum distance between two points on two bodies. It has no other effect. Warning: if you attempt to change the maximum length during the simulation you will get some non-physical behavior. A model that would allow you to dynamically modify the length would have some sponginess, so I chose not to implement it that way. See b2DistanceJoint if you want to dynamically control length.
-
The documentation for this class was generated from the following file:
A shape is used for collision detection. You can create a shape however you like. Shapes used for simulation in b2World are created automatically when a b2Fixture is created. Shapes may encapsulate a one or more child shapes.
A wheel joint. This joint provides two degrees of freedom: translation along an axis fixed in bodyA and rotation in the plane. In other words, it is a point to line constraint with a rotational motor and a linear spring/damper. The spring/damper is initialized upon creation. This joint is designed for vehicle suspensions.
-
The documentation for this class was generated from the following file:
The world class manages all physics entities, dynamic simulation, and asynchronous queries. The world also contains efficient memory management facilities.
Manually clear the force buffer on all bodies. By default, forces are cleared automatically after each call to Step. The default behavior is modified by calling SetAutoClearForces. The purpose of this function is to support sub-stepping. Sub-stepping is often used to maintain a fixed sized time step under a variable frame-rate. When you perform sub-stepping you will disable auto clearing of forces and instead call ClearForces after all sub-steps are complete in one pass of your game loop.
Get the world body list. With the returned body, use b2Body::GetNext to get the next body in the world list. A nullptr body indicates the end of the list.
Get the world contact list. With the returned contact, use b2Contact::GetNext to get the next contact in the world list. A nullptr contact indicates the end of the list.
Returns
the head of the world contact list.
-
Warning
contacts are created and destroyed in the middle of a time step. Use b2ContactListener to avoid missing contacts.
Get the world joint list. With the returned joint, use b2Joint::GetNext to get the next joint in the world list. A nullptr joint indicates the end of the list.
Ray-cast the world for all fixtures in the path of the ray. Your callback controls whether you get the closest point, any point, or n-points. The ray-cast ignores shapes that contain the starting point.
Register a contact filter to provide specific control over collision. Otherwise the default filter is used (b2_defaultFilter). The listener is owned by you and must remain in scope.
Register a routine for debug drawing. The debug draw functions are called inside with b2World::DebugDraw method. The debug draw object is owned by you and must remain in scope.
-Normally shapes on static bodies don't invoke contact creation when they are added to the world.
This overrides that behavior and causes contact creation. This significantly slows down static body creation which can be important when there are many static shapes.
+Normally shapes on static bodies don't invoke contact creation when they are added to the world.
This overrides that behavior and causes contact creation. This significantly slows down static body creation which can be important when there are many static shapes. This is implicitly always true for sensors.
Box2D is a feature rich 2D rigid body physics engine, written in C++ by Erin Catto. It has been used in many games, including Crayon Physics Deluxe, winner of the 2008 Independant Game Festival Grand Prize.
-
Box2D uses the MIT license license and can be used free of charge.
-
-What platforms does Box2D support?
-
Box2D is developed on Windows using Visual C++. Ports are also available for Flash, Java, C#, Python.
-
Erin Catto maintains the C++ version, but provides no support for other languages. Other languages are supported by the community and possibly by the authors of those ports.
-
-Who makes it?
-
Erin Catto is the driving force behind Box2D, with various others supporting the ports. Box2D is an open source project, and accepts community feedback.
-
-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 subreddit to ask any remaining questions.
-
Please to not PM or email Erin Catto for support. It is best to ask questions in the forum so that everyone can benefit from the discussion.
-
-Documentation
-
-Why isn't feature foo documented?
-
If you grab the latest code from the git master 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 Box2D are accompanied by example code in the testbed to test the feature and show the intended usage.
-
-Prerequisites
-
-Programming
-
You should have a working knowledge of C++ before you use Box2D. You should understand classes, inheritance, 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. 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 Box2D.
-
-API
-
-What units does Box2D use?
-
Box2D is tuned for meters-kilograms-seconds (MKS). Your moving objects should be between 0.1 - 10 meters. Do not use pixels as units! You will get a jittery simulation.
-
-How do I convert pixels to meters?
-
Suppose you have a sprite for a character that is 100x100 pixels. You decide to use a scaling factor that is 0.01. This will make the character physics box 1m x 1m. So go make a physics box that is 1x1. Now suppose the character starts out at pixel coordinate (345,679). So position the physics box at (3.45,6.79). Now simulate the physics world. Suppose the character physics box moves to (2.31,4.98), so move your character sprite to pixel coordinates (231,498). Now the only tricky part is choosing a scaling factor. This really depends on your game. You should try to get your moving objects in the range 0.1 - 10 meters, with 1 meter being the sweet spot.
-
-Why don't you use this awesome C++ feature?
-
Box2D is designed to be portable, so I try to keep the C++ usage simple. Also, I don't use the STL (except sort) or other libraries to keep the dependencies low. I keep template usage low and don't use name spaces. Remember, just because a C++ feature exists, that doesn't mean you need to use it.
-
The many ports of Box2D to other languages platforms shows that this strategy has been successful.
-
-Can I use Box2D in a DLL?
-
Box2D was not designed to be used in a DLL. You may have to change how static data is used to make this work.
-
-Is Box2D thread-safe?
-
No. Box2D will likely never be thread-safe. Box2D has a large API and trying to make such an API thread-safe would have a large performance and complexity impact.
-
-Build Issues
-
-Why doesn't my code compile and/or link?
-
There are many reasons why a build can go bad. Here are a few that have come up:
-
-
Using old Box2D headers with new code
-
Not linking the Box2D library with your application
-
Using old project files that don't include some new source files
-
-
-Rendering
-
-What are Box2D's rendering capabilities?
-
Box2D is only a physics engine. How you draw stuff is up to you.
-
-But the Testbed draws stuff
-
Visualization is very important for debugging collision and physics. I wrote the test bed to help me test Box2D and give you examples of how to use Box2D. The TestBed is not part of the Box2D library.
-
-How do I draw shapes?
-
Drawing shapes is not supported and shape internal data is likely to change. Instead you should implement the b2DebugDraw interface.
-
-Accuracy
-
Box2D 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. Box2D uses Gauss-Seidel to approximately solve constraints. Box2D also uses Semi-implicit Euler to approximately solve the differential equations. Box2D also does not have exact collision. Polygons are covered with a thin skin (around 0.5cm thick) to avoid numerical problems. This can sometimes lead to unexpected contact normals. Also, some shapes may begin to overlap and then be pushed apart by the solver.
-
-Making Games
-
-Worms Clones
-
Making a worms clone requires arbitrarily destructible terrain. This is beyond the scope of Box2D, so you will have to figure out how to do this on your own.
-
-Tile Based Environment
-
Using many boxes for your terrain may not work well because box-like characters can get snagged on internal corners. A future update to Box2D should allow for smooth motion over edge chains. In general you should avoid using a rectangular character because collision tolerances will still lead to undesirable snagging.
-
-Asteroid Type Coordinate Systems
-
Box2D does not have any support for coordinate frame wrapping. You would likely need to customize Box2D for this purpose. You may need to use a different broad-phase for this to work.
-
-Determinism
-
-Is Box2D deterministic?
-
For the same input, and same binary, Box2D will reproduce any simulation. Box2D does not use any random numbers nor base any computation on random events (such as timers, etc).
-
However, people often want more stringent determinism. People often want to know if Box2D can produce identical results on different binaries and on different platforms. The answer is no. The reason for this answer has to do with how floating point math is implemented in many compilers and processors. I recommend reading this article if you are curious: http://www.yosefk.com/blog/consistency-how-to-defeat-the-purpose-of-ieee-floating-point.html
-
-But I really want determinism
-
This naturally leads to the question of fixed-point math. Box2D does not support fixed-point math. In the past Box2D was ported to the NDS in fixed-point and apparently it worked okay. Fixed-point math is slower and more tedious to develop, so I have chosen not to use fixed-point for the development of Box2D.
-
-Why is the restitution/friction mixing inaccurate?
-
A physically correct restitution value must be measured in experiments. But as soon as you change the geometry from the experiment then the value is wrong. Next, adding simultaneous collision makes the answer worse. We've been down this road before.
-
So the question of accuracy has been answered: failure.
-
The only remaining question is how do we make it convenient. On this opinions may vary.
-
b2Settings is just that. Settings you can adjust if you know what you are doing.
The Collision module contains shapes and functions that operate on them. The module also contains a dynamic tree and broad-phase to acceleration collision processing of large systems.
-
The collision module is designed to be usable outside of the dynamic system. For example, you can use the dynamic tree for other aspects of your game besides physics.
-
However, the main purpose of Box2D is to provide a rigid body physics engine, so the using the collision module by itself may feel limited for some applications. Likewise, I will not make a strong effort to document it or polish the APIs.
-
-Shapes
-
Shapes describe collision geometry and may be used independently of physics simulation. At a minimum, you should understand how to create shapes that can be later attached to rigid bodies.
-
Box2D shapes implement the b2Shape base class. The base class defines functions to:
-
Test a point for overlap with the shape.
-
Perform a ray cast against the shape.
-
Compute the shape's AABB.
-
Compute the mass properties of the shape.
-
-
In addition, each shape has a type member and a radius. The radius even applies to polygons, as discussed below.
-
Keep in mind that a shape does not know about bodies and stand apart from the dynamics system. Shapes are stored in a compact form that is optimized for size and performance. As such, shapes are not easily moved around. You have to manually set the shape vertex positions to move a shape. However, when a shape is attached to a body using a fixture, the shapes move rigidly with the host body. In summary:
-
When a shape is not attached to a body, you can view it's vertices as being expressed in world-space.
-
When a shape is attached to a body, you can view it's vertices as being expressed in local coordinates.
-
-
-Circle Shapes
-
Circle shapes have a position and radius. Circles are solid. You cannot make a hollow circle using the circle shape.
Polygon shapes are solid convex polygons. A polygon is convex when all line segments connecting two points in the interior do not cross any edge of the polygon. Polygons are solid and never hollow. A polygon must have 3 or more vertices.
-
-
-
-Convex and Concave Polygons
-
Polygons vertices are stored with a counter clockwise winding (CCW). We must be careful because the notion of CCW is with respect to a right-handed coordinate system with the z-axis pointing out of the plane. This might turn out to be clockwise on your screen, depending on your coordinate system conventions.
-
-
-
-Polygon Winding Order
-
The polygon members are public, but you should use initialization functions to create a polygon. The initialization functions create normal vectors and perform validation.
-
You can create a polygon shape by passing in a vertex array. The maximal size of the array is controlled by b2_maxPolygonVertices which has a default value of 8. This is sufficient to describe most convex polygons.
-
The b2PolygonShape::Set function automatically computes the convex hull and establishes the proper winding order. This function is fast when the number of vertices is low. If you increase b2_maxPolygonVertices, then the convex hull computation might become slow. Also note that the convex hull function may eliminate and/or re-order the points you provide. Vertices that are closer than b2_linearSlop may be merged.
The polygon shape has some convenience functions to create boxes.
-
void SetAsBox(float hx, float hy);
-
void SetAsBox(float hx, float hy, constb2Vec2& center, float angle);
-
Polygons inherit a radius from b2Shape. The radius creates a skin around the polygon. The skin is used in stacking scenarios to keep polygons slightly separated. This allows continuous collision to work against the core polygon.
-
-
-
-Polygon Skin
-
The polygon skin helps prevent tunneling by keeping the polygons separated. This results in small gaps between the shapes. Your visual representation can be larger than the polygon to hide any gaps.
-
-
-
-Skin Collision
-
Not that polygon skin is only provided to help with continuous collision. The purpose is not to simulate rounded polygons.
-
-Edge Shapes
-
Edge shapes are line segments. These are provided to assist in making a free-form static environment for your game. A major limitation of edge shapes is that they can collide with circles and polygons but not with themselves. The collision algorithms used by Box2D require that at least one of two colliding shapes have volume. Edge shapes have no volume, so edge-edge collision is not possible.
In many cases a game environment is constructed by connecting several edge shapes end-to-end. This can give rise to an unexpected artifact when a polygon slides along the chain of edges. In the figure below we see a box colliding with an internal vertex. These ghost collisions are caused when the polygon collides with an internal vertex generating an internal collision normal.
-
-
-
-Ghost Collision
-
If edge1 did not exist this collision would seem fine. With edge1 present, the internal collision seems like a bug. But normally when Box2D collides two shapes, it views them in isolation.
-
Fortunately, the edge shape provides a mechanism for eliminating ghost collisions by storing the adjacent ghost vertices. Box2D uses these ghost vertices to prevent internal collisions.
-
-
-
-Ghost Vertices
-
The Box2D algorithm for dealing with ghost collisions only supports one-sided collision. The front face is to the right when looking from the first vertex towards the second vertex. This matches the CCW winding order used by polygons.
In general stitching edges together this way is a bit wasteful and tedious. This brings us to chain shapes.
-
-Chain Shapes
-
The chain shape provides an efficient way to connect many edges together to construct your static game worlds. Chain shapes automatically eliminate ghost collisions and provide one-sided collision. The collision is one-sided to eliminate ghost collisions.
-
If you don't care about ghost collisions, you can just create a bunch of two-sided edge shapes. The efficiency is similar.
-
The simplest way to use chain shapes is to create loops. Simply provide an array of vertices.
The edge normal depends on the winding order. A counter-clockwise winding order orients the normal outwards and a clockwise winding order orients the normal inwards.
-
-
-
-Chain Shape Outwards Loop
-
-
-
-Chain Shape Inwards Loop
-
You may have a scrolling game world and would like to connect several chains together. You can connect chains together using ghost vertices, like we did with b2EdgeShape.
Self-intersection of chain shapes is not supported. It might work, it might not. The code that prevents ghost collisions assumes there are no self-intersections of the chain. Also, very close vertices can cause problems. Make sure all your edges are longer than b2_linearSlop (5mm).
-
-
-
-Self Intersection is Bad
-
Each edge in the chain is treated as a child shape and can be accessed by index. When a chain shape is connected to a body, each edge gets its own bounding box in the broad-phase collision tree.
Edge and chain shapes always return false, even if the chain is a loop.
-
-Shape Ray Cast
-
You can cast a ray at a shape to get the point of first intersection and normal vector. A child index is included for chain shapes because the ray cast will only check a single edge at a time.
-
-
Caution: No hit will register if the ray starts inside a convex shape like a circle or polygon. This is consistent with Box2D treating convex shapes as solid.
Again you must provide child indices to for the case of chain shapes.
-
-Contact Manifolds
-
Box2D has functions to compute contact points for overlapping shapes. If we consider circle-circle or circle-polygon, we can only get one contact point and normal. In the case of polygon-polygon we can get two points. These points share the same normal vector so Box2D groups them into a manifold structure. The contact solver takes advantage of this to improve stacking stability.
-
-
-
-Contact Manifold
-
Normally you don't need to compute contact manifolds directly, however you will likely use the results produced in the simulation.
-
The b2Manifold structure holds a normal vector and up to two contact points. The normal and points are held in local coordinates. As a convenience for the contact solver, each point stores the normal and tangential (friction) impulses.
-
The data stored in b2Manifold is optimized for internal use. If you need this data, it is usually best to use the b2WorldManifold structure to generate the world coordinates of the contact normal and points. You need to provide a b2Manifold and the shape transforms and radii.
The b2Distance function can be used to compute the distance between two shapes. The distance function needs both shapes to be converted into a b2DistanceProxy. There is also some caching used to warm start the distance function for repeated calls.
-
-
-
-Distance Function
-
-Time of Impact
-
If two shapes are moving fast, they may tunnel through each other in a single time step.
-
-
-
-Tunneling
-
The b2TimeOfImpact function is used to determine the time when two moving shapes collide. This is called the time of impact (TOI). The main purpose of b2TimeOfImpact is for tunnel prevention. In particular, it is designed to prevent moving objects from tunneling outside of static level geometry.
-
This function accounts for rotation and translation of both shapes, however if the rotations are large enough, then the function may miss a collision. However the function will still report a non-overlapped time and will capture all translational collisions.
-
The time of impact function identities an initial separating axis and ensures the shapes do not cross on that axis. This might miss collisions that are clear at the final positions. While this approach may miss some collisions, it is very fast and adequate for tunnel prevention.
-
-
-
-Captured Collision
-
-
-
-Missed Collision
-
It is difficult to put a restriction on the rotation magnitude. There may be cases where collisions are missed for small rotations. Normally, these missed rotational collisions should not harm game play. They tend to be glancing collisions.
-
The function requires two shapes (converted to b2DistanceProxy) and two b2Sweep structures. The sweep structure defines the initial and final transforms of the shapes.
-
You can use fixed rotations to perform a shape cast. In this case, the time of impact function will not miss any collisions.
-
-Dynamic Tree
-
The b2DynamicTree class is used by Box2D to organize large numbers of shapes efficiently. The class does not know about shapes. Instead it operates on axis-aligned bounding boxes (AABBs) with user data pointers.
-
The dynamic tree is a hierarchical AABB tree. Each internal node in the tree has two children. A leaf node is a single user AABB. The tree uses rotations to keep the tree balanced, even in the case of degenerate input.
-
The tree structure allows for efficient ray casts and region queries. For example, you may have hundreds of shapes in your scene. You could perform a ray cast against the scene in a brute force manner by ray casting each shape. This would be inefficient because it does not take advantage of shapes being spread out. Instead, you can maintain a dynamic tree and perform ray casts against the tree. This traverses the ray through the tree skipping large numbers of shapes.
-
A region query uses the tree to find all leaf AABBs that overlap a query AABB. This is faster than a brute force approach because many shapes can be skipped.
-
-
-
-Raycast
-
-
-
-Overlap Test
-
Normally you will not use the dynamic tree directly. Rather you will go through the b2World class for ray casts and region queries. If you plan to instantiate your own dynamic tree, you can learn how to use it by looking at how Box2D uses it.
-
-Broad-phase
-
Collision processing in a physics step can be divided into narrow-phase and broad-phase. In the narrow-phase we compute contact points between pairs of shapes. Imagine we have N shapes. Using brute force, we would need to perform the narrow-phase for N*N/2 pairs.
-
The b2BroadPhase class reduces this load by using a dynamic tree for pair management. This greatly reduces the number of narrow-phase calls.
-
Normally you do not interact with the broad-phase directly. Instead, Box2D creates and manages a broad-phase internally. Also, b2BroadPhase is designed with Box2D's simulation loop in mind, so it is likely not suited for other use cases.
The Common module contains settings, memory management, and vector math.
-
-Settings
-
The header b2Settings.h contains:
-
Types such as int32 and float
-
Constants
-
Allocation wrappers
-
The version number
-
-
-Types
-
Box2D defines various types such as int8, etc. to make it easy to determine the size of structures.
-
-Constants
-
Box2D defines several constants. These are all documented in b2Settings.h. Normally you do not need to adjust these constants.
-
Box2D uses floating point math for collision and simulation. Due to round-off error some numerical tolerances are defined. Some tolerances are absolute and some are relative. Absolute tolerances use MKS units.
-
-Allocation wrappers
-
The settings file defines b2Alloc and b2Free for large allocations. You may forward these calls to your own memory management system.
-
-Version
-
The b2Version structure holds the current version so you can query this at run-time.
-
-Memory Management
-
A large number of the decisions about the design of Box2D were based on the need for quick and efficient use of memory. In this section I will discuss how and why Box2D allocates memory.
-
Box2D tends to allocate a large number of small objects (around 50-300 bytes). Using the system heap through malloc or new for small objects is inefficient and can cause fragmentation. Many of these small objects may have a short life span, such as contacts, but can persist for several time steps. So we need an allocator that can efficiently provide heap memory for these objects.
-
Box2D's solution is to use a small object allocator (SOA) called b2BlockAllocator. The SOA keeps a number of growable pools of varying sizes. When a request is made for memory, the SOA returns a block of memory that best fits the requested size. When a block is freed, it is returned to the pool. Both of these operations are fast and cause little heap traffic.
-
Since Box2D uses a SOA, you should never new or malloc a body, fixture, or joint. However, you do have to allocate a b2World on your own. The b2World class provides factories for you to create bodies, fixtures, and joints. This allows Box2D to use the SOA and hide the gory details from you. Never, call delete or free on a body, fixture, or joint.
-
While executing a time step, Box2D needs some temporary workspace memory. For this, it uses a stack allocator called b2StackAllocator to avoid per-step heap allocations. You don't need to interact with the stack allocator, but it's good to know it's there.
-
-Math
-
Box2D includes a simple small vector and matrix module. This has been designed to suit the internal needs of Box2D and the API. All the members are exposed, so you may use them freely in your application.
-
The math library is kept simple to make Box2D easy to port and maintain.
The Dynamics module is the most complex part of Box2D and is the part you likely interact with the most. The Dynamics module sits on top of the Common and Collision modules, so you should be somewhat familiar with those by now.
-
The Dynamics module contains:
-
fixture class
-
rigid body class
-
contact class
-
joint classes
-
world class
-
listener classes
-
-
There are many dependencies between these classes so it is difficult to describe one class without referring to another. In the following, you may see some references to classes that have not been described yet. Therefore, you may want to quickly skim this chapter before reading it closely.
-
The dynamics module is covered in the following chapters.
-
-Bodies
-
Bodies have position and velocity. You can apply forces, torques, and impulses to bodies. Bodies can be static, kinematic, or dynamic. Here are the body type definitions:
-
-b2_staticBody
-
A static body does not move under simulation and behaves as if it has infinite mass. Internally, Box2D stores zero for the mass and the inverse mass. Static bodies can be moved manually by the user. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies.
-
-b2_kinematicBody
-
A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. They can be moved manually by the user, but normally a kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box2D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other kinematic or static bodies.
-
-b2_dynamicBody
-
A dynamic body is fully simulated. They can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass. If you try to set the mass of a dynamic body to zero, it will automatically acquire a mass of one kilogram and it won't rotate.
-
Bodies are the backbone for fixtures (shapes). Bodies carry fixtures and move them around in the world. Bodies are always rigid bodies in Box2D. That means that two fixtures attached to the same rigid body never move relative to each other and fixtures attached to the same body don't collide.
-
Fixtures have collision geometry and density. Normally, bodies acquire their mass properties from the fixtures. However, you can override the mass properties after a body is constructed.
-
You usually keep pointers 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 pointers so you can destroy them when you are done with them.
-
-Body Definition
-
Before a body is created you must create a body definition (b2BodyDef). The body definition holds the data needed to create and initialize a body.
-
Box2D 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.
-
Let's go over some of the key members of the body definition.
-
-Body Type
-
As discussed at the beginning of this chapter, there are three different body types: static, kinematic, and dynamic. You should establish the body type at creation because changing the body type later is expensive.
The body definition gives you the chance to initialize the position of the body on creation. 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. Fixtures 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 mass distribution of the attached shapes or is explicitly set with b2MassData. Much of Box2D's internal computations use the center of mass position. For example b2Body stores the linear velocity for the center of mass.
-
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 angle in radians, which is not affected by the position of the center of mass. If you later change the mass properties of the body, then the center of mass may move on the body, but the origin position does not change and the attached shapes and joints do not move.
bodyDef.position.Set(0.0f, 2.0f); // the body's origin position.
-
bodyDef.angle = 0.25f * b2_pi; // the body's angle in radians.
-
A rigid body is also a frame of reference. You can define fixtures and joints in that frame. Those fixtures and joint anchors never move in the local frame of the body.
-
-Damping
-
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 should be used together.
-
Damping parameters should be between 0 and infinity, with 0 meaning no damping, and infinity meaning full damping. Normally you will use a damping value between 0 and 0.1. I generally do not use linear damping because it makes bodies look like they are floating.
Damping is approximated for stability and 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).
-
-Gravity Scale
-
You can use the gravity scale to adjust the gravity on a single body. Be careful though, increased gravity can decrease stability.
-
// Set the gravity scale to zero so this body will float
What does sleep mean? Well it is expensive to simulate bodies, so the less we have to simulate the better. When a body comes to rest we would like to stop simulating it.
-
When Box2D 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.
You may want a rigid body, such as a character, to have a fixed rotation. Such a body should not rotate, even under load. You can use the fixed rotation setting to achieve this:
The fixed rotation flag causes the rotational inertia and its inverse to be set to zero.
-
-Bullets
-
Game simulation usually generates a sequence of images 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, Box2D 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 and then the solver performs a sub-step to complete the full time step. There may be additional TOI events within a sub-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 Box2D can be labeled as bullets. Bullets will perform CCD with both static and dynamic bodies. 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.
You may wish a body to be created but not participate in collision or dynamics. This state is similar to sleeping except the body will not be woken by other bodies and the body's fixtures will not be placed in the broad-phase. This means the body will not participate in collisions, ray casts, etc.
-
You can create a body in an inactive state and later re-activate it.
Joints may be connected to inactive bodies. These joints will not be simulated. You should be careful when you activate a body that its joints are not distorted.
-
Note that activating a body is almost as expensive as creating the body from scratch. So you should not use activation for streaming worlds. Use creation/destruction for streaming worlds to save memory.
-
-User Data
-
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.
Bodies are created and destroyed using a body factory provided by the world class. This lets the world create the body with an efficient allocator and add the body to the world data structure.
Caution: You should never use new or malloc to create a body. The world won't know about the body and the body won't be properly initialized.
-
-
Box2D 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.
-
Box2D allows you to avoid destroying bodies by deleting your b2World object, which does all the cleanup work for you. However, you should be mindful to nullify body pointers that you keep in your game engine.
-
When you destroy a body, the attached fixtures and joints are automatically destroyed. This has important implications for how you manage shape and joint pointers.
-
-Using 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.
-
-Mass Data
-
A body has mass (scalar), center of mass (2-vector), and rotational inertia (scalar). For static bodies, the mass and rotational inertia are set to zero. When a body has fixed rotation, its rotational inertia is zero.
-
Normally the mass properties of a body are established automatically when fixtures 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.
You can access the position and rotation of a body. This is common when rendering your associated game actor. You can also set the position, although this is less common since you will normally use Box2D to simulate movement.
You can access the center of mass position in local and world coordinates. Much of the internal simulation in Box2D 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 square. The body origin might be a corner of the square, while the center of mass is located at the center of the square.
You can access the linear and angular velocity. The linear velocity is for the center of mass. Therefore, the linear velocity may change if the mass properties change.
-
-Forces and Impulses
-
You can apply forces, torques, and impulses to a body. When you apply a force or an impulse, you provide a world point where the load is applied. This often results in a torque about the center of mass.
Applying a force, torque, or impulse wakes the body. Sometimes this is undesirable. For example, you may be applying a steady force and want to allow the body to sleep to improve performance. In this case you can use the following code.
-
if (myBody->IsAwake() == true)
-
{
-
myBody->ApplyForce(myForce, myPoint);
-
}
-
-Coordinate Transformations
-
The body class has some utility functions to help you transform points and vectors between local and world space. If you don't understand these concepts, please read "Essential Mathematics for Games and Interactive Applications" by Jim Van Verth and Lars Bishop. These functions are efficient (when inlined).
MyFixtureData* data = (MyFixtureData*)f->GetUserData();
-
// do something with data ...
-
}
-
You can similarly iterate over the body's joint list.
-
The body also provides a list of associated contacts. You can use this to get information about the current contacts. Be careful, because the contact list may not contain all the contacts that existed during the previous time step.
-
-Fixtures
-
Recall that shapes don't know about bodies and may be used independently of the physics simulation. Therefore Box2D provides the b2Fixture class to attach shapes to bodies. A body may have zero or more fixtures. A body with multiple fixtures is sometimes called a compound body.
-
Fixtures hold the following:
-
a single shape
-
broad-phase proxies
-
density, friction, and restitution
-
collision filtering flags
-
back pointer to the parent body
-
user data
-
sensor flag
-
-
These are described in the following sections.
-
-Fixture Creation
-
Fixtures are created by initializing a fixture definition and then passing the definition to the parent body.
This creates the fixture and attaches it to the body. You do not need to store the fixture pointer since the fixture will automatically be destroyed when the parent body is destroyed. You can create multiple fixtures on a single body.
-
You can destroy a fixture on the parent body. You may do this to model a breakable object. Otherwise you can just leave the fixture alone and let the body destruction take care of destroying the attached fixtures.
The fixture 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 fixtures. This will improve stacking stability.
-
The mass of a body is not adjusted when you set the density. You must call ResetMassData for this to occur.
Friction is used to make objects slide along each other realistically. Box2D supports static and dynamic friction, but uses the same parameter for both. Friction is simulated accurately in Box2D 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, Box2D must combine the friction parameters of the two parent fixtures. This is done with the geometric mean:
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.
When a shape develops multiple contacts, restitution is simulated approximately. This is because Box2D uses an iterative solver. Box2D also uses inelastic collisions when the collision velocity is small. This is done to prevent jitter. See b2_velocityThreshold.
-
-Filtering
-
Collision filtering allows you to prevent collision between fixtures. 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). Box2D supports such collision filtering using categories and groups.
-
Box2D supports 16 collision categories. For each fixture you can specify which category it belongs to. You also specify what other categories this fixture can collide with. For example, you could specify in a multiplayer game that all players don't collide with each other and monsters don't collide with each other, but players and monsters should collide. This is done with masking bits. For example:
Collision groups let you specify an integral group index. You can have all fixtures 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 bicycle. In the following example, fixture1 and fixture2 always collide, but fixture3 and fixture4 never collide.
-
fixture1Def.filter.groupIndex = 2;
-
fixture2Def.filter.groupIndex = 2;
-
fixture3Def.filter.groupIndex = -8;
-
fixture4Def.filter.groupIndex = -8;
-
Collisions between fixtures of different group indices are filtered according the category and mask bits. In other words, group filtering has higher precedence than category filtering.
-
Note that additional collision filtering occurs in Box2D. Here is a list:
-
A fixture on a static body can only collide with a dynamic body.
-
A fixture on a kinematic body can only collide with a dynamic body.
-
Fixtures on the same body never collide with each other.
-
You can optionally enable/disable collision between fixtures on bodies connected by a joint.
-
-
Sometimes you might need to change collision filtering after a fixture has already been created. You can get and set the b2Filter structure on an existing fixture using b2Fixture::GetFilterData and b2Fixture::SetFilterData. Note that changing the filter data will not add or remove contacts until the next time step (see the World class).
-
-Sensors
-
Sometimes game logic needs to know when two fixtures overlap yet there should be no collision response. This is done by using sensors. A sensor is a fixture that detects collision but does not produce a response.
-
You can flag any fixture as being a sensor. Sensors may be static, kinematic, or dynamic. Remember that you may have multiple fixtures per body and you can have any mix of sensors and solid fixtures. Also, sensors only form contacts when at least one body is dynamic, so you will not get a contact for kinematic versus kinematic, kinematic versus static, or static versus static.
-
Sensors do not generate contact points. There are two ways to get the state of a sensor:
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 joint provide motors which can be used to drive the joint at a prescribed speed until a prescribed force/torque is exceeded.
-
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.
-
-Joint Definition
-
Each joint type has a definition that derives from b2JointDef. All joints are connected between two different bodies. One body may static. Joints between static and/or kinematic bodies are allowed, but have no effect and use some processing time.
-
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 actually the default behavior and you must set the collideConnected Boolean to allow collision between to connected bodies.
-
Many joint definitions require that you provide some geometric data. Often a joint will be defined by anchor points. These are points fixed in the attached bodies. Box2D requires these points to be specified in local coordinates. This way the joint can be specified even when the current body transforms violate the joint constraint --- a common occurrence when a game is saved and reloaded. Additionally, some joint definitions need to know the default relative angle between the bodies. This is necessary to constrain rotation correctly.
-
Initializing the geometric data can be tedious, so many joints have initialization functions that use the current body transforms to remove much of the work. However, these initialization functions should usually only be used for prototyping. Production code should define the geometry directly. This will make joint behavior more robust.
-
The rest of the joint definition data depends on the joint type. We cover these now.
-
-Joint Factory
-
Joints are created and destroyed using the world factory methods. This brings up an old issue:
-
-
Caution: Don't try to create a joint on the stack or on the heap using new or malloc. You must create and destroy bodies and joints using the create and destroy methods of the b2World class.
-
-
Here's an example of the lifetime of a revolute joint:
It is always good to nullify your pointer after they are destroyed. This will make the program crash in a controlled manner if you try to reuse the pointer.
-
The lifetime of a joint is not simple. Heed this warning well:
-
-
Caution: Joints are destroyed when an attached body is destroyed.
-
-
This precaution is not always necessary. You may organize your game engine so that joints are always destroyed before the attached bodies. In this case you don't need to implement the listener class. See the section on Implicit Destruction for details.
-
-Using Joints
-
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 bodies, anchor points, and user data from a joint.
All joints have a reaction force and torque. This the reaction force applied to body 2 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 joint is a distance joint which says that the distance between two 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 in world coordinates. The first anchor point is connected to body 1, and the second anchor point is connected to body 2. These points imply the length of the distance constraint.
-
-
-
-Distance Joint
-
Here is an example of a distance joint definition. In this case we decide to allow the bodies to collide.
The distance joint can also be made soft, like a spring-damper connection. See the Web example in the testbed to see how this behaves.
-
Softness is achieved by tuning two constants in the definition: stiffness and damping. It can be non-intuitive setting these values directly since they have units in terms on Newtons. Box2D provides and API to compute these values in terms of frequency and damping ratio.
Think of the frequency as the frequency of a harmonic oscillator (like a guitar string). The frequency is specified in Hertz. 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 is non-dimensional and is typically between 0 and 1, but can be larger. At 1, the damping is critical (all oscillations should vanish).
It is also possible to define a minimum and maximum length for the distance joint. See b2DistanceJointDef for details.
-
-Revolute Joint
-
A revolute joint forces two bodies to share a common anchor point, often called a hinge point. The revolute joint has a single degree of freedom: the relative rotation of the two bodies. This is called the joint angle.
-
-
-
-Revolute Joint
-
To specify a revolute you need to provide two bodies and a single anchor point in world space. The initialization function assumes that the bodies are already in the correct position.
-
In this example, two bodies are connected by a revolute joint at the first body's center of mass.
The revolute joint angle is positive when bodyB rotates CCW about the angle point. Like all angles in Box2D, the revolute angle is measured in radians. By convention the revolute joint angle is zero when the joint is created using Initialize(), regardless of the current rotation of the two bodies.
-
In some cases you might wish to control the joint angle. For this, the revolute joint can optionally simulate a joint limit and/or a motor.
-
A joint limit forces the joint angle to remain between a lower and upper bound. 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 time derivative of the angle). The speed can be negative or positive. A motor can have infinite force, 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 a revision of the revolute joint definition above; this time the joint has a limit and a motor enabled. The motor is setup to simulate joint friction.
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.
-
// ... Game Loop Begin ...
-
-
myJoint->SetMotorSpeed(cosf(0.5f * time));
-
-
// ... Game Loop End ...
-
You can also use joint motors to track a desired joint angle. For example:
Generally your gain parameter should not be too large. Otherwise your joint may become unstable.
-
-Prismatic Joint
-
A prismatic joint allows for relative translation of two bodies along a specified axis. A prismatic joint prevents relative rotation. Therefore, a prismatic joint has a single degree of freedom.
-
-
-
-Prismatic Joint
-
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 revolute joint has an implicit axis coming out of the screen. The prismatic joint needs an explicit axis parallel to the screen. This axis is fixed in the two bodies and follows their motion.
-
Like the revolute joint, the prismatic joint translation is zero when the joint is created using Initialize(). So be sure zero is between your lower and upper translation limits.
-
Using a prismatic joint is similar to using a revolute joint. Here are the relevant member functions:
A pulley is used to create an idealized pulley. The pulley connects two bodies to ground and to each other. As one body goes up, the other goes down. The total length of the pulley rope is conserved according to the initial configuration.
-
length1 + length2 == constant
-
You can supply a ratio that simulates a block and tackle. This causes one side of the pulley to extend faster than the other. At the same time the constraint force is smaller on one side than the other. You can use this to create mechanical leverage.
-
length1 + ratio * length2 == constant
-
For example, if the ratio is 2, then length1 will vary at twice the rate of length2. Also the force in the rope attached to body1 will have half the constraint force as the rope attached to body2.
-
-
-
-Pulley Joint
-
Pulleys can be troublesome when one side is fully extended. The rope on the other side will have zero length. At this point the constraint equations become singular (bad). You should configure collision shapes to prevent this.
If you want to create a sophisticated mechanical contraption you might want to use gears. In principle you can create gears in Box2D by using compound shapes to model gear teeth. This is not very efficient and might be tedious to author. You also have to be careful to line up the gears so the teeth mesh smoothly. Box2D has a simpler method of creating gears: the gear joint.
-
-
-
-Gear Joint
-
The gear joint can only connect revolute and/or prismatic joints.
-
Like the pulley ratio, you can specify a gear ratio. However, in this case the gear ratio can be negative. Also keep in mind that when one joint is a revolute joint (angular) and the other joint is prismatic (translation), and then the gear ratio will have units of length or one over length.
-
coordinate1 + ratio * coordinate2 == constant
-
Here is an example gear joint. The bodies myBodyA and myBodyB are any bodies from the two joints, as long as they are not the same bodies.
Note that the gear joint depends on two other joints. This creates a fragile situation. What happens if those joints are deleted?
-
-
Caution: Always delete gear joints before the revolute/prismatic joints on the gears. Otherwise your code will crash in a bad way due to the orphaned joint pointers in the gear joint. You should also delete the gear joint before you delete any of the bodies involved.
-
-
-Mouse Joint
-
The mouse joint is used in the testbed to manipulate bodies with the mouse. It attempts to drive a point on a body towards the current position of the cursor. There is no restriction on rotation.
-
The mouse joint definition has a target point, maximum force, frequency, and damping ratio. The target point initially coincides with the body's anchor point. The maximum force is used to prevent violent reactions when multiple dynamic bodies interact. You can make this as large as you like. The frequency and damping ratio are used to create a spring/damper effect similar to the distance joint.
-
Many users have tried to adapt the mouse joint for game play. Users often want to achieve precise positioning and instantaneous response. The mouse joint doesn't work very well in that context. You may wish to consider using kinematic bodies instead.
-
-Wheel Joint
-
The wheel joint restricts a point on bodyB to a line on bodyA. The wheel joint also provides a suspension spring. See b2WheelJoint.h and Car.h for details.
-
-
-
-Wheel Joint
-
-Weld Joint
-
The weld joint attempts to constrain all relative motion between two bodies. See the Cantilever.h in the testbed to see how the weld joint behaves.
-
It is tempting to use the weld joint to define breakable structures. However, the Box2D solver is iterative so the joints are a bit soft. So chains of bodies connected by weld joints will flex.
-
Instead it is better to create breakable bodies starting with a single body with multiple fixtures. When the body breaks, you can destroy a fixture and recreate it on a new body. See the Breakable example in the testbed.
-
-Rope Joint
-
The rope joint restricts the maximum distance between two points. This can be useful to prevent chains of bodies from stretching, even under high load. See b2RopeJoint.h and rope_joint.cpp for details.
-
-Friction Joint
-
The friction joint is used for top-down friction. The joint provides 2D translational friction and angular friction. See b2FrictionJoint.h and apply_force.cpp for details.
-
-Motor Joint
-
A motor joint lets you control the motion of a body by specifying target position and rotation offsets. You can set the maximum motor force and torque that will be applied to reach the target position and rotation. If the body is blocked, it will stop and the contact forces will be proportional the maximum motor force and torque. See b2MotorJoint and motor_joint.cpp for details.
-
-Wheel Joint
-
The wheel joint is designed specifically for vehicles. It provides a translation and rotation. The translation has a spring and damper to simulate the vehicle suspension. The rotation allows the wheel to rotate. You can specify an rotational motor to drive the wheel and to apply braking. See b2WheelJoint, wheel_joint.cpp, and car.cpp for details.
-
-Contacts
-
Contacts are objects created by Box2D to manage collision between two fixtures. If the fixture has children, such as a chain shape, then a contact exists for each relevant child. There are different kinds of contacts, derived from b2Contact, for managing contact between different kinds of fixtures. For example there is a contact class for managing polygon-polygon collision and another contact class for managing circle-circle collision.
-
Here is some terminology associated with contacts.
-
-contact point
-
A contact point is a point where two shapes touch. Box2D approximates contact with a small number of points.
-
-contact normal
-
A contact normal is a unit vector that points from one shape to another. By convention, the normal points from fixtureA to fixtureB.
-
-contact separation
-
Separation is the opposite of penetration. Separation is negative when shapes overlap. It is possible that future versions of Box2D will create contact points with positive separation, so you may want to check the sign when contact points are reported.
-
-contact manifold
-
Contact between two convex polygons may generate up to 2 contact points. Both of these points use the same normal, so they are grouped into a contact manifold, which is an approximation of a continuous region of contact.
-
-normal impulse
-
The normal force is the force applied at a contact point to prevent the shapes from penetrating. For convenience, Box2D works with impulses. The normal impulse is just the normal force multiplied by the time step.
-
-tangent impulse
-
The tangent force is generated at a contact point to simulate friction. For convenience, this is stored as an impulse.
-
-contact ids
-
Box2D tries to re-use the contact force results from a time step as the initial guess for the next time step. Box2D uses contact ids to match contact points across time steps. The ids contain geometric features indices that help to distinguish one contact point from another.
-
Contacts are created when two fixture's AABBs overlap. Sometimes collision filtering will prevent the creation of contacts. Contacts are destroyed with the AABBs cease to overlap.
-
So you might gather that there may be contacts created for fixtures 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. Box2D takes the latter approach because it lets the system cache information to improve performance.
-
-Contact Class
-
As mentioned before, the contact class is created and destroyed by Box2D. Contact objects are not created by the user. However, you are able to access the contact class and interact with it.
You can get access to contacts in several ways. You can access the contacts directly on the world and body structures. You can also implement a contact listener.
You can also access contacts using the contact listener that is described below.
-
-
Caution: Accessing contacts off b2World and b2Body may miss some transient contacts that occur in the middle of the time step. Use b2ContactListener to get the most accurate results.
-
-
-Contact Listener
-
You can receive contact data by implementing b2ContactListener. The contact listener supports several events: begin, end, pre-solve, and post-solve.
Caution: Do not keep a reference to the pointers sent to b2ContactListener. Instead make a deep copy of the contact point data into your own buffer. The example below shows one way of doing this.
-
-
At run-time you can create an instance of the listener and register it with b2World::SetContactListener. Be sure your listener remains in scope while the world object exists.
-
-Begin Contact Event
-
This is called when two fixtures begin to overlap. This is called for sensors and non-sensors. This event can only occur inside the time step.
-
-End Contact Event
-
This is called when two fixtures cease to overlap. This is called for sensors and non-sensors. This may be called when a body is destroyed, so this event can occur outside the time step.
-
-Pre-Solve Event
-
This is called after collision detection, but before collision resolution. This gives you a chance to disable the contact based on the current configuration. For example, you can implement a one-sided platform using this callback and calling b2Contact::SetEnabled(false). The contact will be re-enabled each time through collision processing, so you will need to disable the contact every time-step. The pre-solve event may be fired multiple times per time step per contact due to continuous collision detection.
float approachVelocity = b2Dot(vB -- vA, worldManifold.normal);
-
-
if (approachVelocity > 1.0f)
-
{
-
MyPlayCollisionSound();
-
}
-
}
-
}
-
-Post-Solve Event
-
The post solve event is where you can gather collision impulse results. If you don't care about the impulses, you should probably just implement the pre-solve event.
-
It is tempting to implement game logic that alters the physics world inside a contact callback. For example, you may have a collision that applies damage and try to destroy the associated actor and its rigid body. However, Box2D does not allow you to alter the physics world inside a callback because you might destroy objects that Box2D is currently processing, leading to orphaned pointers.
-
The recommended practice for processing contact points is to buffer all contact data that you care about and process it after the time step. You should always process the contact points immediately after the time step; otherwise some other client code might alter the physics world, invalidating the contact buffer. When you process the contact buffer you can alter the physics world, but you still need to be careful that you don't orphan pointers stored in the contact point buffer. The testbed has example contact point processing that is safe from orphaned pointers.
-
This code from the CollisionProcessing test shows how to handle orphaned bodies when processing the contact buffer. Here is an excerpt. Be sure to read the comments in the listing. This code assumes that all contact points have been buffered in the b2ContactPoint array m_points.
-
// We are going to destroy some bodies according to contact
-
// points. We must buffer the bodies that should be destroyed
-
// because they may belong to multiple contact points.
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.
-
Box2D allows you to achieve custom contact filtering by implementing a b2ContactFilter class. This class requires you to implement a ShouldCollide function that receives two b2Shape pointers. Your function returns true if the shapes should collide.
-
The default implementation of ShouldCollide uses the b2FilterData defined in Chapter 6, Fixtures.
At run-time you can create an instance of your contact filter and register it with b2World::SetContactFilter. Make sure your filter stays in scope while the world exists.
-
MyContactFilter filter;
-
world->SetContactFilter(&filter);
-
// filter remains in scope ...
-
-World
-
The b2World class 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 Box2D will be with a b2World object.
-
-Creating and Destroying a World
-
Creating a world is fairly simple. You just need to provide a gravity vector and a Boolean indicating if bodies can sleep. Usually you will create and destroy a world using new and delete.
The world class contains factories for creating and destroying bodies and joints. These factories are discussed later in the sections on bodies and joints. There are some other interactions with b2World that I will cover now.
-
-Simulation
-
The world class is used to drive the simulation. You specify a time step and a velocity and position iteration 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 actors and render them. 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.
-
As I discussed above in the HelloWorld tutorial, 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 no larger than 1/30 seconds. A time step of 1/60 seconds will usually deliver a high quality simulation.
-
The iteration count controls how many times the constraint solver sweeps over all the contacts and joints in the world. More iteration always yields a better simulation. But don't trade a small time step for a large iteration count. 60Hz and 10 iterations is far better than 30Hz and 20 iterations.
-
After stepping, you should clear any forces you have applied to your bodies. This is done with the command b2World::ClearForces. This lets you take multiple sub-steps with the same force field.
The world is a container for bodies, contacts, and joints. You can grab the body, contact, and joint lists off the world and iterate over them. For example, this code wakes up all the bodies in the world:
myWorld->DestroyBody(b); // ERROR: now GetNext returns garbage.
-
}
-
}
-
Everything goes ok until a body is destroyed. Once a body is destroyed, its next pointer becomes invalid. So the call to b2Body::GetNext() will return garbage. The solution to this is to copy the next pointer before destroying the body.
This safely destroys the current body. However, you may want to call a game function that may destroy multiple bodies. In this case you need to be very careful. The solution is application specific, but for convenience I'll show one method of solving the problem.
Obviously to make this work, GameCrazyBodyDestroyer must be honest about what it has destroyed.
-
-AABB Queries
-
Sometimes you want to determine all the shapes in a region. The b2World class has a fast log(N) method for this using the broad-phase data structure. You provide an AABB in world coordinates and an implementation of b2QueryCallback. The world calls your class with each fixture whose AABB overlaps the query AABB. Return true to continue the query, otherwise return false. For example, the following code finds all the fixtures that potentially intersect a specified AABB and wakes up all of the associated bodies.
You cannot make any assumptions about the order of the callbacks.
-
-Ray Casts
-
You can use ray casts to do line-of-sight checks, fire guns, etc. You perform a ray cast by implementing a callback class and providing the start and end points. The world class calls your class with each fixture hit by the ray. Your callback is provided with the fixture, 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 callbacks.
-
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 of fraction of -1 to filter the fixture. Then the ray cast will proceed as if the fixture does not exist.
Caution: Due to round-off errors, ray casts can sneak through small cracks between polygons in your static environment. If this is not acceptable in your application, trying slightly overlapping your polygons.
In the distribution of Box2D is a Hello World project. The program creates a large ground box and a small dynamic box. This code does not contain any graphics. All you will see is text output in the console of the box's position over time.
-
This is a good example of how to get up and running with Box2D.
-
-Creating a World
-
Every Box2D program begins with the creation of a b2World object. b2World is the physics hub that manages memory, objects, and simulation. You can allocate the physics world on the stack, heap, or data section.
-
It is easy to create a Box2D world. First, we define the gravity vector.
For step 2 the body definition is passed to the world object to create the ground body. The world object does not keep a reference to the body definition. Bodies are static by default. Static bodies don't collide with other static bodies and are immovable.
For step 3 we create a ground polygon. We use the SetAsBox shortcut to form the ground polygon into a box shape, with the box centered on the origin of the parent body.
The SetAsBox function takes the half-**width** and half-**height** (extents). So in this case the ground box is 100 units wide (x-axis) and 20 units tall (y-axis). Box2D is tuned for meters, kilograms, and seconds. So you can consider the extents to be in meters. Box2D generally works best when objects are the size of typical real world objects. For example, a barrel is about 1 meter tall. Due to the limitations of floating point arithmetic, using Box2D to model the movement of glaciers or dust particles is not a good idea.
-
We finish the ground body in step 4 by creating the shape fixture. For this step we have a shortcut. We do not have a need to alter the default fixture material properties, so we can pass the shape directly to the body without creating a fixture definition. Later we will see how to use a fixture definition for customized material properties. The second parameter is the shape density in kilograms per meter squared. A static body has zero mass by definition, so the density is not used in this case.
Box2D does not keep a reference to the shape. It clones the data into a new b2Shape object.
-
Note that every fixture must have a parent body, even fixtures that are static. However, you can attach all static fixtures to a single static body.
-
When you attach a shape to a body using a fixture, the shape's coordinates become local to the body. So when the body moves, so does the shape. A fixture's world transform is inherited from the parent body. A fixture does not have a transform independent of the body. So we don't move a shape around on the body. Moving or modifying a shape that is on a body is not supported. The reason is simple: a body with morphing shapes is not a rigid body, but Box2D is a rigid body engine. Many of the assumptions made in Box2D are based on the rigid body model. If this is violated many things will break
-
-Creating a Dynamic Body
-
So now we have a ground body. We can use the same technique to create a dynamic body. The main difference, besides dimensions, is that we must establish the dynamic body's mass properties.
-
First we create the body using CreateBody. By default bodies are static, so we should set the b2BodyType at construction time to make the body dynamic.
Next we create a fixture definition using the box. Notice that we set density to 1. The default density is zero. Also, the friction on the shape is set to 0.3.
Caution: A dynamic body should have at least one fixture with a non-zero density. Otherwise you will get strange behavior.
-
-
Using the fixture definition we can now create the fixture. This automatically updates the mass of the body. You can add as many fixtures as you like to a body. Each one contributes to the total mass.
That's it for initialization. We are now ready to begin simulating.
-
-Simulating the World
-
So we have initialized the ground box and a dynamic box. Now we are ready to set Newton loose to do his thing. We just have a couple more issues to consider.
-
Box2D uses a computational algorithm called an integrator. Integrators simulate the physics equations at discrete points of time. This goes along with the traditional game loop where we essentially have a flip book of movement on the screen. So we need to pick a time step for Box2D. Generally physics engines for games like a time step at least as fast as 60Hz or 1/60 seconds. You can get away with larger time steps, but you will have to be more careful about setting up the definitions for your world. We also don't like the time step to change much. A variable time step produces variable results, which makes it difficult to debug. So don't tie the time step to your frame rate (unless you really, really have to). Without further ado, here is the time step.
-
float timeStep = 1.0f / 60.0f;
-
In addition to the integrator, Box2D also uses a larger bit of code called a constraint solver. The constraint solver solves all the constraints in the simulation, one at a time. A single constraint can be solved perfectly. However, when we solve one constraint, we slightly disrupt other constraints. To get a good solution, we need to iterate over all constraints a number of times.
-
There are two phases in the constraint solver: a velocity phase and a position phase. In the velocity phase the solver computes the impulses necessary for the bodies to move correctly. In the position phase the solver adjusts the positions of the bodies to reduce overlap and joint detachment. Each phase has its own iteration count. In addition, the position phase may exit iterations early if the errors are small.
-
The suggested iteration count for Box2D is 8 for velocity and 3 for position. You can tune this number to your liking, just keep in mind that this has a trade-off between performance and accuracy. Using fewer iterations increases performance but accuracy suffers. Likewise, using more iterations decreases performance but improves the quality of your simulation. For this simple example, we don't need much iteration. Here are our chosen iteration counts.
-
int32 velocityIterations = 6;
-
int32 positionIterations = 2;
-
Note that the time step and the iteration count are completely unrelated. An iteration is not a sub-step. One solver iteration is a single pass over all the constraints within a time step. You can have multiple passes over the constraints within a single time step.
-
We are now ready to begin the simulation loop. In your game the simulation loop can be merged with your game loop. In each pass through your game loop you call b2World::Step. Just one call is usually enough, depending on your frame rate and your physics time step.
-
The Hello World program was designed to be simple, so it has no graphical output. The code prints out the position and rotation of the dynamic body. Here is the simulation loop that simulates 60 time steps for a total of 1 second of simulated time.
The output shows the box falling and landing on the ground box. Your output should look like this:
-
0.00 4.00 0.00
-
0.00 3.99 0.00
-
0.00 3.98 0.00
-
...
-
0.00 1.25 0.00
-
0.00 1.13 0.00
-
0.00 1.01 0.00
-
-Cleanup
-
When a world leaves scope or is deleted by calling delete on a pointer, all the memory reserved for bodies, fixtures, and joints is freed. This is done to improve performance and make your life easier. However, you will need to nullify any body, fixture, or joint pointers you have because they will become invalid.
The b2Fixture, b2Body, and b2Joint classes allow you to attach user data as a uintptr_t. This is handy when you are examining Box2D data structures and you want to determine how they relate to the objects in your game engine.
-
For example, it is typical to attach an actor pointer to the rigid body on that actor. This sets up a circular reference. If you have the actor, you can get the body. If you have the body, you can get the actor.
You can also use this to hold an integral value rather than a pointer.
-
Here are some examples of cases where you would need the user data:
-
Applying damage to an actor using a collision result.
-
Playing a scripted event if the player is inside an axis-aligned box.
-
Accessing a game structure when Box2D notifies you that a joint is going to be destroyed.
-
-
Keep in mind that user data is optional and you can put anything in it. However, you should be consistent. For example, if you want to store an actor pointer on one body, you should keep an actor pointer on all bodies. Don't store an actor pointer on one body, and a foo pointer on another body. Casting an actor pointer to a foo pointer may lead to a crash.
-
User data pointers are 0 by default.
-
For fixtures you might consider defining a user data structure that lets you store game specific information, such as material type, effects hooks, sound hooks, etc.
You can define custom data structures that are embedded in the Box2D data structures. This is done by defining B2_USER_SETTINGS and providing the file b2_user_settings.h. See b2_settings.h for details.
-
-Implicit Destruction
-
Box2D doesn't use reference counting. So if you destroy a body it is really gone. Accessing a pointer to a destroyed body has undefined behavior. In other words, your program will likely crash and burn. To help fix these problems, the debug build memory manager fills destroyed entities with FDFDFDFD. This can help find problems more easily in some cases.
-
If you destroy a Box2D entity, it is up to you to make sure you remove all references to the destroyed object. This is easy if you only have a single reference to the entity. If you have multiple references, you might consider implementing a handle class to wrap the raw pointer.
-
Often when using Box2D you will create and destroy many bodies, shapes, and joints. Managing these entities is somewhat automated by Box2D. If you destroy a body then all associated shapes and joints are automatically destroyed. This is called implicit destruction.
-
When you destroy a body, all its attached shapes, joints, and contacts are destroyed. This is called implicit destruction. Any body connected to one of those joints and/or contacts is woken. This process is usually convenient. However, you must be aware of one crucial issue:
-
-
Caution: When a body is destroyed, all fixtures and joints attached to the body are automatically destroyed. You must nullify any pointers you have to those shapes and joints. Otherwise, your program will die horribly if you try to access or destroy those shapes or joints later.
-
-
To help you nullify your joint pointers, Box2D provides a listener class named b2DestructionListener that you can implement and provide to your world object. Then the world object will notify you when a joint is going to be implicitly destroyed
-
Note that there no notification when a joint or fixture is explicitly destroyed. In this case ownership is clear and you can perform the necessary cleanup on the spot. If you like, you can call your own implementation of b2DestructionListener to keep cleanup code centralized.
-
Implicit destruction is a great convenience in many cases. It can also make your program fall apart. You may store pointers to shapes and joints somewhere in your code. These pointers become orphaned when an associated body is destroyed. The situation becomes worse when you consider that joints are often created by a part of the code unrelated to management of the associated body. For example, the testbed creates a b2MouseJoint for interactive manipulation of bodies on the screen.
-
Box2D provides a callback mechanism to inform your application when implicit destruction occurs. This gives your application a chance to nullify the orphaned pointers. This callback mechanism is described later in this manual.
-
You can implement a b2DestructionListener that allows b2World to inform you when a shape or joint is implicitly destroyed because an associated body was destroyed. This will help prevent your code from accessing orphaned pointers.
You can then register an instance of your destruction listener with your world object. You should do this during world initialization.
-
myWorld->SetListener(myDestructionListener);
-
-Pixels and Coordinate Systems
-
Recall that Box2D uses MKS (meters, kilograms, and seconds) units and radians for angles. You may have trouble working with meters because your game is expressed in terms of pixels. To deal with this in the testbed I have the whole game work in meters and just use an OpenGL viewport transformation to scale the world into screen space.
If your game must work in pixel units then you should convert your length units from pixels to meters when passing values from Box2D. Likewise you should convert the values received from Box2D from meters to pixels. This will improve the stability of the physics simulation.
-
You have to come up with a reasonable conversion factor. I suggest making this choice based on the size of your characters. Suppose you have determined to use 50 pixels per meter (because your character is 75 pixels tall). Then you can convert from pixels to meters using these formulas:
-
xMeters = 0.02f * xPixels;
-
yMeters = 0.02f * yPixels;
-
In reverse:
-
xPixels = 50.0f * xMeters;
-
yPixels = 50.0f * yMeters;
-
You should consider using MKS units in your game code and just convert to pixels when you render. This will simplify your game logic and reduce the chance for errors since the rendering conversion can be isolated to a small amount of code.
-
If you use a conversion factor, you should try tweaking it globally to make sure nothing breaks. You can also try adjusting it to improve stability.
-
-Debug Drawing
-
You can implement the b2DebugDraw class to get detailed drawing of the physics world. Here are the available entities:
-
shape outlines
-
joint connectivity
-
broad-phase axis-aligned bounding boxes (AABBs)
-
center of mass
-
-
-
-
-Debug Draw
-
This is the preferred method of drawing these physics entities, rather than accessing the data directly. The reason is that much of the necessary data is internal and subject to change.
-
The testbed draws physics entities using the debug draw facility and the contact listener, so it serves as the primary example of how to implement debug drawing as well as how to draw contact points.
-
-Limitations
-
Box2D uses several approximations to simulate rigid body physics efficiently. This brings some limitations.
-
Here are the current limitations:
-
Stacking heavy bodies on top of much lighter bodies is not stable. Stability degrades as the mass ratio passes 10:1.
-
Chains of bodies connected by joints may stretch if a lighter body is supporting a heavier body. For example, a wrecking ball connect to a chain of light weight bodies may not be stable. Stability degrades as the mass ratio passes 10:1.
-
There is typically around 0.5cm of slop in shape versus shape collision.
-
Continuous collision does not handle joints. So you may see joint stretching on fast moving objects.
-
Box2D uses the symplectic Euler integration scheme. It does not reproduce parabolic motion of projectiles and has only first-order accuracy. However it is fast and has good stability.
-
Box2D uses an iterative solver to provide real-time performance. You will not get precisely rigid collisions or pixel perfect accuracy. Increasing the iterations will improve accuracy.
Once you have conquered the HelloWorld example, you should start looking at Box2D's testbed. The testbed is a testing framework and demo environment. Here are some of the features:
-
Camera with pan and zoom.
-
Mouse picking of shapes attached to dynamic bodies.
-
Extensible set of tests.
-
GUI for selecting tests, parameter tuning, and debug drawing options.
-
Pause and single step simulation.
-
Text rendering.
-
-
-
-
-Box2D Testbed
-
The testbed has many examples of Box2D usage in the test cases and the framework itself. I encourage you to explore and tinker with the testbed as you learn Box2D.
-
Note: the testbed is written using GLFW and imgui. The testbed is not part of the Box2D library. The Box2D library is agnostic about rendering. As shown by the HelloWorld example, you don't need a renderer to use Box2D.
Box2D is a feature rich 2D rigid body physics engine, written in C11 by Erin Catto. It has been used in many games and in many game engines.
+
Box2D is a feature rich 2D rigid body physics engine, written in C17 by Erin Catto. It has been used in many games and in many game engines.
Box2D uses the MIT license license and can be used free of charge. Credit should be included if possible. Support is appreciated. You may use the Box2D logo.
What platforms does Box2D support?
-
Box2D is developed using C11. Ports and bindings are likely available for most languages and platforms.
-
Erin Catto maintains the C11 version, but provides no support for other languages. Other languages are supported by the community and possibly by the authors of those ports.
+
Box2D is developed using C17. Ports and bindings are likely available for most languages and platforms.
+
Erin Catto maintains the C17 version, but provides no support for other languages. Other languages are supported by the community and possibly by the authors of those ports.
Who makes it?
-
Erin Catto is the creator and sole contributor of the C11 version of Box2D, with various others supporting the ports. Box2D is an open source project, and accepts community feedback.
+
Erin Catto is the creator and sole contributor of the C17 version of Box2D, with various others supporting the ports. Box2D is an open source project, and accepts community feedback.
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.
Since chains are their own concept now, they get their own identifier, b2ChainId. You can view chains as macro objects, they create many b2SmoothSegment shapes internally. Normally you don't interact with these. However they are returned from queries. You can use b2Shape_GetParentChain() to get the b2ChainId for a smooth segment that you get from a query.
DO NOT destroy or modify a b2SmoothSegment that belongs to a chain shape directly
Some of the joints have more options now. Check the code comments and samples for details.
@@ -307,7 +307,7 @@
Therefore all callbacks except PreSolve have been removed. Instead you can now access all events and contact data after the time step. Version 3.0 no longer uses collision sub-stepping for continuous collision. This means all contacts data are valid at the end of the time step. Just keep in mind that Box2D computes contact points at the beginning of the time step, so the contact points apply to the previous position of the body.
A hit touch event is generated when two shapes collide with a speed faster than the hit speed thresho...
Definition types.h:944
You can loop through these events after the time step. These events are in deterministic order, even with multithreading. See the sample_events.cpp file for examples.
You may not want Box2D to save all contact events, so you can disable them for a given shape using enableContactEvents on b2ShapeDef.
If you want to access persistent contacts, you can get the data from bodies or shapes.
Register the pre-solve callback. This is optional.
You can define a pre-solve callback and register that with the world. You can also provide a context variable that will be passed back to your callback. This is not enough to get a pre-solve callback. You also need to enable it on your shape using enablePreSolveEvents in b2ShapeDef. This is false by default.
@@ -349,7 +349,7 @@
Sensors
In v2.4 sensor events were mixed in with contact events. I have split them up to make user code simpler.
The segment normal depends on the winding order. A counter-clockwise winding order orients the normal outwards and a clockwise winding order orients the normal inwards.
An end touch event is generated when a shape stops overlapping a sensor shape.
Definition types.h:896
You will not get end events if a shape is destroyed. Sensor events should be processed after the world step and before other game logic. This should help you avoid processing stale data.
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 b2Body_GetContactData().
A hit touch event is generated when two shapes collide with a speed faster than the hit speed thresho...
Definition types.h:944
Shapes only generate hit events if b2ShapeDef::enableHitEvents is true. I recommend you only enable this for shapes that need hit events because it creates some overhead. Box2D also only reports hit events that have an approach speed larger than b2WorldDef::hitEventThreshold.
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. Box2D will assert if you use a dangling joint id.
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 spring linear stiffness Hertz, cycles per second.
Definition types.h:494
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 b2DistanceJointDef and the DistanceJoint sample for details.
The revolute joint has an implicit axis coming out of the screen. The prismatic joint needs an explicit axis parallel to the screen. This axis is fixed in body A.
The prismatic joint translation is zero when the anchor points overlap. I recommend to have the prismatic anchor points close to the center of mass of the two bodies. This will improve joint stiffness.
Using a prismatic joint is similar to using a revolute joint. Here are the relevant member functions:
A body definition holds all the data needed to construct a rigid body. You can safely re-use body definitions. Shapes are added to a body after construction.
Angular damping is use to reduce the angular velocity. The damping parameter can be larger than 1.0f but the damping effect becomes sensitive to the time step when the damping parameter is large. Units are 1/time
Is this a fast moving body that should be prevented from tunneling through other moving bodies? Note that all bodies are prevented from tunneling through kinematic and static bodies. This setting is only considered on dynamic bodies.
Warning
You should use this flag sparingly since it increases processing time.
Linear damping is use to reduce the linear velocity. The damping parameter can be larger than 1.0f but the damping effect becomes sensitive to the time step when the damping parameter is large. Units are 1/time
A contact edge is used to connect bodies and contacts together in a contact graph where each body is a node and each contact is an edge. A contact edge belongs to a doubly linked list maintained in each attached body. Each contact has two contact nodes, one for each attached body.
-
The documentation for this struct was generated from the following file:
Contact impulses for reporting. Impulses are used instead of forces because sub-step forces may approach infinity for rigid body collisions. These match up one-to-one with the contact points in b2Manifold.
-
The documentation for this struct was generated from the following file:
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Distance joint definition. This requires defining an anchor point on both bodies and the non-zero distance of the distance joint. The definition uses local anchor points so that the initial configuration can violate the constraint slightly. This helps when saving and loading a game.
Collision groups allow a certain group of objects to never collide (negative) or always collide (positive). Zero means no collision group. Non-zero group filtering always wins against the mask bits.
A joint edge is used to connect bodies and joints together in a joint graph where each body is a node and each joint is an edge. A joint edge belongs to a doubly linked list maintained in each attached body. Each joint has two joint nodes, one for each attached body.
-
The documentation for this struct was generated from the following file:
A manifold for two touching convex shapes. Box2D supports multiple types of contact:
-
clip point versus plane with radius
-
point versus point with radius (circles) The local point usage depends on the manifold type: -e_circles: the local center of circleA -e_faceA: the center of faceA -e_faceB: the center of faceB Similarly the local normal usage: -e_circles: not used -e_faceA: the normal on polygonA -e_faceB: the normal on polygonB We store contacts in this way so that position correction can account for movement, which is critical for continuous physics. All contact scenarios must be expressed in one of these types. This structure is stored across time steps, so we keep it small.
-
-
The documentation for this struct was generated from the following file:
uniquely identifies a contact point between two shapes
-
-
-
Detailed Description
-
A manifold point is a contact point belonging to a contact manifold. It holds details related to the geometry and dynamics of the contact points. The local point usage depends on the manifold type: -e_circles: the local center of circleB -e_faceA: the local center of cirlceB or the clip point of polygonB -e_faceB: the clip point of polygonA This structure is stored across time steps, so we keep it small. Note: the impulses are used for internal caching and may not provide reliable contact forces, especially for high speed collisions.
-
The documentation for this struct was generated from the following file:
Solve A * x = b, where b is a column vector. This is more efficient than computing the inverse in one-shot cases. Solve only the upper 2-by-2 matrix equation.
The maximum constraint force that can be exerted to move the candidate body. Usually you will express as some multiple of the weight (multiplier * mass * gravity).
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Prismatic joint definition. This requires defining a line of motion using an axis and an anchor point. The definition uses local anchor points and a local axis so that the initial configuration can violate the constraint slightly. The joint translation is zero when the local anchor points coincide in world space. Using local anchors and a local axis helps when saving and loading a game.
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Revolute joint definition. This requires defining an anchor point where the bodies are joined. The definition uses local anchor points so that the initial configuration can violate the constraint slightly. You also need to specify the initial relative angle for joint limits. This helps when saving and loading a game. The local anchor points are measured from the body's origin rather than the center of mass because:
-
you might not know where the center of mass will be.
-
if you add/remove shapes from a body and recompute the mass, the joints will be broken.
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Rope joint definition. This requires two body anchor points and a maximum lengths. Note: by default the connected objects will not collide. see collideConnected in b2JointDef.
This describes the motion of a body/shape for TOI computation. Shapes are defined with respect to the body origin, which may no coincide with the center of mass. However, to support dynamics we must interpolate the center of mass position.
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Weld joint definition. You need to specify local anchor points where they are attached and the relative body angle. The position of the anchor points is important for computing the reaction torque.
Set this flag to true if the attached bodies should collide.
-
-
-
Detailed Description
-
Wheel joint definition. This requires defining a line of motion using an axis and an anchor point. The definition uses local anchor points and a local axis so that the initial configuration can violate the constraint slightly. The joint translation is zero when the local anchor points coincide in world space. Using local anchors and a local axis helps when saving and loading a game.
Evaluate the manifold with supplied transforms. This assumes modest motion from the original state. This does not change the point count, impulses, etc. The radii must come from the shapes that generated the manifold.
-
-
-
-The documentation for this struct was generated from the following file:
1.8.17
- 
-
-
Public Member Functions inherited from 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-