box2d-官方-Manual
Box2D issues are tracked using a google code project this is a great way to track issues and ensures that your issue will not be lost in the depths of the forums Pleasefilebugsandfeaturerequestsherehttp://code.googlecom/p/box2d/ You can help to ensure your issue gets fixed if you provide sufficient detail. a testbed example that reproduces the problem is ideal. You can read about the testbed later in this document 1.5 Core Concepts Box2D works with several fundamental objects we briefly define these objects here and more details are given later in this document shape A 2D geometrical object, such as a circle or polygon rigid bod a chunk of matter that is so strong that the distance between any two bits of matter on the chunk is constant. They are hard like a diamond In the following discussion we use body interchangeably with rigid bod f Xture a fixture binds a shape to a body and adds material properties such as density friction, and restitution constraint a constraint is a physical connection that removes degrees of freedom from bodies. In 2d a body has 3 degrees of freedom two translation coordinates and one rotation coordinate if we take a body and pin it to the wall (like a pendulum we have constrained the body to the wall. at this point the body can only rotate about the pin, so the constraint has removed 2 degrees of freedom contact constraint A special constraint designed to prevent penetration of rigid bodies and to simulate friction and restitution. You do not create contact constraints; they are created automatically by box2D joint This is a constraint used to hold two or more bodies together. Box2D supports several joint types revolute, prismatic, distance, and more. Some joints may have limits and motors joint limit a joint limit restricts the range of motion of a joint For example the human elbow only allows a certain range of angles. Joint motor A joint motor drives the motion of the connected bodies according to the joint's degrees of freedom. For xample, you can use a motor to drive the rotation of an elbow world a physics world is a collection of bodies fixtures and constraints that interact together Box2D supports the creation of multiple worlds, but this is usually not necessary or desirable solver The physics world has a solver that is used to advance time and to resolve contact and joint constraints The box2D solver is a high performance iterative solver that operates in order n time, where n is the number of constraints continuous collision The solver advances bodies in time using discrete time steps Without intervention this can lead to tunneling ime1 timeo Tunneling Effect BOX2D contains specialized algorithms to deal with tunneling. First, the collision algorithms can interpolate the motion of two bodies to find the first time of impace(toi). Second there is a sub stepping solver that moves bodies to their first time of impact and then resolves the collision 1.6 Modules Box 2D is composed of three modules: Common Collision, and dynamics. the common module has code for allocation, math and settings. the collision module defines shapes a broad-phase, and collision functions/queries. Finally the dynamics module provides the simulation world bodies, fixtures and joints. Common Collision Dynamics 1. Units BoX2D works with floating point numbers and tolerances have to be used to make box2D perform well These tolerances have been tuned to work well with meters-kilogram-second (mksunits. In particular, Box2D has been tuned to work well with moving objects between 0. 1 and 10 meters So this means objects between soup cans and buses in size should work well static objects may be up to 50 meters big without too much trouble Being a 2D physics engine, it is tempting to use pixels as your units. Unfortunately this will lead to a poor simulation and possibly weird behavior. An object of length 200 pixels would be seen by box2D as the size of a 45 story building Caution Box2D is tuned for MKS units. Keep the size of moving objects roughly between 0. 1 and 10 meters. You'll need to use some scaling system when you render your environment and actors. The box2D testbed does this by using an OpenGL viewport transform. DO NOT USE PIXELS It is best to think of Box2D bodies as moving billboards upon which you attach your artwork. The billboard may move in a unit system of meters, but you can convert that to pixel coordinates with a simple scaling factor. You can then use those pixel coordinates to place your sprites, etc BOX2D uses radians for angles. The body rotation is stored in radians and may grow unbounded Consider normalizing the angle of your bodies if the magnitude of the angle becomes too large(use b2 Body: SetAngle) 1. 8 Factories and Definitions Memory management plays a central role in the design of the box2D APl So when you create a b2 body or a b2Joint, you need to call the factory functions on b2World You should never try to allocate these types in another manner. There are creation functions b2Body* b2World: Create Body (const b2Body Def* def) b2Joint* b2World:: CreateJoint(const b2JointDef* def) And there are corresponding destruction functions: void b2World: Destroy Body (b2Body* body) void b2World: DestroyJoint(b2Joint* joint) When you create a body or joint, you need to provide a definition these definitions contain all the information needed to build the body or joint By using this approach we can prevent construction errors, keep the number of function parameters small, provide sensible defaults, and reduce the number of accessors Since fixtures must be parented to a body they are created and destroyed using a factory method on b2Bod b2Fixture* b2Body: CreateFixture (const b2FixtureDef* def) void b2Body: Destroy Fixture(b2Fixture* fixture) There is also shortcut to create a fixture directly from the shape and density b2Fixture* b2Body:: CreateFixture (const b2Shape* shape, float32 density) Factories do not retain references to the definitions. So you can create definitions on the stack and keep them in temporary resources 1.9 User data The b2 Fixture, b2Body and b2Joint classes allow you to attach user data as a void pointer. this is hand when you are examining box2d data structures and you want to determine how they relate to the entities 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. GameActor* actor Game CreateActor (; b2BodyDef body Def; body Def. userData actor actor->body box2Dworld->Create Body(&body Def); 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 nUll by default Chapter 2 Hello box2D n 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 2.1 Creating a World Every box2D program begins with the creation of a b2 World 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. also we tell the world to allow bodies to sleep when they come to rest. a sleeping body doesn't require any simulation b2Vec2 gravity(0. of, -100f); booⅠ dogsleep=true; Now we create the world object Note that we are creating the world on the stack, so the world must remain in scope b2World world(gravity, dosleep); So now we have our physics world, let's start adding some stuff to it 2.2 Creating a Ground Box Bodies are built using the following steps: Define a body with position, damping, etc 1234 Use the world object to create the body Define fixtures with a shape, friction, density etc Create fixtures on the body For step 1 we create the ground body for this we need a body definition With the body definition we specify the initial position of the ground body b2BodyDef ground Body Def; groundBody Def position Set(eof, -10of); 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 b2Body*ground Body= world. CreateBody(&groundBodyDef) For step 3 we create a ground polygon We use the setAs Box shortcut to form the ground polygon into a box shape, with the box centered on the origin of the parent body b2PolygonShape groundBox groundBox SetAsBox(50 of, 10.0f), The SetAs Box 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 groundBody->Create Fixture(&groundBox, 0 of) Box 2D 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 bod 2.3 Creating a Dynamic bod 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 b2Body type at construction time to make the body dynamic b2 Body Def body Def body Def. type = b2 dynamicBody body Def. position Set(oof,4.0f) b2 Body* body world Create Body (&body Def Caution You must set the body type to b2 dynamic Body if you want the body to move in response to forces Next we create and attach a polygon shape using a fixture definition. First we create a box shape b2Polygon Shape dynamicBox; dynamicBox SetAs Box(1 of, 1.0f); 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 b2FixtureDef fixtureDef fixtureDef. shape =&dynamicBox; fixtureDef. density =1.of fixtureDef. friction =0. 3f 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 body->CreateFixture(&fixtureDef); That's it for initialization. We are now ready to begin simulating 2.4 Simulating the World (of Box2D) 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 t 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