FlashPunk, DAME and Lua Tutorial (Part 3)

01/27/2011

Since I've already covered some of the various game frameworks for Flash, decided on a project to make, and explained all of the components within the project - I think it's finally time to get into some code.  If you haven't already downloaded the project files, grab them here.

First, take a look at the XML structure we'll be using:

<level>
	<tiles layer="template4" x="1440" y="0" width="480" height="480" tileWidth="32" tileHeight="32" widthInTiles="15" heightInTiles="15" >
		<tile tx="96" ty="0" x="0" y="0"/>
	</tiles>
	<sprites layer="template4">
		<sprite className="Balloon" x="1484" y="349" width="35" height="45" points="1" />
		<sprite className="Balloon" x="1621" y="2" width="35" height="45" points="1" spawnShape="74A916C5-C96B-62BE-6540-024B6D1237CB" spawnAmount="2" color="0x00ff00" />
		<sprite className="Balloon" x="1818" y="73" width="35" height="45" points="1" />
		<sprite className="Balloon" x="1750" y="343" width="35" height="45" points="1" spawnShape="74A916C5-C96B-62BE-6540-024B6D1237CB" spawnAmount="5" />
		<sprite className="FlyingPig" x="1843" y="1" width="60" height="51" spawnShape="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" spawnAmount="5" />
		<sprite className="Balloon" x="1629" y="346" width="35" height="45" points="1" />
	</sprites>
	<shapes layer="template1">
		<shape type="rectangle" x="1663" y="286" width="191" height="159" guid="74A916C5-C96B-62BE-6540-024B6D1237CB" />
		<shape type="rectangle" x="1659" y="64" width="257" height="160" guid="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" />
	</shapes>
</level>

It looks a bit complicated, but it's really not at all.  First of all, notice that I've only included a single line for each tag.  In reality, the entire file is over 1000 lines long (don't worry, Lua does all of that for us!).   On line 1 you can see that the root node for the entire XML file is called level.  This could be called anything, usually it's just <xml> but in this case I went with something that made sense to me.

The main tags

Within that root level tag, there are only 3 other main tags:

<tiles>

<tiles layer="template4" x="1440" y="0" width="480" height="480" tileWidth="32" tileHeight="32" widthInTiles="15" heightInTiles="15" >

This contains all of the tilemap information for the level.  Each time within DAME that you click on the canvas and paint a tile (or use the tile matrix tool), it will be exported into the xml file within this tag.  More on that in a second.  Note the attributes within this tag:

• layer - this is name of the layer within DAME.  For this part of the tutorial, we will just focus on "template4" because it has tiles, sprites and shapes that we will be using to spawn entities (as they are called in FlashPunk).
• x / y - This is the x/y offset within DAME.  We won't be using this number to place the tiles, but actually the sprites.  That may be a little confusing, but it's simply because DAME editor does not let you set the same properties on a sprite or shape layer, as you can on a tilemap layer.
• width / height - The dimensions of the map in pixels.  Although this could be calculated in AS3, this is handy to have as an attribute for reading through the XML code.  It also saves us the effort of figuring it out in code.
• tileWidth / tileHeight - More obvious sounding variables (in an ongoing effort to write self-commenting code) imply that these are simply the size in pixels of the tiles used.
• widthInTiles / heightInTiles - Again, this may seem redundant since we could calculate this in code from the information already provided.  It could be helpful to have for a few reasons though, so I've included it.

<sprites>

<sprites layer="template4">

Not surprisingly, this tag contains all of the sprites within the level.  As mentioned above, the <tiles> tag actually has all of the offset information needed to position the sprites.  The <sprites> tag only has one attribute actually: layer, which is set to "template4."

<shapes>

<shapes layer="template4">

Just like the <sprites> tag, shapes gets it's offset information from the <tiles> tag with the same layer name, "template4."

The Child Tags

We're almost done covering the xml format!  Within each of the main parent tags, there are child tags.  For <tiles> there is <tile>, for <sprites> there is <sprite> and for <shapes> there is <shape>.  Let's go over each one, since this is where all the important stuff is:

<tile>

<tile tx="96" ty="0" x="0" y="0"/>

One of these tags is created each time you paint a tile within DAME.  There are only 4 attributes, which are all very straight forward:

• tx / ty - This refers to the position of the tile image used within the tileset, in pixels.  In the example above, tx is 96 (pixels), which means it's 3 tiles over (the red bricks).  Since it may be hard to explain with text alone, here is an image to give you an better idea:
  
• x / y - These are the actual coordinates of each tile, relative to the tilemap.  In the provided example, x and y are both 0, meaning that this tile will be placed in the top left corner of the tilemap.

<sprite>

<sprite className="FlyingPig" x="1843" y="1" width="60" height="51" spawnShape="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" spawnAmount="5" />

For the sprite example, let's look at this flying pig.  Out of all the different elements within the XML file, the <tiles> (plural) and <sprite> (non-plural) tags will usually have the most attributes (at least the way I've coded it).

• className - This is set within each sprite's properties inside of DAME, in the class field.  In flash we will be using this to reference classes of the same name.  In this example, it's "FlyingPig" which will correspond with FlyingPig.as in a later part to this series.
• x / y - The position of the sprite, however notice that this is not relative to the tilemap.  DAME treats all sprites as if they were positioned absolutely (forgive me using CSS terminology) instead of relatively.  This is why we will use the x attribute within the corresponding <tiles> tag, to figure out where to place the sprite within the tilemap.
• width / height - DAME allows you to resize (and even rotate) sprites within the editor.  We won't be doing that in this tutorial, however it's very helpful to know how big the sprites are before loading them into memory.  By setting these attributes, we will know exactly how big to make hitboxes, masks and etc.
• spawnShape / spawnAmount - Unlike the rest of the attributes listed so far, which are generated by default in DAME, spawnShape and spawnAmount were custom properties, created within the editor.  spawnShape refers to the GUID of a shape object within DAME (explained below in just a moment).  The spawnShape will be used to randomly place the sprite somewhere within the bounds of that shape.  The spawnAmount attribute will tell Flash how many of these sprites (in this case, Flying Pigs) to spawn within the spawn area.

<shape>

<shape type="rectangle" x="1659" y="64" width="257" height="160" guid="5E3E76E3-431E-E1E1-B26C-930B32DB8AB1" />

Finally, this is the last element to look at.  While a circle is used for example in this project, there is no code to support using circles as spawnShapes.  So let's take a look at a rectangle, which is being used as a spawnShape.

• x / y - Just like our <sprite> tag, this is an absolute position of the shape, which will use the <tiles> position to offset within the code.
• width / height - Every rectangle needs the bare minimum of requirements, and this one is no exception.
• guid - This is a value that DAME automatically calculates for all objects created within the editor.  In our example, I've decided to export the guid value for just shapes, but could have exported the guid for all elements if needed.  Notice the guid of this shape, is the guid being referenced in the spawnShape attribute from the <sprite> tag above.

For a visual example of whats going on here, let's look at this template within DAME:

The FlyingPig <sprite> in this example, is the one you see in the top right of the template.  The <shape> being used as a spawnShape for the Flying Pig, is the rectangle right below him (or her).  You can also see by the marquee, that the FlyingPig sprite is selected within the DAME editor, and there are two custom properties (on the bottom left).  This is where spawnShape and spawnAmount are defined.

Conclusion of Part 3

Phew, I wasn't sure how much detail I wanted to go into with this XML file, but turns out, I wanted quite a bit.  You should now understand how to create a level within DAME editor, and what that information will look like when it comes out of DAME.  The next step of this tutorial will be to explain exactly how all of this information is converted, using Lua (which is not an acronym).

Continue to Part 4