Pro Tip:Talking to Jim McGinley for 30 minutes or so when you are exhausted to the point of passing out will generally restore your energy for the remainder of the day. Or at least long enough for the caffeine to take over

As always, I had an awesome time, even if I was more tired this year than previous years. That largely due to the fact that I was up until 3 am the night before the Jam trying to get SVN set up on my machine so that Alex and I could forego the USB time sync. Irrational Escalation at its finest.

Alex covered the event really well with some video blogs. Find them here.

There were some fantastic games out there, I sunk quite a bit of time into Michael Todd’s dogfighting game. Shawn McGrath’s game would probably conquer XBox Live Arcade if it were to appear there. Some screenshots and description of our game after the cut

Our game this year was “Reentry” a game about misplaced guidance systems and creepy starship pilots. This year had a lot of ups and down for us.

Good: Sound and music

This year’s game used more sound assets than all 4 of the previous games I’ve worked on put together.

Alex worked with a friend of his to record voice tracks for the main characters who I have dubbed Captain Helium and Lt. Commander Creeper McShady. The voices
add a lot to the experience. The game feels a little dull without them, but that’s in line with our plan. The characters are a big part of the design.

We also got a great music track from chiptune artist OxygenStar and editted it into 3 loops connected by transitions. It turned out great.

For sound effects, we used SFXR, which belongs in every indie developer’s toolbox. Thanks to Steven Hill for throwing that one our way. All of the sound effects in the game were generated by Alex using this tool. I’m excited to try out the music creation tool Musagi by the same developer

Bad: Source Control

If you ever think about trying to set up SVN the night before a 72-hour game development event, and further think about starting at 11 pm, with no prior experience doing so, do yourself a favour and don’t.

Our hackjob solution made me worry quite a bit but ended up working out. We set up the Flex project on Alex’s computer in a network share folder and both pointed our environments at that location directly. There were some hiccups where one of us would temporarily break the build for the other, but I don’t think we lost more than 30 mins over the course of the Jam. That’s much better than what we wasted with our USB juggling last year.

Next year I’ll try to get SVN set up again, but this time a month in advance at least.

Good: Scope Control

We wanted to aim for a smaller game idea this year. We have trended towards big ideas before, and felt that it didn’t leave us enough time to refine the gameplay for the actual fun factor. I think we pulled it off this time, despite ignoring a game breaking bug right until the end of the event.

Balancing ship movement to be challenging without killing you was very time consuming You have to click the appropriate thruster and hold the mouse down (not necessarily over the thruster) to keep it firing. There are two thrusters that push your ship side to side, and two more that control your rotation. Figuring out the right amount of force for each engine to apply, as well as turbulence and impacts took up a pretty significant chunk of my time at the event.

Next time I’m adding some mechanism to adjust these values in the game itself, to make tweaking less time consuming

Bad: Miscommunication

This mostly happened prior to the event, but apparently everyone had a different picture in their head of what the game would actually look and play like up until the week of the event.

It wasn’t until we actually started sketching out the game that everything became clear. Lesson learned. The storyboard comes before everything else. It’s much harder to have a misunderstanding based on visual information than written or spoken information.

Things To Change Next Year

Based on my experience this year, there are several things I want to keep in mind when TOJam 6 rolls around. Some good practices from previous years were not observed, and they proved their value in their absence.

1. Use an engine. Not using Flixel this time made sense, but the decision should have come earlier, and a more appropriate technology selected. The best games every year leverage existing technologies. Motor physics really gave us a leg up last year.
2. Simple gameplay. We went simpler this year, in terms of number of mechanics, but we didn’t actually choose a simpler mechanic for the core of the game.
3. Revive last year’s formal approach. Alex and I both work better against a well defined schedule. Not having one this year wasn’t a good change
4. Prove it’s fun ahead of time. We took a risk on this one with a small idea and really only one major mechanic that we hadn’t seen much of elsewhere. I liked doing this, but there should have been some pre-Jam prototyping just to be sure that the idea was actually a good one.
5. Consider abstract graphics. Every year so far I’ve worked with representative graphics, and it can be limiting in some ways even if it brings a lot of benefits along with it. Besides, if Miguel Sternberg can make a game without developers, we need to show him we can make a game without artists!

I’ve been really busy lately, had to take a break from my Roguelike development to get life back in order. Posts should start appearing more regularly now, although I am still holding off on the Roguelike until I have more time to dedicate to it. My first foray into Test Driven Development in a personal project has taught me quite a bit about how unit tests should be written, and what types of things one shouldn’t try to unit test. Some test refactoring should allow me to make easier progress. I’ll make a follow up post to discsuss what I learned

Dwarf Fortress has now been updated to version 0.31, bringing an overhaul to the combat system and materials handling. There is much delectable modding goodness to be found there. Most my efforts in the short term will be devoted to working Dwarf Fortress modding tools and getting RantingRodent’s Graphical Overhaul updated with the new creatures and professions.

Summary

1. Centralize error message construction to ensure consistency
2. Catch generic errors and throw specific errors in their place
3. Include as much information as possible about the error in the message itself
4. Exceptions are a tool to help solve problems, they are not problems themselves
5. Always throw an exception the moment the application state becomes invalid, rather than waiting for it to become a problem

Error Messages

It’s often difficult to maintain a set of clear and consistent error messages. Flash developers are intimately familiar with the frustration of poor wording or vagueness. It’s difficult to prevent this from happening once the code base exceeds a certain size. A Factory can be employed to centralize the composition of error messages and make it easier to maintain them. Compare these two implementations:

public function getCell(in_x:int, in_y:int):MapCell
{
	if(!_isInitialized)
	{
		throw(new MapError("Map not initialized prior to referencing a cell", MapError.NOT_INITIALIZED));
	}
	if(outOfBounds(in_x, in_y))
	{
		throw(new MapError("Requested cell at ("+in_x+","+in_y+") is out of map bounds", MapError.OUT_OF_RANGE));
	}
	return MapCell(_map.cells.get(in_x, in_y));
}

public function getCell(in_x:int, in_y:int):MapCell
{
	if(!_isInitialized)
	{
		throw(MapErrorFactory.fromNotInitialized());
	}
	if(outOfBounds(in_x, in_y))
	{
		throw(MapErrorFactory.fromOutOfBounds(in_x, in_y));
	}
	return MapCell(_map.cells.get(in_x, in_y));
}

The code becomes much more readable, and the errors have consistent information every time they are thrown. It is also apparent whether a new error message should be created or an existing message reused, based on the exception name and the parameters provided to it. Here are the MapErrorFactory and MapError classes that accompany this example.

package com.andrewtraviss.illfate.errors
{
	public class MapErrorFactory
	{
		public static function fromNotInitialized():MapError
		{
			return new MapError("Mapper has not been initialized", MapError.NOT_INITIALIZED);
		}
		public static function fromOutOfBounds(in_x:int, in_y:int):MapError
		{
			return new MapError("Requested cell at ("+in_x+","+in_y+") is out of map bounds", MapError.OUT_OF_RANGE)
		}
	}
}
 
package com.andrewtraviss.illfate.errors
{
	public class MapError extends Error
	{
		public function MapError(in_message:String, id:int=0)
		{
			super("MapError #"+String(id)+": "+in_message, id);
		}
		public static const NOT_INITIALIZED:int = 100;
		public static const OUT_OF_RANGE:int = 101;
	}
}

Note that the x and y coordinates of the cell requested are included in the error message, rather than the message simply being “Requested cell was out of bounds”. Providing specific information about the failure makes diagnosis much easier. Implementing a distinct error message for every potential failure scenario involving the same data puts a lot of responsibility on the originating code to understand and explain the nature of each failure. It’s better to just provide the information to the developer to identify the problem. A class also cannot always judge what the meaning of a failure is just based on its own data.

Generic Exceptions

The Flash Player generates quite a number of exception on its own. The vast majority of these exceptions are useless for figuring out anything more than the fact that your application is broken. This is also true of generic messages that developers include in data structures, messaging, and other workhorse classes. If the specific impact of a generic exception can be understood by the calling method or class, the exception should be caught, and a new error thrown that describes the specific natuer of the failure, rather than allowing the generic error to be displayed.

private function fooBar():void
{
	// throws a null object reference error
	foo.bar();
}

private function fooBar():void
{
	if(!foo)
	{
		throw(FooErrorFactory.fromFooNotSet());
	}
	foo.bar();
}

When to Let Everything Crash Down

Do yourself a favour, if an exception unexpectedly takes down your whole application, let it happen. It’s far better to track down the root cause and prevent the exception from occurring in the first place. It’s very tempting to just steamroller over an exception that doesn’t seem to cause any problems just to get the product out the door, but it a dangerous call to make. I have seen the following more times than I care to count.

private function fooBar():void
{
	foo = getFoo();
	if(foo != null)
	{
		updateCriticalApplicationConfiguration(foo);
	}
}

Exceptions are only a symptom. Don’t treat the symptom, treat the illness! If you’re lucky, several function calls later, some other function is going to throw a null object reference error because this variable was not set properly. If you’re unlucky, there will be “unexpected behaviour” in a loosely related scenario somewhere far down the line. If at all possible, ensure that an exception is thrown immediately when the application becomes invalid; it saves you time versus having to track down the real point of failure from wherever it triggered an even worse failure.

This is most often a problem in the more generic parts of an application. Generic code cannot make a judgement about specific failures and whether or not they are safe. Obviously, there is the occasional case where an exception really is safe to ignore, but generic code should rarely be making that call.

1. Combat system
2. Basic status effects
3. Basic room archetypes
4. Room “theme” separate from the room’s design

Room Archetypes

I want to have some representation of some basic rooms that I can apply some randomization to. Here is the starting list of archetypes and the inspirations I am pulling them from. This list should expand when they game increases in scope beyond a single room. If you think of a standalone room type I haven’t covered below, please leave a comment with your idea.

The Simple Barracks

Inspiration: Virtually any RPG

A basic room with some enemies and their equipment. Nothing to write home about, but if every room was really interesting, they wouldn’t stand out.

The Environmental Hazard Room

Inspiration: Super Metroid

The room is too hot, and will damage your character over time. The door itself is too hot to touch. Find some heat-protective armour or use a heat protective spell to survive the room and escape.

The Dormant Room

Inspiration: Adventures of Lolo

The room contains dormant enemies which will awaken upon finding the key to exit the room. Steps can be taken to destroy the enemies or limit their mobility prior to grabbing the key. Adventures of Lolo was one of my favourite NES games, and I always thought the mechanic was excellent.

The Laser Room (pew pew)

Inspiration: Penny Arcade D&D Session

A beam of light must be reflected through the room in order to activate mechanisms and weaken enemies, but it is hazardous to cross the beam yourself. Wax Golems and Ant Men, here we come.

Shop

The final version of The Room will drop you from one Room to the next, persisting stats, so a shop level is appropriate. I can insert them after every few rooms to give the player a chance to restock and sell. And give me the chance to implement trade in this version.

Verse 1:4

Door locked securely
First obstacle encountered
Where did that key go?

In addition to the controls in the in-game instructions, you can press Home to save state and End to load state.

This verse forced me to answer some important questions about how to handle interactions between Entities in the game. In the end, Entities remained simple data structures for physical objects. Interactors were created to handle complex interactions separately. Any interaction which occurs at the basic Entity level will be a part of the physical Simulation. Interactors will be used to simulate complex behaviour that is not physically modelled.

Obviously the door falls into this category, but also inventories. The player is carrying a key around, but I am not modelling the key hanging from a belt or in a pocket, it’s just holistically “in the player’s inventory”. Once I’ve had time to iron out the whole system, I’ll post some source code for it and a deeper explanation.

Verse 1:5

A woman in robes
“It’s dangerous to go alone!”
“Take this,” she insists

package com.andrewtraviss.illfate.data
{
   import flash.utils.ByteArray;
 
   public class Terrain
   {
      public var tileIndex:int = -1;
      public var sheetIndex:int = -1;
      public var friction:Number = 1;
      public var passable:Boolean = true;
   }
}

This is the Terrain class that we are saving. This is pretty straightforward. Since IllFate is at an early stage there isn’t much data to worry about. This is why I wanted to get the system in place now. I am making it a general rule that all game objects store their state information in separate data structure classes. This makes it easier to create scenarios for testing and makes features like this one easier to implement.

package com.andrewtraviss.illfate.factories
{
   import com.andrewtraviss.illfate.data.Terrain;
 
   import flash.utils.ByteArray;
 
   public class TerrainFactory
   {
      public static function fromBytes(in_bytes:ByteArray):Terrain
      {
         var terrain:Terrain = new Terrain();
         terrain.passable = in_bytes.readBoolean();
         terrain.tileIndex = in_bytes.readInt();
         terrain.sheetIndex = in_bytes.readInt();
         terrain.friction = in_bytes.readFloat();
         return terrain;
      }
   }
}

The creation code is implemented in a factory. Why not put it into the Terrain class? Creation of the terrain instance should be an atomic operation if at all possible. It makes any code that has to create terrain much more readable. If a configureFromBytes method was implemented in Terrain itself, that would require two operations every time we needed to create an instance from data. Compare the following.

var terrain = new Terrain();
terrain.configFromBytes(terrainData);

var terrain = TerrainFactory.fromBytes(terrainData);

The abstraction of details will become more important if other subsystems need to get involved with Terrain creation. Any time I look at TerrainFactory it’s going to be because I am interested in the details of creating an instance. Once there are more complex relationships to manage, this will also protect Terrain from acquiring new dependencies.

package com.andrewtraviss.illfate.serialization
{
   import com.andrewtraviss.illfate.data.Terrain;
 
   import flash.utils.ByteArray;
 
   public class TerrainSerializer
   {
      public static function toBytes(in_terrain:Terrain):ByteArray
      {
         var bytes:ByteArray = new ByteArray();
         bytes.writeBoolean(in_terrain.passable);
         bytes.writeInt(in_terrain.tileIndex);
         bytes.writeInt(in_terrain.sheetIndex);
         bytes.writeFloat(in_terrain.friction);
         bytes.position = 0;
         return bytes;
      }
   }
}

For much the same reason that construction is in a separate class, serialization was implemented by TerrainSerializer. Keeping the underlying data structure classes free of dependencies is one of my general goals with this project as a whole.

package com.andrewtraviss.illfate.tests
{
   import com.andrewtraviss.illfate.data.Terrain;
   import com.andrewtraviss.illfate.factories.TerrainFactory;
   import com.andrewtraviss.illfate.serialization.TerrainSerializer;
 
   import flash.utils.ByteArray;
 
   import flexunit.framework.TestCase;
 
   public class SaveLoadTerrainTests extends TestCase
   {
      public function testBasic():void
      {
         var saveTerrain:Terrain = new Terrain();
         saveTerrain.friction ++;
         saveTerrain.passable = !saveTerrain.passable;
         saveTerrain.sheetIndex ++;
         saveTerrain.tileIndex ++;
         var terrainData:ByteArray = TerrainSerializer.toBytes(saveTerrain);
         var loadTerrain:Terrain = TerrainFactory.fromBytes(terrainData);
         assertEquals(saveTerrain.friction, loadTerrain.friction);
         assertEquals(saveTerrain.passable, loadTerrain.passable);
         assertEquals(saveTerrain.sheetIndex, loadTerrain.sheetIndex);
         assertEquals(saveTerrain.tileIndex, loadTerrain.tileIndex);
      }
   }
}

And here’s the unit test, to cap it off. Rather than injecting some magic numbers, all properties are just changed in some way from the default before saving. Numbers are incremented and booleans are inverted. This is enough to ensure that the values are changed from the defaults.

Eventually this approach will become awkward, that’s plainly obvious. I have to reference every property three times in the testing code, once in the loading code, and once in the saving code. This will add a constant drag as I need to update all of these places whenever I add a property to any game object that must be saved. I will need to generalize it in some way. I’ll include details with the Verse 1:4 release post if something happens.

Verse 1:3

In quite a hurry,
but the ice is treacherous.
The walls are not soft.

Hold shift to run. When running, you will slide around on the ice a bit. If you strike a wall hard enough, you can bounce off of it and take some damage.

Challenge: Physics

Every time I make a run at my own physics implementation I utterly fail to remember any of my vector math, so that absorbed some time as I reacquainted myself with an old friend. Once I got it working, the result was really ugly. This was the time for TDD to shine. This was the first real test of TDD’s vaunted ability to make refactoring easier and more comfortable, and it did just that. I didn’t need to test the actual game until I was done all of the changes, and it worked, which was a nice feeling.

My initial implementation saw the Collider class calculating the forces involved in the collision and then applying the forces to the entities. Once I got this working, I noticed this:

From PhysicalSimulation.as

public function applyForceToEntity(in_force:Point, in_entity:Entity):void
{
   in_entity.xVelocity += in_force.x;
   in_entity.yVelocity += in_force.y;
   invalidateEntity(in_entity);
}

From Collider.as

public function applyForceToEntity(in_force:Point, in_entity:Entity):void
{
   in_entity.xVelocity += in_force.x/in_entity.mass;
   in_entity.yVelocity += in_force.y/in_entity.mass;
}

Not only were these duplicate code, but at the moment, they were working differently. I rolled up my sleeves and updated the Collider class to just calculate and return the force of the collision instead of actually acting on the objects. The PhysicalSimulation takes care of actually applying the force to the Entities, and now takes mass into account. This involved rewriting most of the unit tests for the Collider class, since my expectations were now based on the returned force rather than inspecting the properties of the entities.

One thing I want to do differently, versus my last Roguelike attempt, is to implement saving very early in development, so that every feature can be developed with game saves as part of the testing. My next goal doesn’t directly imply this should be done, but I will be tackling it as part of the test implementation.

Verse 1:4

Door locked securely
First obstacle encountered
Where did that key go?

Verse 1:2

Walk across the room.
That door looks awfully nice.
I just won the game.

W, A, S, D keys move the character. Depending on browser and operating system, you may need to click on the game before the controls will work.

In order to meet this goal, I had to rough out the physics system just enough to get the player character moving around. I opted for a force-based interface into the physics system; each step action instructs the physics system to apply a force to the player entity in the appropriate direction, rather than directly changing the player’s position or velocity. The physics system deals with all of the consequences from there on.

Unfortunately, after the first step there is leftover velocity that results in the player flying across the screen. Nothing is slowing the player down. I considered a few different ways to handle this.

1. Remember the previous step and apply an opposing force before stepping again
2. Scrap force-based physics altogether in favour of just instructing the physics system to move an object from A-to-B
3. Implement friction

Option #1 is not very attractive for many reasons. Rather than working with the here and now, we’re making decisions based on previous actions. Any changes that occur between the original step and the new step have to be taken into account when determining if a counter-force must be applied, and how much force to necessary.

Option #2 was tempting, as it mirrors my previous Roguelike work more closely. However, working only with forces instead of velocities or actual positions ensures that the physics remains black boxed. This is inconvenient in some ways, but that is far outweighed by the benefit of keeping physics decoupled from the rest of the code base. Previous projects have demonstrated that physics are particularly apt at latching themselves onto everything around them once you decide to open them up.

That leaves me with option #3; as an entity moves across a surface, friction is applied. I’m currently tracking velocity as an integer, so the one tile velocity of walking is rounded to 0 by friction after one calculation. This puts me in a great position to implement a couple of features. The character can run by applying more force per action, and icy surface jut needs a low friction coefficient. I’ve set my next goal with this in mind. Testing out how the physics implementation handles different situations will tell me whether or not I made the right choice.

Verse 1:3

In quite a hurry,
but the ice is treacherous.
The walls are not soft.

/*
 Copyright (c) 2009 Andrew Traviss
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation
 files (the "Software"), to deal in the Software without
 restriction, including without limitation the rights to use,
 copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following
 conditions:
 
 The above copyright notice and this permission notice shall be
 included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
*/
package com.andrewtraviss.flexunit
{
   import flash.display.BitmapData;
 
   import flexunit.framework.TestCase;
 
   public class VisualTestCase extends TestCase
   {
      public function VisualTestCase(methodName:String=null)
      {
         super(methodName);
      }
      protected function assertBitmapsMatch(in_expected:BitmapData, in_actual:BitmapData):void
      {
         oneAssertionHasBeenMade();
         if(!areIdentical(in_expected, in_actual))
         {
            failBitmapsMatch();
         }
      }
      protected function assertBitmapsDoNotMatch(in_notExpected:BitmapData, in_actual:BitmapData):void
      {
         oneAssertionHasBeenMade();
         if(areIdentical(in_notExpected, in_actual))
         {
            failBitmapsDoNotMatch();
         }
      }
      private function areIdentical(in_bitmapDataA:BitmapData, in_bitmapDataB:BitmapData):Boolean
      {
         var result:* = in_bitmapDataA.compare(in_bitmapDataB);
         if(result is BitmapData)
         {
            return false;
         }
         else
         {
            return (result == IDENTICAL);
         }
      }
      private function failBitmapsMatch():void
      {
         fail("Expected identical bitmaps, actual bitmaps are different.");
      }
      private function failBitmapsDoNotMatch():void
      {
         fail("Expected different bitmaps, actual bitmaps are identical.");
      }
      private const IDENTICAL:int = 0;
   }
}

Here’s a quick usage example from the unit tests for my CellRenderer class. Note that this code has not been spit-shined, so it’s a bit rougher. I’ve included just enough of the class to communicate the gist.

override public function setUp():void
{
   super.setUp();
   surface = createSurface();
   cellRenderer = new CellRenderer();
   cell = MapCellFactory.createCell(0,0);
   terrain = createTestTerrain();
   testSheet = createTestSheet();
 
   cellRenderer.useSurface(surface);
   cell.terrain = terrain;
}
public function testCellTerrain():void
{
   target = new BitmapData(TILE_SIZE, TILE_SIZE, false, 0xff0000);
 
   assertBitmapsDoNotMatch(target, surface);
   cellRenderer.renderCellFromSheet(cell, testSheet);
   assertBitmapsMatch(target, surface);
}
public function testCellWithActor():void
{
   target = new BitmapData(TILE_SIZE, TILE_SIZE, false, 0xff0000);
   target.fillRect(new Rectangle((TILE_SIZE-2)/2,(TILE_SIZE-2)/2,2,2), 0xffffff);
 
   var actorSprite:BitmapData = new BitmapData(TILE_SIZE, TILE_SIZE, true, 0x00000000);
   actorSprite.fillRect(new Rectangle((TILE_SIZE-2)/2,(TILE_SIZE-2)/2,2,2), 0xffffffff);
 
   var actor:Actor = new Actor();
   actor.sprite = actorSprite;
   cell.addActor(actor);
 
   assertBitmapsDoNotMatch(target, surface);
   cellRenderer.renderCellFromSheet(cell, testSheet);
   assertBitmapsMatch(target, surface);
}

Instead of writing out a bunch of requirements documentation, which would just slow me down, I will be focusing on a single goal at any given time. That goal will be summarized using a haiku. Why a haiku? I was inspired by the way that the Adams brothers use short stories to generate goals and requirements for Dwarf Fortress. I want to keep my release cycles very tight, so I wanted to limit the size of any given change. Using a constrained verse structure seems like a natural way to do it. If I can’t fit it into a haiku, it’s probably too much to do at once.

Every time I implement a verse, I will release the latest build and share the next haiku.

Verse 1:1

An empty room waits.

Only four walls and a floor.

Better than nothing.

This version isn’t really a game yet. The renderer is operational, and the basic map structures are in place. A single actor is rendered along with a small room. It will be some time before we leave this room. In fact the goal of the game will be to escape the room, until there is enough meat to justify tackling dungeon generation and other large topics.

Verse 1:2

Walk across the room.

That door looks awfully nice.

I just won the game.