A closer look at the Awe6 Haxe inverted game framework

I just recently took a look at available Haxe game engines and decided to take a closer look at two of them, HaxeFlixel and Awe6.  I started with Awe6, as frankly it’s the most non-traditional of the two options and as a result, the most interesting to me.

 

Awe6 is a very design pattern heavy framework, built around the concepts of Inversion of Control and Dependency Injection, but reality is, just about every single design pattern that isn’t the Singleton make an appearance.  As a direct result though, groking it all can be a bit confusing… my current understand of things took a great deal of digging through code and documentation to arrive at.  That is one immediate problem with Awe6…  the number of examples available can at best be called lacking.

 

I actually prefer going through working code than I do documentation, so this part is a rather large disappointment.  Then again, if I document awe6 usage, I suppose I will have more people interested in the material, double edged sword I suppose.  Anyways, so far as existing code to work from, there is the incredibly simple Hello World example, the demo in github and finally this example, probably the best of the bunch.

 

 

Ok, enough about what other people have done, now lets take a look at what I’ve discovered.  One of the ongoing trends of Haxe development holds true for Awe6.  If you are developing on Windows using FlashDevelop, the process is amazingly smooth.  If you aren’t… it isn’t.  I’ve given in and just work under FlashDevelop, at least when creating my projects.  I deploy to Dropbox then can reboot and test in Mac if needed.  The following instructions apply to Windows/Flashdevelop only.  You can get it working on other OSes, but its a pain.

 

Getting started is brutally simple.  If you haven’t already, install Haxe and NME.

Open a command prompt and type haxelib install awe6

Then run the command haxelib run awe6 install

 

That’s it.  Assuming you have FlashDevelop installed, you can now create a new awe6 Project via the project menu, otherwise refer to their site for details of working from command line.  It will create a fully fleshed out folder structure for you, but truth is, when just starting out this is a bit daunting.  That said, the Hello World example is a bit too trivial, so I set about writing something that is middle ground… a more advanced Hello World, or less advanced example project, depending on your perspective.

 

This awe6 sample simply loads an image and allows you to manipulate it using the left and right arrows.  The code:

 

 

import awe6.Types;  import nme.display.Bitmap;  import nme.display.BitmapData;  import nme.display.Sprite;  import nme.Assets;  import nme.Lib;    /**   * ...   * @author Mike   */    class Main  {  	static function main()  	{  		var l_factory = new Factory( Lib.current, '<?xml version="1.0" encoding="utf-8"?><data></data>' );  	}  	  	public function new()  	{  		// needed for Jeash  	}  }    class MyImage extends Entity  {  	private var _sprite:Sprite;  	  	public function new( p_kernel:IKernel )  	{  		_sprite = new Sprite();  		super(p_kernel, _sprite);  	}  	  	public override function _init(): Void {  		super._init();  		_sprite.addChild(new Bitmap(Assets.getBitmapData("assets/img/mechwarriorFrameScaled.png")));  	}  	  	override private function _updater(?p_deltaTime:Int = 0): Void  	{  		super._updater(p_deltaTime);  		if (_kernel.inputs.keyboard.getIsKeyDown(EKey.RIGHT))  			_sprite.x += 10;  		if (_kernel.inputs.keyboard.getIsKeyDown(EKey.LEFT))  			_sprite.x -= 10;  	}  }    class Factory extends AFactory {  	public override function createScene( type : EScene) : IScene  	{  		var scene = new Scene(this._kernel, type);  		scene.addEntity(new MyImage(this._kernel),true);  		return scene;  	}  }  

 

 

 

Below is the Flash target if you want to play around with it (click it first to give keyboard focus, then price left or right arrow):

 

If you created a Awe6 project, you will notice the one above is a great deal simpler, but all the same basics are there.  Some of the terminology may certainly seem alien to you… Factory? Entity?  But don’t worry, its not actually that difficult in the end.

 

Let’s start with the Factory…  this is basically the “guts” of your game…  guts actually is probably the wrong analogy… brains would be a more accurate description or perhaps backbone.  Essentially you extend the Factory class to implement specific behaviour to your game by overriding a series of methods.  In our simple example above, we override the createScene method, but there are dozens of other methods and members that you can set.  The full documentation is right here.  Essentially the factory configures/defines your game, handles special actions ( such as the back key ), allows you to provide your own implementation of the Sessions, Preloader, Overlay, etc…  

 

So, if Factory is the brains or backbone of your application, Scenes are the meat of it.  This is how you organize your game into manageable pieces.  You could create a Scene for say… the title screen, one for when the game is playing, one for displaying the high scores, one for credits, one for settings, etc.  On top of this, literally, you have the Overlay, which is basically a top level UI or HUD if you like.  Your Factory class can create one, but I believe you can also create one at the Scene level as well.

 

After Scene, we have entities… simply put, these are “things” in your game, visible or not.  This could be… your main player, an enemy or a simple proximity trigger.  Entities can in turn contain other entities.  A Scene can contain numerous entities which themselves can contain many more.  Each entity will receive an update() call per tick for updating itself.  That’s the bare basics of the hierarchy of objects and that just scratches the surface… it doesn’t touch on other aspects such as Agendas ( state machines ), Session ( game state ), Preloader ( asset loading/caching ), or many other aspects of the framework.  We also don’t touch on the kernel yet, which is a very important concept that we will talk about in a moment.

 

Now, lets take a quick look at how our code works, in order of execution.  When our program’s main() is called, we simply create an instance of Factory, a class we define that inherits from AFactory.  We pass in the context as well as a simple empty configuration in this case.  As part of the process ( we will look a bit deeper in a second ) our Factory classes createScene method is called.  In createScene, we create a simple scene and add a MyImage entity to it. MyImage is a simple Entity that contains a Sprite class holding our mech image.  In the updater method ( called each tick when the entity needs to update ), we check the kernel for input, and move our position accordingly.

 

Now, understanding exactly what is going on behind the scenes is probably the trickiest part, so lets take a closer look at the process.

 

As we mentioned earlier, the Factory class is critical to your game, forming it’s backbone, setting major configuration settings and perhaps most importantly controlling scene creation.  This is where execution begins.  You inherit from AFactory, but awe6 remaps it to an appropriate version depending on your platform ( you can see this logic in action right here, the same trick is performed for a number of classes ), all of the platform specific implementations simply provide platform specific functionality, but ultimately inherit from this guy, AFactory.hx.  It’s kinda confusing at first, but you only really need to involve yourself in the details if you are trying to grok the source code.  The most important part of of AFactory to understand at this point is this call:

 

inline private function _init():Void
{
#if haxe3
config = new Map<String,Dynamic>();
#else
config = new Hash<Dynamic>();
#end
_configure( true );
_driverInit();
}

 

The call _driverInit() is of critical importance.  This is where the kernel is created.  What is the kernel, other than the object we keep passing around?  Well if Factory is the backbone of your game, Kernal is the backbone of awe6.  Essentially, kernel IS the game engine, and ultimately it is created by your Factory class ( or more specifically, the class your factory inherits from ).  So, obviously kernel is important, let’s take a look at it’s Init() method, it will make a great deal of things clear:

 

override private function _init():Void

{

super._init();

_view = new View( this, _context, 0, this );

_processes = new List<IProcess>();

_helperFramerate = new _HelperFramerate( factory.targetFramerate );

_isPreloaded = false;

 

// Perform driver specific initializations.

isDebug = factory.isDebug;

isLocal = _driverGetIsLocal();

_driverInit();

 

// Initialize managers.

assets = _assetManagerProcess = new AAssetManager( _kernel );

audio =_audioManager = new AudioManager( _kernel );

inputs = _inputManager = new InputManager( _kernel );

scenes = _sceneManager = new SceneManager( _kernel );

messenger = _messageManager = new MessageManager( _kernel );

_view.addChild( _sceneManager.view, 1 );

_addProcess( _assetManagerProcess );

_addProcess( _inputManager );

_addProcess( _sceneManager );

_addProcess( _messageManager );

_addProcess( _audioManager );

 

// Set defaults for visual switches.

isEyeCandy = true;

isFullScreen = false;

 

// Signal completion to the factory and initialize factory-dependent components.

factory.onInitComplete( this );

 

session = factory.createSession();

session.reset();

_preloader = factory.createPreloader();

_addProcess( _preloader );

_view.addChild( _preloader.view, 2 );

}

 

This is where the various subsystems are created ( assetManager, audio, input, etc… ) and started running ( via addProcess call ).  Then you will notice the code calls back into the Factory, calling the onInitiComplete method.  At this point, the Factory now has a copy of the kernel and the kernel has a pointer to the factory.  One other very important call for program execution is 

_view.addChild( _sceneManager.view, 1 );

View is something drawn on screen, in this case the main window.  In sceneManager, this is where we go full circle, with the call:

scene = _kernel.factory.createScene( p_type );


This in turn is what calls our derived Factory class’s createScene method, causing the Scene to be created, our entity to be added to the scene, etc…

 

The bright side is, you don’t really need to know ANY of this to make use of Awe6.  I just personally hate using a framework if I don’t understand process flow.  It’s a clever architecture, decoupling key systems and allowing for you to organize your own code in a clean manner, while still enabling communication between various systems.

Design


Scroll to Top