Help

For now, the main documentation will be kept on the Box2D wiki.

Please feel free to discuss your ideas and/or problems in the forums, also.

Manual

The original Box2D manual has been ported to Python and mostly updated for the latest version. You can find it here.

Basic API documentation is available thanks to epydoc, here. It's hardly user-friendly, so unless you know what you're looking for, chances are the testbed examples are still your best bet.

Version Numbers

The version numbers follow the main Box2D releases (currently 2.0.1) with a release number attached. For example, 2.0.1b3 is based on Box2D release 2.0.1 and is the third release of the bindings.

Starting Box2D 2.0.2b1, the version number of the source code is available in Box2D:

import Box2D
Box2D.__version__      # '2.0.2b1'
Box2D.__version_info__ # (2,0,2,1)

Changes

2.0.2b1 (2/25/2009)

Since 2.0.2b0, there have been a good deal of changes to pybox2d:

• Code structure completely reorganized
• Doxygen comments converted to docstrings (should be a bit more friendly now, but still a bit C++'ish in places)
• Lists and tuples may be used anywhere in place of b2Vec2's, and all of the tests have been updated to reflect this
• Save/load state (pickling support for worlds)
• Bug fix: Seg faults during DebugDraw/etc callbacks
• Bug fix: userData reference counting causing leaks
• Bug fix: getType() didn't work on line joints
• Bug fix: TestSegment now returns from (-1,0,1) and not a bool
• b2PolygonDef.setVertices() added, supports either b2Vec2 or list/tuple, so no need to specify. Old setVertices_tuple/b2Vec2() are deprecated.
• New pretty printing style. It takes up a good deal of space, but it's actually readable.
• New examples: bezier edges with thin line segments, a simple belt, basic pickling example (might needs some updating)
• (Optionally compilable) C++ assertion failures turned into Python exceptions
  Additional properties and accessors to make coding easier (see below)
• Many tests were updated and rewritten to be cleaner
• Added b2CheckPolygonDef and deprecated the Python ported version. This version adds (optional) additional checks to ensure that your shape is convex and properly sized to not have strange results
• Added GetVertices() for b2EdgeShapes. Creating one b2ChainDef results in many b2EdgeShapes, so this properly loops through each connected shape and gets the vertices in order
• Box2D source updated, b2GravityController fixed
• A fix for not allowing b2Body/Joint/Controller/Shapes as dictionary keys. Don't know how I missed this one. Still won't be picklable unfortunately.
• Basic iterators have been added: b2World (iterates over bodies), b2Body (iterates over shapes), b2Controller (iterates over bodies), b2PolygonShape (iterates over vertices)

There are several code-breaking features that you might run into:

• The library is now called Box2D (and not the cumbersome Box2D2)
• Controllers now follow the factory style (see the buoyancy test for more information)
• b2Distance updated (see here if this affects you)
• b2Body.GetShapeList() used to return only first shape, now returns actual list
• b2World.GetBodyList/Joint() used to return only first body, now returns actual list
• All occurences of the ugly 'm_*' have been removed. This might require some changes in your code, since this applies to all b2Joint.m_* and others, not just testbed stuff.

The following are the additional properties added. Most are just for convenience and make the definition (e.g., b2ShapeDef) symmetric with the output (e.g., b2Shape). Ones in bold are changeable; the rest are read-only:

(later SVN versions add support for changing damping, fixedRotation, and shape isSensor)

Basic epydoc documentation is now available here. The testbed is no longer included in the installer, so please download it separately here.

2.0.2b0 (10/23/2008)

First release that's not based on a major Box2D release. It combines Box2D SVN r177 and contributions from shaktool (thin line segment) and BorisTheBrave (controllers/buoyancy).

• Thin line segment support (forum post)
• Buoyancy with generic controller support (forum post)
• Pyglet 1.1 testbed (still has some issues. run convert-from-pygame.py to convert the tests from pygame)
• OS X Installer
• Python 2.6 support
• Line joints (see LineJoint test)
• Raycasts (see RayCast test and BoxCutter test)
• TestSegment support
• BreakableBody test (forum post)
• Fixed: == was working, but != comparisons weren't.
• Access to polygon normals, core vertices, etc.
• cvar list fixed
• Off by one bug fixed for vertices

New time step will require a few minor updates to your code:

Old:

world.Step(timeStep, iterationCount)

New:

world.Step(timeStep, velocityIterations, positionIterations)

velocityIterations is usually 10, and positionIterations is usually 8.

2.0.1b4 (6/1/2008)

• Supports comparing shapes, joints, bodies. Doesn't require using userData anymore.
• Major clean ups with Box2D.i
• Added some docstrings to Box2D.i functions
• Added b2PolygonDef.checkValues(): checks the Polygon definition to see if upon creation it will cause an assertion to fail (raises ValueError)
• Wrapped shape.GetCoreVertices() like GetVertices() (for test TimeOfImpact)
• test_Web fixed
• All stuff prettily printed by a semi-automated process now
• Updated test_Bridge.py to SVN rev 156
• Added many comments to test_main

2.0.1b3 (5/7/2008)

• Updated the interface to allow SetUserData() (absolutely necessary for setting the ground's userdata)
• Fixed b2PolygonShape (.vertexCount is now private, so the accessor is used instead)
• Release for Python 2.4
• Linux (possibly OS X) support with setup.py