Add initial prototype.
This commit is contained in:
Rod Kay
216
3-mid/physics/implement/box2d/contrib/docs/overview.md
Normal file
216
3-mid/physics/implement/box2d/contrib/docs/overview.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Overview
|
||||
Box2D is a 2D rigid body simulation library for games. Programmers can
|
||||
use it in their games to make objects move in realistic ways and make
|
||||
the game world more interactive. From the game engine's point of view,
|
||||
a physics engine is just a system for procedural animation.
|
||||
|
||||
Box2D is written in portable C++. Most of the types defined in the
|
||||
engine begin with the b2 prefix. Hopefully this is sufficient to avoid
|
||||
name clashing with your game engine.
|
||||
|
||||
## Prerequisites
|
||||
In this manual I'll assume you are familiar with basic physics
|
||||
concepts, such as mass, force, torque, and impulses. If not, please
|
||||
first consult Google search and Wikipedia.
|
||||
|
||||
Box2D was created as part of a physics tutorial at the Game Developer
|
||||
Conference. You can get these tutorials from the download section of
|
||||
box2d.org.
|
||||
|
||||
Since Box2D is written in C++, you are expected to be experienced in C++
|
||||
programming. Box2D should not be your first C++ programming project! You
|
||||
should be comfortable with compiling, linking, and debugging.
|
||||
|
||||
> **Caution**:
|
||||
> Box2D should not be your first C++ project. Please learn C++
|
||||
> programming, compiling, linking, and debugging before working with
|
||||
> Box2D. There are many resources for this on the net.
|
||||
|
||||
## Scope
|
||||
This manual covers the majority of the Box2D API. However, not every
|
||||
aspect is covered. Please look at the testbed included
|
||||
with Box2D to learn more.
|
||||
|
||||
This manual is only updated with new releases. The latest version of
|
||||
Box2D may be out of sync with this manual.
|
||||
|
||||
## Feedback and Bugs
|
||||
Please file bugs and feature requests here:
|
||||
[Box2D Issues](https://github.com/erincatto/box2d/issues)
|
||||
|
||||
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.
|
||||
|
||||
There is also a [Discord server](https://discord.gg/NKYgCBP) and a
|
||||
[subreddit](https://reddit.com/r/box2d) for Box2D.
|
||||
|
||||
## Core Concepts
|
||||
Box2D works with several fundamental concepts and objects. We briefly
|
||||
define these objects here and more details are given later in this
|
||||
document.
|
||||
|
||||
#### shape
|
||||
A shape is 2D geometrical object, such as a circle or polygon.
|
||||
|
||||
#### rigid body
|
||||
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 body.
|
||||
|
||||
#### fixture
|
||||
A fixture binds a shape to a body and adds material properties such as
|
||||
density, friction, and restitution. A fixture puts a shape into the
|
||||
collision system (broad-phase) so that it can collide with other shapes.
|
||||
|
||||
#### constraint
|
||||
A constraint is a physical connection that removes degrees of freedom
|
||||
from bodies. A 2D 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 example, 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.
|
||||
|
||||
|
||||
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 impact (TOI). Second, there is a sub-stepping solver
|
||||
that moves bodies to their first time of impact and then resolves the
|
||||
collision.
|
||||
|
||||
## Modules
|
||||
Box2D 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.
|
||||
|
||||
|
||||
## 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 (MKS) units. In particular, Box2D has
|
||||
been tuned to work well with moving shapes between 0.1 and 10 meters. So
|
||||
this means objects between soup cans and buses in size should work well.
|
||||
Static shapes may be up to 50 meters long without 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. You can also account for flipped coordinate axes.
|
||||
|
||||
Another limitation to consider is overall world size. If your world units
|
||||
become larger than 2 kilometers or so, then the lost precision can affect
|
||||
stability.
|
||||
|
||||
> **Caution**:
|
||||
> Box2D works best with world sizes less than 2 kilometers. Use
|
||||
> b2World::ShiftOrigin to support larger worlds.
|
||||
|
||||
If you need to have a larger game world, consider using
|
||||
b2World::ShiftOrigin to keep the world origin close to your player. I recommend
|
||||
to use grid lines along with some hysteresis for triggering calls to ShiftOrigin.
|
||||
This call should be made infrequently because it is has CPU cost. You may
|
||||
need to store a physics offset when translating between game units and Box2D units.
|
||||
|
||||
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 `b2Body::SetTransform`).
|
||||
|
||||
> **Caution**:
|
||||
> Box2D uses radians, not degrees.
|
||||
|
||||
## Changing the length units
|
||||
Advanced users may change the length unit modifying `b2_lengthUnitsPerMeter`.
|
||||
You can avoid merge conflicts by defining `B2_USER_SETTINGS` and providing
|
||||
`b2_user_settings.h`. See the file `b2_settings.h` for details.
|
||||
|
||||
## Factories and Definitions
|
||||
Fast memory management plays a central role in the design of the Box2D
|
||||
API. So when you create a b2Body 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:
|
||||
|
||||
```cpp
|
||||
b2Body* b2World::CreateBody(const b2BodyDef* def)
|
||||
b2Joint* b2World::CreateJoint(const b2JointDef* def)
|
||||
```
|
||||
|
||||
And there are corresponding destruction functions:
|
||||
|
||||
```cpp
|
||||
void b2World::DestroyBody(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 (shapes) must be parented to a body, they are created and
|
||||
destroyed using a factory method on b2Body:
|
||||
|
||||
```cpp
|
||||
b2Fixture* b2Body::CreateFixture(const b2FixtureDef* def)
|
||||
void b2Body::DestroyFixture(b2Fixture* fixture)
|
||||
```
|
||||
|
||||
There is also shortcut to create a fixture directly from the shape and
|
||||
density.
|
||||
|
||||
```cpp
|
||||
b2Fixture* b2Body::CreateFixture(const b2Shape* shape, float density)
|
||||
```
|
||||
|
||||
Factories do not retain references to the definitions. So you can create
|
||||
definitions on the stack and keep them in temporary resources.
|
||||
Reference in New Issue
Block a user