General FAQ
From Box2D Wiki
Contents |
About
What is this wiki
This wiki is the community run help for the Box2D engine, it's derivatives, and general 2d physics. For personal support, try the forum.
What is Box2D
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.
What platforms does Box2D support?
Box2D is developed on Windows using MSVC 2005. Other platforms are supported by community contributions, including Linux and fixed point embedded devices. Ports are also available for Flash, Java, C#, Python.
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 changes.
Where is official Documentation
The manual is the best source of information, but many sources of documentation are available.
What are the 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.
How does Box2D compare to...
Rendering
What are Box2D's rendering capabilites
Box2D is only a physics engine. How you draw stuff is up to you. But the Testbed draws stuff. There is seperate advice for AS3
Visualization is very important for debugging collision and physics. The TestBed is there to help test Box2D and give you examples of how to use Box2D. The TestBed is not part of the Box2D library.
Why is the shape data all messed up
Boxes are converted into polygons and polygons have all their vertices resolved into the body's coordinate frame. This is a performance optimization. There are other performance optimizations on shape data that makes it differ from the original shape definition.
Normally games do not use shape positions for rendering. They take the body position and move the sprite, bone, etc accordingly. Games do not normally render the exact shape, the shape is just an approximation of the model. For example, games like Mario just wrap a box or capsule around the character. They don't have every pixel represented by the collision shapes. Therefore, the shape positions are not used much (except perhaps for debug drawing).
Remember that shapes are completely fixed to the body. The relative position of a shape on a body is not changing.
Normally you should not need to access shapes in your game loop. In the test bed I work with shapes because I don't have a full game engine with sprites, bones, etc.
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.
API
What are m_ variables
Class properties starting with m_ variables are meant to be internal to the Box2D engine. They are frequently not marked as private to avoid visibility issues within the engine.
Why does Box2D have so much public data
C++ is good for development, but not so great for libraries. Much of the class data is made public to ease development. In many classes you will find this comment:
//--------------- Internals Below -------------------
This means that any members below that line are subject to change, aren't documented, and aren't supported.
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 units
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.
In the Box2DFlashAS3 TestBed, the examples are already set up with a scaling factor.
Troubleshooting
See Troubleshooting
