MemoryManager revisited

Starting with DS version 1.1, there is now a new MemoryManager available, which was almost written from scratch. My past experience showed that the former implementation was somewhat limited, as you were forced to preallocate a fixed amount of memory prior to your application’s entry point. The new version now supports dynamic memory allocation, so memory consumption grows with application demand (you can still define an upper limit to be on the safe side). It’s now also possible to resize memory space after it has been allocated. I’ve also simplified the API and optimized the code.

Using alchemy memory in HaXe is now as simple as writing:

var integerArray = new IntMemory(x);
integerArray.free();

The first line allocates space for storing x 32-bit integers, and the second line will free up used memory once it’s no longer needed. The same also applies to BitMemory (a bit vector), ShortMemory (16-bit integers), FloatMemory (32-bit IEEE 754 single-precision floats) and DoubleMemory (64-bit IEEE 754 double-precision floats). Each implementation provides a get/set method to read/write the value from/to index i (I hope HaXe gets support for overriding [] in the future so we can omit the get()/set() methods); an offset property that stores the memory offset in bytes and a bytes property indicating the number of allocated bytes. Custom classes can be realized by inheriting from the abstract MemoryAccess class (yes, HaXe has private constructors ;-))

Frequent allocation/deallocation leads to fragmentation so the user can request defragmentation by calling MemoryManager.defrag(). In addition to the defrag() method, MemoryManager.pack() frees up unused space so it can be garbage collected. To be exact: All existing bytes are copied from the current ByteArray accessed by the alchemy memory opcodes to a smaller ByteArray, and once the reference to the former ByteArray is GC’ed the former content is deallocated (setting the .length property of the ByteArray seems to be a bit flaky and sometimes results in a runtime exception).

A quick note about MemoryManager.BLOCK_SIZE_BYTES: This value defines the growth-rate of the memory. The default is 1024 bytes (must be a power of 2). Every time the MemoryManager runs out of memory, a multiple of this block size is added. The block size affects performance and storage efficiency. As a rule of thumb the block size should match the average size of all ‘memory arrays’ used in the application. Using a tiny block size when storing 2k images is obviously a bad idea.

A major advantage of using alchemy memory is that you can use the appropriate data size that fits your needs which brings down memory usage. For example if you know in advance that your numbers are in the range 0…100 you can use bytes, or if you need floats without full 64-bit precision, you can fall back to 32-bit floats. In AS3, you are constrained to 32-bit integers or 64-bit double precision floats. Using the ByteArray is not an option because it’s too slow.

Performance

Although the preview version of FP 10.1 slowed down memory access a bit (it seems that the latest release fixes most performance issues) using those special alchemy memory opcodes is by far the best way to work with numbers. Time for some real world examples!

Example 1: JPEG encoding

After porting the JPEG encoder from the Flex framework (mx.graphics.codec) to HaXe I’ve encoded an empty 1024×786 bitmap and compared the numbers:

The HaXe version encodes the image in about 100 milliseconds, the AS3 version takes almost a second.

Example 2: Bit vectors

My next test compares an AS3 bit vector implementation from generalrelativity.org with the BitMemory from the ds package:

Combining alchemy memory, optimized byte code and inlining gives some excellent results :)

Example 3: FP10 drawing API

The last test draws triangles with the FP10 drawing API and measures the time needed to build a GraphicsPath object from a command and a data vector (without calling graphics.drawGraphicsData()). The HaXe version uses my VectorRenderer class which utilizes alchemy memory as a temporary buffer.

All results are based on the windows release player 10,0,42,34 and use the MemoryManager class.

Traversing the display list

A great HaXe feature is that you can define your own Iterator and execute it with the for-syntax.
It can be used in many different ways and drastically improves readability of your code. AS3 developers often need to look at the display list, so I wrote a basic DisplayListIterator to handle this task. Here is an example:

using de.polygonal.gl.DisplayListIterator;
...
for (i in Lib.current.stage) trace(i);

This will print out all display objects in the display list.

If you are not familiar with HaXe, Lib.current.stage points to the MovieClip of the Document class, and the using statement automatically creates a DisplayListIterator whenever it is called on a DisplayObjectContainer. So the statement ‘Class.method(arg)’ is transformed to ‘arg.method()’. Without ‘using’ I would have to write:

import de.polygonal.gl.DisplayListIterator;
...
for (i in new DisplayListIterator(Lib.current.stage)) trace(i);

Let’s finish with a simple example that changes the text color of all text fields to red inside a DisplayObjectContainer.

var container:Sprite = myTextFieldContainer;
for (i in container)
{
  if (Std.is(i, TextField))
  {
    cast(i, TextField).textColor = 0xff0000;
  }
}

Useful, isn’t it :)

Ace of Mace

Last year some guys started to work on a game called Ace of Mace built on top of my physics engine. It was officially released yesterday and won a price at the Europrix Multimedia Award before. Today it’s featured as the Adobe Site of the day. Great work!

Speaking about motor2, version 0.9 was released at the end of last year, and now I’m working on it to get a major release done.

Firefighter - The Mission

I just want to introduce a game called ‘Firefighter - The Mission‘ that can be played here. It’s somewhat a milestone for me because it’s the first game I coded as a freelancer. It was finished at the end of last year, but was just published now. The game is build upon an efficient isometric game (which you probably won’t notice that much because the animated fire and smoke effects are serious performance killer).

A unique game feature is the collision detection. All collisions are computed in 2d, so the game does not need coordinate space transformations (rotation about y and x axis). In fact, 90% of the code only uses additions, multiplications and bit shifting, so I think it should also run well on mobile devices.

Collision handling is divided into two parts, which are often referred to as broad phase and narrow phase. The broad phase step just checks if the 4 adjacent tiles on which the player stands are walkable and adjusts the player position accordingly. The narrow phase step uses a system I like to call ‘Micro Collision Cells’. Every tile has a fine grid of cells - much smaller than the player itself, and each cell can be turned on/off in the level editor. When the engine is fired up, all flagged cells are merged into the smallest possible amount of larger axially aligned bounding boxes (AABB). For example, if a tile has a resolution of 5×5 cells, and each cell is flagged, the engine would have to check 5×5 = 25 cells in total, but the simplification leads to one box covering the full tile.

Another feature I worked on was exact line-of-sight computation. This is used to get a valid range of tiles in front of the player that can be extinguished (very important for z-sorting the water particles). Scrolling is tile based and follows the principle of tonypa’s well known tutorial about tile based games.
Because there wasn’t much time to develop the game, I left out some advanced features like ‘line of sight’ for visibility determination (similar to a fog of war in strategy games), but I will definitely port and extend the engine to AS3, since it is easily adapted to other graphics sets or tile sizes which should come in handy if a similar project comes along.

How to debug fast-paced action games

During the development of my last game I took a different approach of debugging it which is especially useful for real time games. Because it’s so simple I’m wondering why I haven’t used this method before (perhaps too lazy ? ;-)) Usually you include a bunch of trace statements everywhere or create a logger system which prints out the information you need. But this is useless in games where many simultaneous events occur. Your logger will be flooded with messages so it’s hard to keep track of everything.

The idea is to include a simple playback control by using keys or invoking a custom breakpoint() method, so you can stop and resume the game at any time and trace out additional information with it. Here is how it’s done (again, basic stuff here):

var updateGame:Boolean = true;
var useBreakpoints:Boolean = false;

//main loop: update game logic, render scene..
function tick():Void
{
	if (!updateGame) return;

	update();
	render();
}

function update():Void
{
	//...
	if (player.collides(wall)) breakpoint("player-wall collision");
	//...
}

So whenever the player collides with the wall, the game stops and prints out the passed string. The breakpoint function itself can look like this:

function breakpoint(message:String, forced:Boolean):Void
{
    //just quit if breakpoints are disabled
    //this can be overridden by setting forced=true
    if (!useBreakpoints && !forced) return;

    //print out message and stop game
    trace("breakpoint:" + message);
    updateGame = false;
}

Obviously, when breakpoint() is called, ‘updateGame’ is set to false so the main loop stops doing anything. The function also checks if breakpoints are enabled so you can globally turn them on or off. Furthermore, you have the option to call breakpoint() with a forced flag, so even if breakpoints are entirely disabled, your game will stop at that point. This is useful to keep some breakpoints active for very rare events or stuff you aren’t sure is working at all and at the same time you can test the game without being constantly bothered by existing regular breakpoints. I have also defined some keys:

function onKeyDown()
{
    switch (String.fromCharCode(Key.getAscii()))
    {
        //stop/resume game
        case "u":

            updateGame = !updateGame;
            break;

        //toggle breakpoints
        case "b":

            useBreakpoints = !useBreakPoints;
            trace("breakpoints " + (useBreakpoints ? "on" : "off"));
            break;

        //step through game
        case "s": 

            if (!updateGame)
            {
                update();
                render();
            }
            break;
    }
}

Game playback is toggled with ‘u’, and when the game is frozen by a breakpoint call, you can advance frame-by-frame by pressing the ’s’ key or resume playing by pressing ‘u’. This makes debugging much easier because you actually now have the time to think about what’s going on when something goes wrong ;-).