Understanding Box2D debug draw

When you are about to create a complex script with Box2D – or even a simple one, but that’s complex for your skills – I suggest to enable debug draw.

Debug draw will provide you everything you need in order to verify your script is working correctly, and once you are satisfied with the result, you can start attaching movieclips to skin the shapes.

So I am going to explain everything you need to know about debug draw, and probably something more.

The following movieclip is the HelloWorld.fla file you can find in the distribution package, with all movieclips removed and the debug draw enabled:

Let’ see how did I modify the script in order to enable debug draw… interesting lines range from line 21 to line 35

So now we are going to look at lines 22-34

Line 22: Declaring a new sprite called m_sprite

Line 23: Creating the sprite itself

Line 24: Adding the sprite to stage

Line 25: Declaring a new b2DebugDraw variable called dbgDraw

Line 26: Declaring and creating a new sprite called dbgSprite. This line acts like lines 22 and 23

Line 27: Adding this sprite to stage as a child of m_sprite

Line 28: Setting m_sprite as the sprite to use to render the world

You should not change anything until line 28

Now, it’s time to look at the ways to custom the debug draw. We will custom it by changing its attributes.

m_sprite as said, defines the sprite to be used for rendering

m_drawScale (line 29) sets the drawing scale of the rendering. As seen in Understanding pixels and meters with Box2D and how to select an object with mouse – part 2, one meter is equal to 30 pixels, so setting m_drawscale to 30 allows me to use pixel units.

This is how my movie looks like if I don’t set m_drawscale:

m_alpha (line 30) sets the alpha (from 0 to 1) for objects drawing color

m_fillAlpha (line 31) sets the alpha (from 0 to 1) for objects filling color

m_lineThickness (line 32) sets the thickness in pixels for objects drawing line

m_drawFlags (line 33) allows you to set some drawing flags. Before I explain every flag, let’s see how our movieclip will look like if I don’t set m_drawFlags

and now let’s see the flags you can assign, separed by a pipe |:

e_shapeBit: draws shapes
e_jointBit: draws joint connections
e_coreShapeBit: draws core (TOI) shapes
e_aabbBit: draws axis aligned bounding boxes
e_obbBit: draws oriented bounding boxes
e_pairBit: draws broad-phase pairs
e_centerOfMassBit: draws center of mass frame

The only thing you cannot change from here is the color of the objects: by default, Box2D assigns a green to static objects, a red to sleeping ones and a grey for moving ones.

You can change the colors editing b2World.as at lines 1060-1074 (line numbers may vary according to Box2D distribution)

You just have to change values inside b2Color with values from 0 to 1 where 1 is the 255 value we are used to deal with when working with colors.

We are almost ready to make our first Box2D game…

  • Great explanation, thanks! :D
    viva italia :p

  • anlik

    Great man, I like your all flash game tutorial, especially Box2D!!! Thanks your work!!!

  • Pingback: Box2D: tutorial for the absolute beginners - step 2 : Emanuele Feronato()

  • laura

    Hi. Very interesting to know

  • laura

    Can you tell me where to change the color of joints?
    I could not find that

  • Cem

    However code fails at line 95
    1046: Type was not found or was not a compile-time constant: b2Body.

  • Pingback: Physics Engine für Flash: Box2D | Multitouch and Beyond()

  • vahidb

    debugDraw Class is not useful in c++. We must Draw anything by ourself.

    Are these words right?

    Is DebugDraw is Pure Virtual?

  • vahidb

    debugDraw Class is not useful in c++. We must Draw anything by ourself.

    Are these words right?

    Is DebugDraw ,Pure Virtual?

  • COOOOOOOOOOOOOOOOOOOOOOOLLLLLLL

  • Pingback: Customize Box2D debug draw and make it run even on Starling mobile apps - Emanuele Feronato()

  • Mr. Feronato, thank you for your big work! I’m using box2d 2.1a and when i assigned AABB’s flag in my debug draw, i’ve seen that all AABBs of movin’ bodies are incorrect (not like in your example). It seems like they constructing from several frames. Maybe you know where the problem?