What the b2World can teach you about C++ (and ActionScript, too)

I’m going to let you in on a secret. The Scriptocalypse banner at the time of this writing uses the Box2DFlashAS3 physics engine, a port of Erin Catto’s Box2D, written in C++. This is not the first time The Horseman has used Box2DFlashAS3. In fact, it’s one of those things that he learned to work with in the midst of a professional project “under the gun” as it were.

If you’ve never worked with a physics engine before, Box2D looks intimidating. To make matters ‘worse’ for an ActionScripter, the Box2DFlashAS3 port of the library breaks almost every standard ActionScript code convention. This made the task of parsing the library for comprehension a bit more difficult than other AS3 libraries I’ve encountered, though obviously it’s doable. Without knowing anything about the pedigree of the library, at first I wondered why the author chose to do this. I clued in fairly quickly after skimming the source code and finding references to “native” datatypes that Flash just doesn’t support (int32, anyone?) that had been commented out and re-written a line below with datatypes Flash recognizes. Box2DFlashAS3, as a port, is very much a “transliteration” of the library from its native code as opposed to a smooth “localization.” It would be like translating literally:

“Ik kom uit Amerika” -> “I come out America”

Instead of translating the general meaning…

“Ik kom uit Amerkia” -> “I’m from America”

Everything from the naming conventions, to the placement of the variables, to the slavish insistence on strictly defining the length of Arrays on instantiation, to the way you create instances of b2Body and b2Joint, to the ubiquity of the LinkedList structures used for iteration looked like it came straight from a different paradigm. The linked lists alone are peculiar in ActionScript. Virtually every physics body, shape definition, and joint is capable of containing a reference to a “next” and “previous” object of the same datatype, and almost nowhere are you as the user given an Array to sift via the API.

“Why would I want or need to explicitly declare Array lengths on instantiation? Why would I need to specifically create bodies and joints by calling the b2World rather than just instantiating them like I would do for a MovieClip object? Let’s read the user’s manual…”

From the manual:

C++ is great for encapsulation and polymorphism, but it’s not so great for API design. There are always significant trade-offs when creating a C++ library.

Should we use abstract factories or the pimpl idiom? These make the API look cleaner, but they ultimately get in the way of debugging and efficient development.

Should we use private data and friends as necessary? Perhaps, but eventually the number of friends can become ridiculous.

Should we just wrap the C++ code with a C-API? Perhaps, but this is extra work and may lead to internal choices that are non-optimal. Also, C-APIs are harder to debug and maintain. A C-API also breaks encapsulation.

For Box2D I have chosen the path of least resistance. For some cases a class is well contained in its design and function, so I use public functions and private data. For everything else I use classes or structs with all public members. These choices let me develop the code rapidly, it is easy to debug, and it creates minimal internal clutter while maintaining tight encapsulation. The downside is that you don’t see a clean, simple API. Of course, you have this nice manual to help you out. 🙂

Remember, the above excerpt is from the ActionScript-specific port of the manual!

Here’s some more:

Joint Factory

Joints are created and destroyed using the world factory methods. This brings up an old issue:


Don’t try to create a body or joint on the stack or on the heap using new or malloc. You must create and destroy bodies and joints using the create and destroy methods of the b2World class.

Heap? Malloc? In ActionScript?

Box2D doesn’t use reference counting. So if you destroy a body it is really gone. Accessing a pointer to a destroyed body has undefined behavior. In other words, your program will likely crash and burn. To help fix these problems, the debug build memory manager fills destroyed entities with FDFDFDFD. This can help find problems more easily in some cases.

If you destroy a Box2D entity, it is up to you to make sure you remove all references to the destroyed object. This is easy if you only have a single reference to the entity. If you have multiple references, you might consider implementing a handle class to wrap the raw pointer.

Often when using Box2D you will create and destroy many bodies, shapes, and joints. Managing these entities is somewhat automated by Box2D. If you destroy a body then all associated shapes and joints are automatically destroyed. This is called implicit destruction.

When you destroy a body, all its attached shapes, joints, and contacts are destroyed. This is called implicit destruction. Any body connected to one of those joints and/or contacts is woken. This process is usually convenient. However, you must be aware of one crucial issue:


When a body is destroyed, all shapes and joints attached to the body are automatically destroyed. You must nullify any pointers you have to those shapes and joints. Otherwise, your program will die horribly if you try to access or destroy those shapes or joints later.

Ahah! Any seasoned ActionScript developer should know and understand the concept of reference counting, as it’s a long-standing garbage collection technique used in the Flash Player (though the player now uses mark-and-sweep). But even though this documentation is clearly still “in another language” so to speak, things are definitely coming together here.

As pretty much anyone who’s done more than scratch the surface of Box2DFlashAS3 can tell you, trying to perform an action on a body or a joint that has either been destroyed or has “fallen out of the world” by leaving the confines of the AABB is asking for trouble. That manual is not kidding when it tells you to “nullify your pointers” when you destroy the object (or in ActionScript parlance, set your variable containing the b2Body/b2Joint = null) , and the more places in which you’re storing references to those bodies the more diligent you must be about cleaning up after yourself. The most disastrous behavior I found was calling b2World.DestroyBody() / DestroyJoint() on a body or joint that had already been destroyed. Completely threw off the internal count and broke all kinds of madness loose.

The paranoia about how you create and destroy the bodies and joints, and about Array length pre-definition is directly related to the fact that in straight C++ you are responsible for your own memory management and garbage collection. The implications of this are somewhat alien to the ActionScripter who has never worked with code in an unmanaged environment before, but become blindingly obvious when you have to handle it yourself.

Suddenly, the length to which you define your Array really, really matters! We’re a bit spoiled here in Flash-land with our dynamic-length Arrays. Those are more traditionally thought of as “Lists,” as they can grow or shrink in size on-the-fly at runtime. The worst that happens in ActionScript when you try to access an Array location that stores no data is that flash returns a literal datatype of “undefined”. In C++, may the Four Horsemen of the Scriptocalypse have mercy on your soul for daring to step off the end of an Array. This is why Box2D is so heavily reliant on Linked List structures when returning collections of bodies and joints. At least when you walk off the end of one of those, it can tell you explicitly what you’ve done rather than executing undefined behavior (which is a far different animal than returning a literal datatype defined as “undefined”).

So, what’s the point of all this rambling? I think what I found enlightening about my experience working with Box2DFlashAS3 was that it really gives you an appreciation for the care with which you must treat your resources. In our little world of managed code, we get away with a lot of things every time we compile a swf that just wouldn’t fly in C or C++. As a consequence, we can “afford” to be a little sloppy with our resources… but can we really afford it? Shouldn’t we always take care to implement a scheme for thorough destruction of all object references when they’re no longer needed? Isn’t it true that the more different places in which an object is stored, the harder this becomes?

Before snagging and holding onto a reference to an object whose life and death are somehow integral to the program, even in the highly managed world of ActionScript, maybe it’s a good idea to stop and ask yourself “Do I really need to store a reference to this object here? How much extra work will I create for myself when I have to destroy it? What harm will come when I fail to destroy it?

Tags: , , ,

  1. No comments yet.