Automating entity generation with PHP and ImpactJS

While working on the JIPPI game we needed tools for easing the development. One of the tools was a PHP script for automating generation of entities.

We would get the sprite sheets from Making Waves, and then it was our job to make the entities come alive. To make this process as flexible as possible, we needed a workflow that would allow the client to update the sprite sheets whenever needed. We could therefore not add any functionality to the generated entities. Otherwise, they would be overwritten during the next update. Instead, we turned the hierarchy upside-down. Generated entities would extended a parent entity that gave them a particular set of behaviours.

The PHP script got instructions for how to generate entities by reading the file names of the sprite sheets. Let's consider the following file name:

Tells the script to save the entity in game/entities/thomas. Create the folder if it doesn't exist.
Name the file player.js.
Load the entity definition template called character.
Split the sprite sheet in 2 columns and 4 rows.
Define a set of animations, where the first animation is called 'idle' and uses the first index of the sprite sheet. Next add an animation called 'jump', consisting of sprite index 1, 2 and 3. Wait animation uses index 4 and 5, and lastly add two animations with one frame each, called sit and crouch.

The script was split up into several files where the most important ones were the template files. They had each a parser with a set of rules specific for that template, and a function that would merge the data from the file with a template file. Some templates could generate multiple entities per file. The other files would do things like calculating the size and offset of each tile in a sprite sheet.

The PHP script followed the following routine:

  1. Scan media folder for valid image files.
  2. Run the file name with the parser for each entity template to see if the file is supposed to be made into an entity. One can make the script ignore files by naming the file something that doesn't match any of the patterns in the parsers.
  3. When a template has been found, test it agains the class that splits the image into the desired number of rows and cols. If the image has the wrong size, abort the script.
  4. Calculate each tile's size and offset by looping over each transparent pixel from top > bottom, right > left, bottom > top and left > right until we either reach the other side of the image (all the pixels are transparent) or a pixel with a transparency level above a defined threshold.
  5. If any animation has been specified in the file name, set up all the animations.
  6. Merge all of this data with a template.
  7. Write the file to the correct folder, overwriting any old entity.

With this routine, we generated about 50 entities in only a couple of seconds. If we were to manually create and maintain these entities we would spend hours each update, and it would be prone to errors.

Latest articles