Starling, Nape Physics, and PhysicsEditor

While there are seemingly countless tutorials, articles, and assorted commentaries on using TexturePacker with Flash (and usually Starling), it seems there are very few articles out there about TexturePacker’s creator’s (Andreas Löw) other equally fantastic tool PhysicsEditor. Since I’m currently working on a game that makes extensive use of this software, I thought I’d take a bit of time off to write a little about it.

If you don’t know what it is, in a nutshell, PhysicsEditor allows you to import .png files, trace their shapes, then export matching physics bodies for the framework of your choice (assuming your choice is AndEngine, Box2D, CitrusEngine, Corona, Chipmunk, Gideros, Lime + Corona, Nape, QuickBox2D, or RapaNui – and, really, what else is there?) in code form. I’ll give a quick run through on exporting some bodies for the Nape AS3 engine, so if you want to be able to compile the end result, you’ll need the latest Nape release, PhsyicsEditor, of course (there’s a free trial available), and Starling.

First you’ll need some images to play around with. Just for complexity, for this demo, I chose a gear and a wacky ground I just drew up at random. You’re welcome to play around with these, but for the sake of full disclosure, I found the gear in a Google image search, so I wouldn’t go using it for anything other than testing.

One of the great things about PhysicsEditor is that you can simply load in the actual textures you plan on using in your game or app so unless you wind up resizing your assets later, you’ll get a perfect WYSIWYG result.

So, fire up PE and load in your images using the ‘Add Sprites’ button on the top tool bar. Once imported, to the left you’ll see a list of the currently added images. If you used your own images and didn’t give them meaningful names (e.g. you named them ’01.png’ or some such thing), now would be a good time to  do so. Double click the name of the image and change it to something more meaningful like ‘ground’, or ‘gear’ or whatever (you’ll see why you’ll want to do so in a bit). Now on your images (one at a time), click the ‘shape tracer’ button (the little magic wand icon just above the big image in the center). This will open a new window called ‘Tracer’ and automatically trace a shape around your image. Of course you’re welcome to play around with the settings here, but I find the defaults to work just fine. More than likely the shape won’t be perfect, but we’ll fix that in just a second.

After clicking ‘OK’ in the Tracer window, you’ll be taken back to the Main window, but now see a reddish shape around your image. For a closer look, you can use the slider beneath the image window to zoom in and out. As mentioned, your traced shape probably won’t be perfect, but at this point, you can click on vertex points to move them around. And by right clicking, you can delete any unnecessary vertex points or add new ones anywhere on the path. The goal is to trace a path as perfectly as possible around your image while keeping the vertex count as low as possible. After about 30 seconds of mucking about, my gear image wound up looking like this.

My ground image took even less fixing up.

Next you’ll want to choose an exporter. From the drop down menu to the left select ‘Nape (AS3)’. You’ll see some more settings you can play around with, but the only thing I changed in this demo was the anchor point which I placed right in the center for both ground and gear. You can do this quickly and easily by changing the relative x and y coordinates to both be .5. Like the Flash display list, this is the registration point of your physics body and will affect how they’re positioned when we get to that point.

At this time, you’re ready to go. However, if you were to publish right now, you would wind up with several errors in your code. This is because the Nape Physics API has been updated since the last release PhysicsEditor (I’m sure it’s hard keeping up to date when supporting all those freaking engines). Thankfully, Andreas Löw has made it incredibly easy to keep the exporters up to date ourselves. Go to the installation directory of PhysicsEditor and find the ‘exporters’ directory. Browse into that then go down and move into the ‘nape-as3’ directory. Inside there, you’ll see a ‘nape.as’ file. Open that in a text or code editor and every place you see ‘cbType =’, change it to ‘cbTypes.add()’. So, for example:

will become:

and:

will become:

etc.

If you’re not familiar with Nape, CBTypes are short for Call Back Types. You can create your own call back types and apply them to physics bodies so that interactions will have different results. For example, a collision between two gears may play a different sound than a collision between a gear and the ground. In previous versions of Nape each body could only have a single call back type applied. Now, however, call back types are added to a list and you can have several on a single body. For this basic demo we won’t bother with any cbTypes, but, again, without making these changes to the export, your final project will be filled with errors.

NOTE: by the time you read this, this discrepancy may be fixed and none of this may be necessary. I’m currently using the 1.0.9 version of PhysicsEditor.

So, once the exporter file has been fixed (you only have to do this one time), you’re ready to publish your actionscript file. Click on the ‘Publish’ or ‘Publish As’ button on the top tool bar and save the file to your project root (or anywhere you’ll remember if you haven’t created a project yet) with the default name ‘PhysicsData.as’.

ANOTHER NOTE: if you choose a different file name or publish to a package other than the root of your project, you’ll have to edit the .as file to reflect these changes. No big deal.

Now, you’re ready to start writing some code. If you haven’t already done so, create a new Actionscript project somewhere. I set mine to export a 800×600 .swf file with a framerate of 60. I also embedded the ground and gear images (same ones I used in PhysicsEditor). Of course you could create an image Atlas (with something like TexturePacker, for example), but for only two textures, I really didn’t want to go through the trouble.

The first thing you’ll want to do is initialize Starling. In my example, I have a very basic mStarlingBase instance which inherits from the Starling Sprite class and does really nothing but act as container to which I can add some Starling images.

After Starling is good to go, we’ll initialize the Nape Physics engine. Unlike other physics engines, Nape is extremely easy to set up. Really all you need to do is create an instance of the Space class and pass it a Vec2 instance which defines gravity and you’re good to go. For this example though, I also create a PivotJoint instance which will be used to add mouse interactivity so you drag and throw the gears around. So my initPhysics method looks like this:

(1000 may seem like a high gravity, but Nape just seems to look and perform better with very high gravity set. Adjust to your own taste).

Once the physics space is ready, we can start adding physics bodies. First we’ll initialize the ground. The first thing we’ll do is create a Starling image from the embedded ground image bitmap data and add it to the Starling base. After that, we create a Nape physics body using a static method of the PhysicsData class exported from PhysicsEditor – var ground:Body = PhysicsData.createBody(“ground”); And now you can see why it was important to give your images meaningful names back in PE – writing PhysicsData.createBody(“01”) just wouldn’t be the same. Notice that this static method can also take a graphic argument. We’re not going to bother with that though. More on that in just a bit. Since our ground will never move, we set its ‘type’ property to static. We then position it in the center of the screen (recall back in PE we set the registration point to be in the center – this is where it makes a difference). Finally we add the body to the physics simulation just by setting its space property to our mSpace instance. The entire initGround() method looks like this:

Next, we’ll add some gears into the mix. Since I want to add 3, I’ll do it in a simple for loop. This is done essentially the same as we added the ground with one slight difference. Since these gears will be moving around, we’ll want to associate our gear image with the gear physics body. In many Nape tutorials, you’ll see people telling you to use the ‘graphic’ property of the body instance. That property is being deprecated though and it is now recommended that you add your graphics to the ‘userData’ property of the body; which is just a generic object that any data can be added to. Also note that when we create our gear images, we adjust the pivot point to match the centered anchor point of the gear body. So, the initGears() method looks like:

Now that our physics bodies are in place, we add some MouseEvent listeners to handle our mouse interaction and, finally, an EnterFrame listener to update our physics simulation. To update the Nape Physics engine, it’s really only necessary to call the step() method of the Space instance. In our case though, we also want to update our PivotJoint for mouse interactions, and, more importantly we want to update the images associated with the gear bodies. So our enter frame handler looks like this:

Notice that to update our graphics we loop through the live bodies in our Space instance and for each of them call a method called updateGraphics. This method expects a Body instance as an argument and looks like:

And that is really the entire gist of it. Assuming all goes well, you should wind up with something like this. As you can see, even with such complex physics shapes as gears and that crazy ground, you still get an app that runs at a framerate of 60 FPS.

But, of course, the main point was just how easy it is to create complex physics shapes using Andreas Löw’s fantastic PhysicsEditor tool.

The entire code is listed below:

The document class, Main.as:

And the PhysicsData.as class exported from PhysicsEditor: