Box2D

The Box2D physics engine is available for several languages including Free Pascal and we have written a tutorial section to help you to get started with using Box2D in Lazarus. The official documentation is for Erin Catto's C++ original and this C++ tutorial is most useful. (See our tutorial C/C++ after Pascal for help with the syntax). Note that in the Smart Pascal version of Box2D, the Y axis increases as usual down the screen.

Box2D Terminology

This is an alphabetical list of terms used in the Box2D documentation with our notes (not rigorous definitions) and links. Sentences or phrases in quotes are copied directly from the documentation.

AABB

axis aligned boundary box (used for quick collision detection)

body

An object of type Tb2Body that may be static, dynamic or kinematic. A body takes fixtures (of type Tb2Fixture) defined by fixture definitions (of type Tb2BodyDef). The fixture definition has a public field BodyType that has the value btStaticBody, btKinematicBody or btDynamicBody.

CCW

counter clockwise

centre of mass

The point at which the whole mass of the body may be considered to act e.g. the centre of a circle or rectangle.

constraint

A limitation on the degrees of freedom (usually achieved by one or more joints). An unrestricted 2D body can translate in two dimensions and rotate.

degree of freedom

For a 2D body this is translation in the X or Y direction or rotation.

density

In a 2D world this is the mass of unit area. "The fixture density is used to compute the mass properties of the parent body." A value of 1 for the density seems to give good results.

distance joint

Joint that keeps the anchor points on two bodies a fixed distance apart, as if linked by an invisible rod. See an example.

engine

Software with a functionality designed to be used by many programs. In this case the Box2D physics engine provides to game programs the positions and orientations of interacting bodies.

fixture

Attaches a shape to a body. A fixture definition provides the fixture with attributes.

fixture definition

Provides its fixture with attributes such as shape, density, restitution, friction and image data.

FreeGLUT

An alternative to the OpenGL Utility Toolkit (GLUT) library. It has additional features and Version 3.0.0 was released on 7th March 2015.

friction

Used to resist the movement between two surfaces. Usually given a value between 0 and 1, via the fixture definition. The value used in calculations is the geometric mean of the individual values for each surface.

GLUI

GLUT-based C++ user interface library. Provides widgets such as buttons and edit boxes to OpenGL applications.

joint

"Joints are used to constrain bodies to the world or to each other." The joint types are jtUnknownJoint, jtRevoluteJoint, jtPrismaticJoint, jtDistanceJoint, jtPulleyJoint, jtMouseJoint, jtGearJoint, jtWeldJoint, jtFrictionJoint and jtRopeJoint.

kinematic

A kinematic body is useful for moving platforms because it can rotate and translate but is unaffected by gravity or by collisions.

malloc

C and C++ routine for allocation of memory blocks. (Box2D has its own fast memory allocation).

manifold

A structure used internally by Box2D to hold the common normal vector and up to two contact points between two touching surfaces.

MKS

metre kilogram second. Use MKS units for your Box2D code then multiply by a scale factor to convert to pixels for rendering.

motor

Used to translate or rotate a body.

prismatic joint

Enables linear sliding between two bodies. The name is confusing unless you think of how this has been engineered while preventing rotation as described on this Wikipedia page. See our piston.

radian

The unit of rotation used by Box2D. One revolution (360 degrees) is 2*Pi radians.

ray cast

Provides the point of first intersection and normal vector of shape(s) hit by the ray and the fraction along the ray for each intersection, so you can determine the closest shape. Used e.g. for line-of-sight tests.

rendering

drawing

restitution

The coefficient of restitution is the ratio of speed of separation to speed of approach in a collision. It takes a value between 0 for an inelastic collision and 1 for a completely elastic collision. In Box2D we supply a value for restitution to a body via its fixture definition. For each collision Box2D uses the greater of the two restitution values of the colliding bodies.

revolute joint

Used for rotation. See for example a motorised axle and the use of many hinges in a rag-doll.

shape

The types of shape are stCircleShape, stEdgeShape, stPolygonShape and stChainShape.

SOA

Small object allocator, used internally by Box2D for fast memory allocation.

step

The time step for most calculations, for which a value of 1/60 is recommended.

TOI

time of impact, used by Box2D to prevent tunnelling of one shape through another during a time step.

tolerance

A margin of error that can be tolerated when comparing floating point numbers.

tree

Used for storage of objects by position enabling rapid access to a subset for, say, collision detection. See our Pascal tutorial on sorting and searching for straightforward examples of the use of trees.

tunnelling

The passing of one body through another during a time step. Calculations of time of impact and sub-steps are designed to prevent tunnelling.

world

You create a world (of type Tb2World) before creating bodies and joints with it.

Follow the links below to our examples, which show how you can use the usual Smart Pascal graphics routines to render the objects at positions and orientations that have been computed by the engine. We demonstrate the use of several types of joint, and trust that you will be able to apply your knowledge to the other types.