Which begs the question of how I got into game development. Most choreographers do something else to supplement their choreography income, it comes with the low-pay high-satisfaction territory. Some teach dance or do other dance related work, others wait tables in restaurants. I wrote code – it paid better and I enjoyed it. Eventually, a few years back, I stopped choreographing and focused entirely on game development.

Which is all background to what I want to talk about. Reading Daniel Cook’s recent article, How Revolutionaries become The Man, and particularly the section on game design teaching, caused me to remember, and dwell on, how I was taught choreography.

Teaching choreography

The first thing to note about my choreography learning is that it all took place in dance studios. I was never required to read books or analyze other choreographers’ work, although I did so by choice. I was encouraged to watch lots of dance, and my teachers made time to discuss what I’d seen if I asked them to, but choreography teaching was based around one activity – choreographing. The thinking, in essence, was the more you choreograph the more you learn. So, during my three years at dance school I choreographed 14 dances of varying length.

And while at dance school there were three choreography teachers from whom I learnt a lot.

Jane Dudley was a legend in the contemporary dance world. She was a dancer in Martha Graham’s original company and had over 50 years experience as a choreographer. Jane taught a class of her own devising, in which she choreographed a dance on us, the students, while asking us for ideas that she might use in the dance. Through this she encouraged our creativity, allowing us to express all sorts of crazy ideas, some of which she used and some she didn’t. Through this we also saw first hand, from the best vantage, how she built a dance piece, overlaying ideas, providing counterpoints, and discarding content without regret if it didn’t quite work. The result was a dance work that we all had a hand in creating.

I also asked Jane to watch and feedback on my work, which she seemed to enjoy doing. She was unreserved in both praise and criticism. Above all Jane emphasised the importance of creating something interesting. It wasn’t enough to craft with skill if what you were crafting was not unique in some small way. Jane helped me to understand and pay attention to the ideas that drove my work, to know what would make each dance special.

Ingegerd Lönnroth was quiet, unassuming and could dissect a dance with precision and present the truth with kindness. She sometimes struggled with a class full of students, but she was brilliant with individuals or small groups. On one occasion I showed her a piece I was working on. Inge watched the piece through once, then asked the dancers to perform one specific section again. Half way through she pointed and said “There”, and as she said it I realised how, with one careless move, I had broken the purpose and flow of the dance, and Inge had spotted it on a single viewing of the dance. Through her I learnt to pay attention to the details, to care about every moment. I also started to learn one of the most difficult skills of a creator, how to view my work with the dispassionate eye of a neutral observer. To see the dance as it was, not as I wanted it to be.

Kim Brandstrup was brilliant at telling stories with dance. But what I learnt from him was not about stories, it was about craft. He taught me how to shape a phrase of dance, to give it highs and lows, to make it deliberate and to give it purpose. In his choreography classes he would present us with simple, short exercises – a rhythm, a theme, a message – and ask us to create a phrase of dance, mere seconds in length, and refine it to convey the goal he’d presented. Then we’d watch each other’s work and discuss what succeeded and didn’t, and why. Kim taught me craft.

So, I learnt to choreograph by choreographing. I was only required to choreograph one work per year but I was encouraged to do much more. I used other dancers at the school in my dances. Most of the time I used prerecorded music, or on a couple of occasions no music at all, and there were no specific costumes or lighting because learning to craft the dance was what mattered.

In my final year I was lucky to work with a couple of composers from nearby music schools, a brilliant design student from a theatre school, and a friend of a friend who was a lighting designer. By then I was showing my work to the public and the addition of these other skills, and learning to work with those who had these skills, was important.

Choreography was an important part of my degree. I was assessed and marked by experts who watched what I’d choreographed, discussed it with me, and decided how many marks it deserved. There was no written exam, no testing my understanding of choreographic theory. To test my choreography, I choreographed and the examiners assessed the result.

What if game design was taught like I was taught choreography?

I don’t presume to know how game design is taught at universities around the world. I have heard stories, and if those stories are correct then it has little in common with how I was taught choreography. If game design was taught how I was taught choreography then I guess it would look something like this.

Students are encouraged to create games, working with fellow students as artists and programmers. They create multiple games every year, in various genres, exploring ideas, pushing boundaries, discovering for themselves, with guidance and help from experts who work or have worked in the industry. They learn craft from small exercises, designing solutions to specific problems or designing a critical few seconds of a game.

They are encouraged to read, to play, and to discuss what they read and play. But there is no right and wrong for them to be taught, instead there is opinion to be formed and skill to be acquired.

Each year they also work with a professional game designer, as assistant designers and level designers, to create a complete game for release to the world (their colleagues studying programming, art and music build this game that they design, also under the guidance of professionals from the industry).

Every year, they present their best work for assessment by experienced game designers and the marks from this are their assessment. And at the end of their course, after designing 14 games or so, they will have started to form their own vision of what games they want to design and to gain the skills with which to design them.

If I went back to school, that’s the game design course I’d like to learn from.

The difficulty with finite state machines in an entity system framework like Ash can be summed up in one sentence – the state pattern doesn’t work with an entity system framework. Entity system frameworks use a data-oriented paradigm in which game objects are not self-contained OOP objects. So you can’t use the state pattern, or any variation of it. All the data is in the components, all the logic is in the systems.

If your states are few and simple it is possible to use a good old fashioned switch statement inside a system, with the data for all the states in one or more components that are used by that system, but I wouldn’t usually recommend that.

When creating Stick Tennis I was faced with the problem of how to manage states as the two main entities in the game are the two players, and they go through a number of states as they…

• prepare to serve
• swing arm to toss the ball
• release the ball
• swing the racquet
• hit the ball
• follow through
• run to a good position
• react to the opponent hitting the ball
• run to intercept the ball
• swing the racquet
• hit the ball
• follow through
• run to a good position
• react to winning the point
• …etc

Stick Tennis is a complex example, and I can’t show you the source code, so instead I’ll use something a little simpler, with source code.

An example

Lets consider a guard character in a game. This character patrols along a path, keeping watch. If they spot an enemy, they attack him/her.

In a traditional object-oriented state machine we might have a class for each state

public class PatrolState
{
    private var guard : Character;
    private var path : Vector.<Point>;

    public function PatrolState( guard : Character, path : Vector.<Point> )
    {
        this.guard = guard;
        this.path = path;
    }

    public function update( time : Number ) : void
    {
        moveAlongPath( time );
        var enemy : Character = lookForEnemies();
        if( enemy )
        {
            guard.changeState( new AttackState( guard, enemy ) );
        }
    }
}

public class AttackState
{
    private var guard : Character;
    private var enemy : Character;

    public function AttackState( guard : Character, enemy : Character )
    {
        this.guard = guard;
        this.enemy = enemy;
    }

    public function update( time : Number ) : void
    {
        guard.attack( enemy );
        if( enemy.isDead )
        {
            guard.changeState( new PatrolState( guard, PatrolPathFactory.getPath( guard.id ) );
        }
    }
}

In a entity system architecture we have to take a slightly different approach, but the core principle of the state pattern, to split the state machine across multiple classes, one for each state, can still be applied. To implement the state machine in an entity framework we will use one System per state.

public class PatrolSystem extends ListIteratingSystem
{
    public function PatrolSystem()
    {
        super( PatrolNode, updateNode );
    }

    private function updateNode( node : PatrolNode, time : Number ) : void
    {
        moveAlongPath( node );
        var enemy : Enemy = lookForEnemies( node );
        if( enemy )
        {
            node.entity.remove( Patrol );
            var attack : Attack = new Attack();
            attack.enemy = enemy;
            node.entity.add( attack );
        }
    }
}

public class AttackSystem extends ListIteratingSystem
{
    public function AttackSystem()
    {
        super( AttackNode, updateNode );
    }

    private function updateNode( node : PatrolNode, time : Number ) : void
    {
        attack( node.entity, node.attack.enemy );
        if( node.attack.enemy.get( Health ).energy == 0 )
        {
            node.entity.remove( Attack );
            var patrol : Patrol = new Patrol();
            patrol.path = PatrolPathFactory.getPath( node.entity.name );
            node.entity.add( patrol );
        }
    }
}

The guard will be processed by the PatrolSystem if he has a Patrol component, and he will be processed by the AttackSystem if he has an Attack component. By adding/removing these components from the guard we change his state.

The components and nodes look like this…

public class Patrol
{
    public var path : Vector.<Point>;
}

public class Attack
{
    public var enemy : Entity;
}

public class Position
{
    public var point : Point;
}

public class Health
{
    public var energy : Number;
}

public class PatrolNode extends Node
{
    public var patrol : Patrol;
    public var position : Position;
}

public class AttackNode extends Node
{
    public var attack : Attack;
}

So, by changing the components of the entity, we change the entities state and thus change the systems that process the entity.

Another example

Here’s another, more complex example using the Asteroids example game that I use to illustrate how Ash works. I’ve add an additional state to the spaceship for when it’s shot. Rather than simply removing the spaceship when it is shot, I show a short animation of it breaking up. While doing this, the user won’t be able to move it and the spaceship won’t react to collisions with other objects.

The two states require the following

While the ship is alive -

• It looks like a spaceship
• The user can move it
• The user can fire its gun
• It collides with asteroids

When the ship is dead -

• It looks like bits of a spaceship floating in space
• The user cannot move it
• The user cannot fire its gun
• It doesn’t collide with asteroids
• After a fixed time it is removed from the game

The relevant piece of code, where the spaceship dies, is in the CollisionSystem. Without the second state it would look like this

for ( spaceship = spaceships.head; spaceship; spaceship = spaceship.next )
{
    for ( asteroid = asteroids.head; asteroid; asteroid = asteroid.next )
    {
        if ( Point.distance( asteroid.position.position, spaceship.position.position )
            <= asteroid.position.collisionRadius + spaceship.position.collisionRadius )
        {
            creator.destroyEntity( spaceship.entity );
            break;
        }
    }
}

The code tests whether the ship is colliding with an asteroid, and if it is it removes the ship. Elsewhere, the GameManager system handles the situation where there is no spaceship and creates another one, if any are left, or ends the game. Instead of destroying the spaceship, we need to change its state. So, lets try this...

We can prevent the user controlling the spaceship by simply removing the MotionControls and GunControls components. We might as well remove the Motion and Gun components while we’re at it since they're of no use without the controls. So we replace the code above with

for ( spaceship = spaceships.head; spaceship; spaceship = spaceship.next )
{
    for ( asteroid = asteroids.head; asteroid; asteroid = asteroid.next )
    {
        if ( Point.distance( asteroid.position.position, spaceship.position.position )
            <= asteroid.position.collisionRadius + spaceship.position.collisionRadius )
        {
            spaceship.entity.remove( MotionControls );
            spaceship.entity.remove( Motion );
            spaceship.entity.remove( GunControls );
            spaceship.entity.remove( Gun );
            break;
        }
    }
}

Next, we need to change how the ship looks and remove the collision behaviour

for ( spaceship = spaceships.head; spaceship; spaceship = spaceship.next )
{
    for ( asteroid = asteroids.head; asteroid; asteroid = asteroid.next )
    {
        if ( Point.distance( asteroid.position.position, spaceship.position.position )
            <= asteroid.position.collisionRadius + spaceship.position.collisionRadius )
        {
            spaceship.entity.remove( MotionControls );
            spaceship.entity.remove( Motion );
            spaceship.entity.remove( GunControls );
            spaceship.entity.remove( Gun );
            spaceship.entity.remove( Collision );
            spaceship.entity.remove( Display );
            spaceship.entity.add( new Display( new SpaceshipDeathView() ) );
            break;
        }
    }
}

And finally, we need to ensure that the spaceship is removed after a short period of time. To do this, we’ll need a new system and component like this

public class DeathThroes
{
    public var countdown : Number;
        
    public function DeathThroes( duration : Number )
    {
        countdown = duration;
    }
}

public class DeathThroesNode extends Node
{
    public var death : DeathThroes;
}

public class DeathThroesSystem extends ListIteratingSystem
{
    private var creator : EntityCreator;
    
    public function DeathThroesSystem( creator : EntityCreator )
    {
        super( DeathThroesNode, updateNode );
        this.creator = creator;
    }

    private function updateNode( node : DeathThroesNode, time : Number ) : void
    {
        node.death.countdown -= time;
        if ( node.death.countdown <= 0 )
        {
            creator.destroyEntity( node.entity );
        }
    }
}

We add the DeathThroesSystem to the game at the start, so it will handle the drawn-out death of any entity. Then we add the DeathThroes component to the spaceship when it dies.

for ( spaceship = spaceships.head; spaceship; spaceship = spaceship.next )
{
    for ( asteroid = asteroids.head; asteroid; asteroid = asteroid.next )
    {
        if ( Point.distance( asteroid.position.position, spaceship.position.position )
            <= asteroid.position.collisionRadius + spaceship.position.collisionRadius )
        {
            spaceship.entity.remove( MotionControls );
            spaceship.entity.remove( Motion );
            spaceship.entity.remove( GunControls );
            spaceship.entity.remove( Gun );
            spaceship.entity.remove( Collision );
            spaceship.entity.remove( Display );
            spaceship.entity.add( new Display( new SpaceshiopDeathView() ) );
            spaceship.entity.add( new DeathThroes( 5 ) );
            break;
        }
    }
}

And that is our state transition. The transition is achieved by altering which components the entity has.

The state is encapsulated in its components

This is the general rule of the entity system architecture - the state of an entity is encapsulated in its components. If you want to change how an entity is processed, you should change its components. That will alter which systems operate on it and that changes how the entity is processed.

Standardised state machine code

To help with state machines I’ve added some standard state machine classes to Ash. These classes help you manage states by defining states based on the components they contain, and then changing state simply by specifying the new state you want.

A finite state machine is an instance of the EntityStateMachine class. You pass it a reference to the entity it will manage when constructing it. You will usually store the state machine in a component on the entity so it can be recovered from within any system that is operating on the entity.

var stateMachine : EntityStateMachine = new EntityStateMachine( guard );

A state machine is configured with states, and the state can be changed by calling the state machine's changeState() method. States are identified by a string, which is assigned when the state is created and used to identify the state when calling the changeState() method.

States are instances of the EntityState class. They may be added to the EntityStateMachine using the EntityStateMachine.addState() method, or they may be created and added in one call using the EntityStateMachine.createState() method.

var patrolState : EntityState = stateMachine.createState( "patrol" );
var attackState : EntityState = stateMachine.createState( "attack" );

A state is a set of components that should be added to the entity when that state is entered, and removed when that state exits (unless they are also required for the next state). The add method of the EntityState specifies the type of component required for the state and is followed by a rule specifying how to create that component.

var patrol : Patrol = new Patrol();
patrol.path = PatrolPathFactory.getPath( node.entity.name );
patrolState.add( Patrol ).withInstance( patrol );
attackState.add( Attack );

The four standard rules for components are

entityState.add( type : Class );

Without a rule, the state machine will create a new instance of the given type to provide the component every time the state is entered.

entityState.add( type : Class ).withType( otherType : Class );

This rule will create a new instance of the otherType every time the state is entered. otherType should be the same as or extend the specified component type. You only need this rule if you create component classes that extend other component classes and should be treated as the base class by the engine, which is rare.

entityState.add( type : Class ).withInstance( instance : * );

This method will use the provided instance for the component every time the state is entered.

Finally

entityState.add( type : Class ).withSingleton();

or

entityState.add( type : Class ).withSingleton( otherType : Class );

will create a single instance and use that one instance every time the state is entered. This is similar to using the withInstance method, but the withSingleton method will not create the instance until it is needed. If otherType is omitted, then the singleton with be an instance of type, if included it will be of otherType and otherType must be the same as or extend type.

Finally, you can use custom code to provide the component by implementing the IComponentProvider interface and then using your custom provider with

entityState.add( type : Class ).withProvider( provider : IComponentProvider );

The IComponentProvider interface is defined as

public interface IComponentProvider
{
    function getComponent() : *;
    function get identifier() : *;
}

The getComponent method returns a component instance. The identifier in the IComponentProvider is used to compare two component providers to see if they will effectively return the same component. This is used to avoid replacing a component unnecessarily if two successive states use the same component.

The methods are designed to be chained together, to create a fluid interface, as you’ll see in the next example.

Back to the examples

If we apply these new tools to the spaceship example, the states are set-up when the spaceship entity is created, as follows

var fsm : EntityStateMachine = new EntityStateMachine( spaceshipEntity );

fsm.createState( "playing" )
   .add( Motion ).withInstance( new Motion( 0, 0, 0, 15 ) )
   .add( MotionControls )
       .withInstance( new MotionControls( Keyboard.LEFT, Keyboard.RIGHT, Keyboard.UP, 100, 3 ) )
   .add( Gun ).withInstance( new Gun( 8, 0, 0.3, 2 ) )
   .add( GunControls ).withInstance( new GunControls( Keyboard.SPACE ) )
   .add( Collision ).withInstance( new Collision( 9 ) )
   .add( Display ).withInstance( new Display( new SpaceshipView() ) );

fsm.createState( "destroyed" )
   .add( DeathThroes ).withInstance( new DeathThroes( 5 ) )
   .add( Display ).withInstance( new Display( new SpaceshipDeathView() ) );

var spaceshipComponent : Spaceship = new Spaceship();
spaceshipComponent.fsm = fsm;
spaceshipEntity.add( spaceshipComponent );
fsm.changeState( "playing" );

and the state change is simplified to

for ( spaceship = spaceships.head; spaceship; spaceship = spaceship.next )
{
    for ( asteroid = asteroids.head; asteroid; asteroid = asteroid.next )
    {
        if ( Point.distance( asteroid.position.position, spaceship.position.position )
            <= asteroid.position.collisionRadius + spaceship.position.collisionRadius )
        {
            spaceship.spaceship.fsm.changeState( "destroyed" );
            break;
        }
    }
}

To do

There will be further refinement and additions to the state machine tools based on feedback so please do let me know how you get on with them. Use the mailing list for Ash to get in touch.

The simple option doesn’t work

The first thing to note is that Apple deliberately limited the new retina resolution to Apps built with the iOS 5.1 SDK. This is to avoid incompatibility issues with Apps that were released before the new iPad was available. So apps built with earlier versions of the iOS SDK use pixel doubling and have an effective resolution of 1024×768 pixels, like the iPad 2.

By default, Adobe Air compiles with iOS 4.0. I don’t know what’s special about iOS 4.0 that Adobe can distribute this version with Air but not later versions, but that’s the way it is. So, if you compile your Air app the normal way, you will not get retina resolution on the new iPad. Everything will still work fine, but it will use pixel doubling to get the same results as on the iPad 2.

Compiling with iOS 5.1

If you have a Mac, there is a solution. Adobe Air (since Air 3.1) includes a build setting to specify the version of the iOS SDK to use. The setting is the platformsdk and you can read more about it on this Adobe blog. If you read through the comments in that post you’ll see that this is only supported when compiling on OSX, at the moment, but Adobe hope to bring it to Windows sometime in the future.

So, if you have a Mac, download and install XCode. In the new XCode, the SDK is inside the application package – the filepath is /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.1.sdk/. Now use the playformsdk setting to build against iOS 5.1.

The test

To test this I built a little app, with just a few lines of code –

package com.sticksports.test
{
  import flash.display.Sprite;
  import flash.display.StageAlign;
  import flash.display.StageScaleMode;
  import flash.events.Event;
  import flash.system.Capabilities;
  import flash.text.TextField;

  public class RetinaTest extends Sprite
  {
    public function RetinaTest()
    {
      stage.scaleMode = StageScaleMode.NO_SCALE;
      stage.align = StageAlign.TOP_LEFT;
      addEventListener( Event.ENTER_FRAME, getStats );
    }
    
    private function getStats( event : Event ) : void
    {
      removeEventListener( Event.ENTER_FRAME, getStats );
      
      var textField : TextField = new TextField();
      textField.width = stage.stageWidth - 40;
      textField.height = stage.stageHeight - 40;
      textField.x = 20;
      textField.y = 20;
      textField.border = true;
      textField.multiline = true;
      addChild( textField );
      
      textField.appendText( "Capabilities.screenResolutionX : " + Capabilities.screenResolutionX + "\n" );
      textField.appendText( "Capabilities.screenResolutionY : " + Capabilities.screenResolutionY + "\n" );
      textField.appendText( "Capabilities.screenDPI : " + Capabilities.screenDPI + "\n" );
      textField.appendText( "stage.stageWidth : " + stage.stageWidth + "\n" );
      textField.appendText( "stage.stageHeight : " + stage.stageHeight + "\n" );
      textField.appendText( "stage.fullScreenWidth : " + stage.fullScreenWidth + "\n" );
      textField.appendText( "stage.fullScreenHeight : " + stage.fullScreenHeight + "\n" );    }
  }
}

I didn’t use Flash Builder for my tests because I’m an FDT user, so the apps were built from Ant scripts. First I built the swf in the standard way.

<exec executable="${sdk.home}/bin/amxmlc" failonerror="true" dir="../package">
  <arg line='-source-path ../src'/>
  <arg line='-default-size=960,640'/>
  <arg line='-default-background-color 0xFFFFFF'/>
  <arg line='-default-frame-rate 60'/>
  <arg line='-debug=false'/>
  <arg line='-optimize=true'/>
  <arg line='-swf-version=13'/>
  <arg line='-output RetinaTest.swf'/>
  <arg line='../src/com/sticksports/test/RetinaTest.as'/>
</exec>

I gave the swf a default size to match the iPhone, just to see what Air gave me as the stage size as a result.

The application descriptor file requests the high resolution display, as for the iPhone retina screen.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<application xmlns="http://ns.adobe.com/air/application/3.0">

  <id>com.sticksports.RetinaTest</id>
  <filename>RetinaTest</filename>
  <name>Retina Test</name>
  <versionNumber>0.0.1</versionNumber>
  <versionLabel>v0.0.1</versionLabel>
  <copyright>Stick Sports Ltd.</copyright>

  <initialWindow>
    <content>RetinaTest.swf</content>
    <aspectRatio>portrait</aspectRatio>
    <autoOrients>true</autoOrients>
    <fullScreen>true</fullScreen>
    <renderMode>cpu</renderMode>
    <softKeyboardBehavior>none</softKeyboardBehavior>
    </initialWindow>

  <icon>
    <image29x29>icons/icon_29.png</image29x29>
    <image57x57>icons/icon_57.png</image57x57> 
    <image72x72>icons/icon_72.png</image72x72> 
    <image114x114>icons/icon_114.png</image114x114> 
  </icon>
  
  <iPhone>
    <InfoAdditions>
      <![CDATA[
        <key>UIDeviceFamily</key>
        <array>
          <string>1</string>
          <string>2</string>
        </array>
        <key>UIStatusBarStyle</key>
        <string>UIStatusBarStyleBlackOpaque</string>
      ]]>
    </InfoAdditions>
    <requestedDisplayResolution>high</requestedDisplayResolution>
  </iPhone>

</application>

I built the ipa twice, using the Air 3.2 release candidate from Adobe Labs. I built it once using the default version of the iPhone SDK (version 4.0) that is bundled with Air.

<exec executable="${sdk.home}/bin/adt" failonerror="true" dir="../package">
  <arg value="-package"/>
  <arg value="-target"/>
  <arg value="ipa-ad-hoc"/>
  <arg value="-provisioning-profile"/>
  <arg value="${ios.provisioning.profile}"/>
  <arg value="-storetype"/>
  <arg value="pkcs12"/>
  <arg value="-keystore"/>
  <arg value="${ios.keystore.file}"/>
  <arg value="-storepass"/>
  <arg value="${ios.keystore.password}"/>
  <arg value="../publish/default/RetinaTest.ipa"/>
  <arg value="../build/RetinaTest-app.xml"/>
  <arg value="RetinaTest.swf"/>
  <arg value="Default.png"/>
  <arg value="icons"/>
</exec>

And once with the iOS 5.1 SDK

<exec executable="${sdk.home}/bin/adt" failonerror="true" dir="../package">
  <arg value="-package"/>
  <arg value="-target"/>
  <arg value="ipa-ad-hoc"/>
  <arg value="-provisioning-profile"/>
  <arg value="${ios.provisioning.profile}"/>
  <arg value="-storetype"/>
  <arg value="pkcs12"/>
  <arg value="-keystore"/>
  <arg value="${ios.keystore.file}"/>
  <arg value="-storepass"/>
  <arg value="${ios.keystore.password}"/>
  <arg value="../publish/5.1/RetinaTest.ipa"/>
  <arg value="../build/RetinaTest-app.xml"/>
  <arg value="RetinaTest.swf"/>
  <arg value="Default.png"/>
  <arg value="icons"/>
  <arg line="-platformsdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.1.sdk/"/>
</exec>

The equivalent command-line script is

adt -package -target ipa-ad-hoc -provisioning-profile YOUR_PROVISIONING_PROFILE -storetype pkcs12 -keystore YOUR_KEYSTORE_FILE -storepass YOUR_KEYSTORE_PASSWORD RetinaTest.ipa RetinaTest-app.xml RetinaTest.swf Default.png icons -platformsdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.1.sdk/

The results

With the default SDK the results are

Capabilities.screenResolutionX : 768
Capabilities.screenResolutionY : 1024
Capabilities.screenDPI : 132
stage.stageWidth : 960
stage.stageHeight : 640
stage.fullScreenWidth : 768
stage.fullScreenHeight : 1024

I was surprised the stageWidth and stageHeight don’t match the screenResolutionX and screenResolutionY, which is why I use the latter in my projects. As Florian mentioned in the comments, you can also use fullScreenWidth and fullScreenHeight, which I added after reading his comment. Aside from that, there’s no surprises here. The results are the same as on the iPad2.

With iOS 5.1 SDK, the results are

Capabilities.screenResolutionX : 1536
Capabilities.screenResolutionY : 2048
Capabilities.screenDPI : 132
stage.stageWidth : 1536
stage.stageHeight : 2048
stage.fullScreenWidth : 1536
stage.fullScreenHeight : 2048

This version uses the full resolution of the retina screen. The text is half the size on screen because the pixel resolution is doubled and the screenResolutionX and screenResolutionY and fullScreenWidth and fullScreenHeight are the correct size for the retina display. This time, surprisingly, the stageWidth and stageHeight did match the screen resolution – all the more reason not to trust them. Also, the screenDPI is incorrect, showing the same value as the iPad 2.

But, most importantly, the project has access to the full retina screen resolution. Hurrah!

Building with Air 3.1

As I said above, I initially used the public beta of Air 3.2 for this test. I reran the test using Air 3.1 and the results were the same, except building with Air 3.1 and iOS 5.1 gave the stageWidth as 1920px and stageHeight as 1280px. All other results were the same as for Air 3.2.

Documentation

1. Getting Started

Here’s a couple of useful getting started guides. If you don’t know what you’re doing, this is a good place to start. There are more on the web, just ask Google.

• Extending Adobe Air
• AIR Native Extension Example: iBattery for iOS

2. Read Adobe’s documentation.

For the most part Adobe’s documentation is comprehensive and detailed. Use it.

Writing the Actionscript code

3. Pay attention to the Actionscript API

Make an Actionscript API that suits the functionality you’re implementing. Don’t get pulled into copying Apple’s iOS API in Actionscript if there’s a better, more Actionscript like, way to do it.

Remember, changing the implementation later only affects the extension, but changing this API breaks all projects that use the extension so make it as good as you can.

4. Maximise the error checking in your Actionscript code

You need to check the input to your extension methods to avoid errors. You could do this in the native code, but it’s a lot easier to do it in the Actionscript code. If you know you’ll always call the native code with the correct number of parameters, and that those parameters will always be valid values, you can avoid a lot of error checking in the native code.

Of course, if you enjoy writing error checking code in C, go right ahead. Personally, I prefer to do this in Actionscript.

5. Always create a default implementation

Even if you’re only planning to use your extension on iOS, create a default implementation anyway. You build this default implementation in pure Actionscript, so it works on all platforms. It implements the same API as the iOS version, but using only Actionscript. That means it may throw errors or returns null values, but it will be valid Actionscript code that you can compile against for platforms other than iOS.

Without a default implementation, you can only ever test your app on an iOS device. This makes testing your app during development very tiresome. Being able to compile your app for desktop Air to test a new feature that’s unrelated to your native extension is very useful.

Writing the native code

6. Use Objective-C to interface to Apple’s APIs.

You don’t have to use Objective-C, but if you’re interfacing with any of Apple’s APIs it’s easier if you do. Otherwise, you can use C or C++.

7. Place the C code for the Air-Native interface in a .m file.

The interface between the native code and Air is via C, so your native code will include one file of C code to provide this interface. If you place this code inside a .c file, you can’t use any Objective-C functionality in there (e.g. you can’t use objective-c style code to call objective-c APIs), but if you place it inside a .m file you can. So life is easier if you use a .m extension.

8. The .m file containing the Air-Native interface doesn’t need a .h header file.

But you’ll want to disable the error messages so turn off warnings for “missing function prototypes” in your XCode project settings.

9. Use unique names for your extension initializer and finalizer functions.

A number of example extensions use generic names like “extInitializer” and “extFinalizer” for the initializer and finalizer functions. No two extensions in your project may have the same names for these functions, so use names that are appropriate to your project.

10. Use macros in your source code

How many times can you type

FREObject someFunction(FREContext context, void* functionData, uint32_t argc, FREObject argv[])

before you want to poke yourself in the eye with a blunt stick? Create a macro for this, and any other repetitive tasks for implementing the Air-Native interface. You can see a few of my macros in this source file. (Thank you to David Wagner for some of these.)

11. Set “Enable linking with shared libraries” to yes

There’s a lot of noise around the web about this XCode project setting, with some saying use “no” and some saying use “yes”. Basically, setting this to yes means your extension will be linked with the required libraries later when you compile your app. This is what you want. But it means when you compile your Air app that uses your native extension, you’ll need to direct the compiler to the iOS SDK so it can link to the libraries. See item 18 below.

N.B. If you get a build error

ld warning: unexpected srelocation type 9

then you probably either have this setting as no or you haven’t specified the location of the iOS SDK when building your app.

12. Be careful with threads

Your native extension can’t create Actionscript objects in any but the main thread from which it is called, and must do so during a call from Air. This makes using blocks in your objective-c code problematic. However, there is one thing you can do from another thread, and that is dispatch an event to the Actionscript ExtensionContext. This offers a solution

1. In your block or other threaded code, store your data into a native object.
2. Dispatch an event to your ExtensionContext with whatever details it needs for step 3.
3. In response to the event, call a native method to fetch the object.
4. In this native method, create the Actionscript object from the native object created in step 1 and return it.

13. Creating native views

Your Air application runs inside a standard native window. You can get a reference to this window as

[UIApplication sharedApplication].keyWindow

Once you have this window reference you can add subviews to it to display native views.

Compiling the Extension

14. Automate the compiling and testing of your extension

When building my Game Center extension I created a simple air app for testing the extension.

I created an ant build script to compile the whole extension (build the native C/obj-C library, build the native AS3 library, build the default AS3 library, wrap them all as an Air native extension) and to build the test project.

The result, one click in Eclipse and I had the extension built and the test project built against it, ready to drop on my phone (and using the Organiser in XCode makes this last step easy too). The result – it took about 10 seconds to go from writing code to having the test project with the latest extension on my phone. That’s still 9 seconds too long but it’s a lot better than most workflows I’ve seen.

Maybe there’s a better way if you use Flash Builder (I use FDT), and you certainly don’t have to use Ant – any build tool will do. But streamline the build and test process as much as you can. My ant scripts are in my Game Center extension project if you want them.

15. Using a third party library

If you’re using a third party library in your extension (e.g. the Flurry analytics library in my Flurry extension), include that library along with your compiled native library in the “-platform iPhone-ARM” argument when compiling the extension.

16. You may need a platform.xml file.

If using any but the most common libraries in the iOS SDK, create a platform.xml file to specify the libraries you’re using and the minimum iOS version to build against.

I create a platform.xml file for all my extensions – it hides the warning about unknown minimum iOS version that Air 3.1 will display if you don’t.

Building your mobile application

17. If your IDE doesn’t know about native extensions, use the .swc from the default implementation.

This swc contains the full Actionscript API of the native extension in a pure Actionscript implementation, so you can code against it, and compile with it for testing on your dev computer.

Of course, an IDE that doesn’t know about native extensions won’t build your mobile app correctly, but you’re using a build script for that aren’t you.

18. Specify the location of the iOS SDK when compiling your Air mobile app.

By default, the Air compiler compiles against version 4.0 of the iOS SDK. If your native extension uses features that don’t exist in this version it will fail to compile because the required libraries can’t be found. Specify the location of a later version of the iOS SDK to enable this linking. See this blog post for more details.

In Flash Builder, there is a setting for this somewhere in the various screens for configuring the native extensions your project uses. If you’re using the command line compiler, use the -platformsdk compiler flag to specify the path to the iOS SDK.

Unfortunately, this is only possible if you’re compiling your app on Mac OS X. Adobe are, apparently, working to get this working on Windows too. If you try to use a native extension that requires you to link to the SDK and don’t link to it, you will get a compile error like this (the second line may or may not be present).

Compilation failed while executing : ld64
ld: unknown option: -ios_version_min

Unfortunately, this means that for the time being some native extensions can only be used if you compile on a Mac.

19. ld: warning: ARM function not 4-byte aligned

When compiling your app, you may get a number of warnings of the form

ld: warning: ARM function not 4-byte aligned

These are just warnings and nothing to worry about. 4-byte alignment is an optimisation rather than a requirement.

When it’s all done

20. Make your native extension available to others.

Having completed your extension, you have three choices

1. Keep it to yourself
2. Open-source it for other developers
3. Sell it to other developers

Ask yourself what makes your app unique and special. If it’s not your native extension (and it very rarely is) then choosing option 2 or 3 may have many benefits for you like code contributions from others or additional income.

Further, by making your extension available to other developers you strengthen the ecosystem around Adobe Air as a tool for mobile development. This encourages other developers to use Air and encourages Adobe to continue to develop and improve it. This is in your interests.

At Stick Sports we favour option 2 because we’d rather spend time marketing and supporting our games than marketing and supporting our extensions as commercial products.

If you ask people who attend conferences why they do it, most of them will tell you it’s for the networking. Some of the presentations will be good, but it’s the conversations, over coffee, over beer, and over dinner, that make the conference worthwhile. Because the best thing you get from a conference is the opportunity to share experiences with other developers, to talk about code, to learn from each other.

try{harder} has that in spades. try{harder} is about sixteen experienced developers teaching and learning. Seminars, code jams, pair programming, and of course conversations. Not shallow chats, but important debates, with depth and breadth, explored over a four day period. Sometimes lubricated with fine scotch whisky (thank you David). The experience is intense, exhausting, exhilirating, and absolutely wonderful.

October’s try{harder} was the first. After it I’d learnt more about TDD than I’d learnt in the previous two years of (sometimes) unit testing my code. I’d learnt enough to kickstart my development of Air native extensions. I’d learnt about build tools, debugging tools, and promises. I’d learnt about the inner workings of the Flash player, and about Robotlegs 2 and SwiftSuspenders 2. I’d learnt about myself. And I’d been inspired enough to dig deeper into Entity frameworks and to write Ash.

And more than all that, I’d gained sixteen new friends. That’s fifteen great developers and Stray‘s lovely wife Helen. These are friends who know and understand what I do for a living. Friends I can turn to for advice and help, as I did recently when wondering which cloud platform would suit a particular need.

This spring will see another try{harder} born. This one is subtitled ‘level-up’ because it’s all about the alumni from the previous try{harder} sharing their experience and their knowledge with eight other, less experienced developers. It’s about helping those mid-to-senior developers realise their potential.

It will feature the same mix of seminars, programming and conversations. The same intense learning experience. But in addition, to help the newcommers they will each be mentored by an alumni.

I am very disappointed that I can’t be a mentor at try{harder} level-up. Unfortunately I have work commitments that can’t be moved. But the mentors who will be there are fantastic.

If you’re looking to improve your developer skills, try{harder} level-up is an opportunity to learn from the best. I highly recommend it.

So, in this post I will look more at what the final architecture is, what it gives us that other architectures don’t, and why I personally prefer this architecture.

The core of the architecture

First, it’s worth noting that the core of this architecture is the components and the systems. Components are value-objects that contain the state of the game, and systems are the logic that operates on that state, changing it as the game progresses. The other elements of the architecture are purely incidental, designed to make life easier.

The entity object is present to collect related components together. The relation between components is encapsulated by the concept of an entity and that is vital to the architecture, but it isn’t necessary to use an explicit Entity object for this. There are some frameworks that simply use an id to represent the entity, adding the entity id to every component to indicate which entity it belongs to. In this scenario there is no requirement for an entity object at all and entity based operations are performed through an entity manager, using the id to indicate which entity they are operating on.

As a concept, the entity is vital to the architecture. But as a code construct it is entirely optional. I include it because, when using an object-oriented language, the entity object makes life easier. In particular, it enables us to create the methods that operate on the entity as methods of an entity object and to track and manage the entity through this object, removing the need to track ids throughout the code.

While the concept of an entity is vital to the architecture, the concept of node objects is entirely incidental. The nodes are used as the objects in the collections of components supplied to the systems. We could instead provide each system with a collection of the relevant entities and let the systems pull the components they want to operate on out of the entities, using the get() method of the entity.

In Ash, the nodes serve two purposes. First they enable us to use a more efficient data structure in which the node objects that the systems receive are nodes in a linked list. This improves the execution speed of the framework.

Second, using the node objects enables us to apply strong, static typing throughout our code. The method to fetch a component from an entity necessarily returns an untyped object, which must then be cast to the correct component type for use in the game code. The properties on the node are already statically typed to the components’ data types, so no casting is necessary.

So, fundamentally, the entity architecture is about components and systems.

This is not object-oriented programming

We can build our entity architecture using an object-oriented language but, on a fundamental level, this is not object-oriented programming. The architecture is not about objects, it’s about data (components) and sub-routines that operate on that data (systems).

For many object-oriented programmers this is the hardest part of working with an entity system framework. Our tendency is to fall back to what we know and as an object-oriented programmer using an object-oriented language that means encapsulating data and operations together into objects. If you do this with a framework like Ash you will fail.

Data-Oriented Programming

Games tend to be about lots of fast changing state, with players, non-player characters, game objects like bullets and lasers, bats and balls, tables and chairs, and levels, scores, lives and more all having state that might include position, rotation, speed, acceleration, weight, colour, intention, goals, desires, friendships, enemies and more.

The state of the game can be encapsulated in this large mass of constantly changing data, and on a technical level the game is entirely about what this data is and how this data changes.

In a game a single little piece of this data may have many operations acting on it. Take, for example, a player character that has a position property that represents the character’s position in the game world. This single piece of data may be used by

• The render system, to draw the player in the world.
• The camera system, to position the camera relative to the player.
• The AI systems of all non-player characters, to decide how they should react to the player.
• The input system, which alters the player’s position based on user input.
• The physics system, which alters the player’s position based on the physics of the game world.
• The collision system, which tests whether the player is colliding with other objects and resolves those collisions.

and probably many more systems besides. If we try to build our game using objects that encapsulate data with the operations that act on that data, then we will build dependencies between all these different systems as they all want to be encapsulated with the player’s position data. This can’t be done unless we code the game as one single, massive class, so inevitably we break some parts of the game into separate systems and provide data to those systems – the physics system, the graphics system – while including other elements of the game logic within the entity objects themselves.

An entity architecture based on components and systems takes the idea of discrete systems to its logical conclusion. All operations are programmed as independent systems, and all game state is stored separately in a set of data components, which are provided to the systems according to their need.

The systems are decoupled form each other. Each system knows only about itself and the data it operates on. It knows and cares nothing at all about the other systems and how they may have affected by or used the data before or after this system gets to work with it.

Also, by embracing the system as the core logic of the architecture, we are encouraged to make many smaller and simpler systems rather than a few large complex ones, which again leads to simpler code and looser coupling.

This decoupling makes building your game much easier. It is why I enjoy working with this form of entity system so much, and why I built Ash.

Storing the game state

Another benefit of the component/system architecture is apparent when you want to save and restore the game state. Because the game state is contained entirely in the components, and because these are simple value objects, saving the game state is a relatively simple matter of serialising out the components, and restoring the game state involves just deserialising the data back in again.

In most cases, serialising a value-object is straightforward, and one could simply json-encode each component, with additional data to indicate its entity owner (an id) and its component type (a string), to save the game state.

Adam Martin wrote about comparing components in an entity system framework to data in a relational database (there’s lots of interesting entity related stuff on Adam’s blog), and emphasising that conversion between a relational database for long-term storage and components for game play doesn’t require any object/relational mapping, because components are simple copies of the relational database’s data structure rather than complex objects.

This leads further to the conclusion that a component/system architecture is ideal for an MMO game, since state will be stored in a relational database on the game servers, and much of the processing of that state will occur on the servers, where using a set of discrete, independent systems to process the data as the game unfolds is an excellent fit to both the data storage requirements of the state and the parallelism available on the servers.

Concurrency

Indeed, a component/system architecture is well suited to applying concurrency to a game. In most games, some of the systems are entirely independent of each other, including being independent of the order in which they are applied. This makes it easy to run these systems in parallel.

Further, most systems consist of a loop in which all nodes are processed sequentially. In many cases, the loop can be parallelised since the nodes can be updated independently of each other.

This gives us two places in the code where concurrency can be applied without altering the core logic of the game, which is inside the loop in the systems, or the core state of the game, which is in the components.

This makes adding concurrency to the game relatively simple.

We don’t need object-orientation

Finally, because the component/system architecture is not object-oriented, it lends itself to other programming languages that implement different programming paradigms like functional programming and procedural programming. While I created Ash as an Actionscript framework, this architecture would be well suited to Javascript for client side development or any of the many functional languages used for highly concurrent server side development.

Update: In-game editors

Tom Davies has pointed out that a very valuable benefit to him is how easy it is to create an in-game level editor when developing with an entity system framework like Ember or Ash. You can see his example here.

I agree with Tom, this is a very useful benefit of these frameworks. The complete separation of the game state and the game logic in an entity system framework makes it easy to create an editor that lets you alter the state (configuration, level design, AI, etc.) while playing the game. Add to this the easier saving and loading of state and you have a framework that is very well suited to in-game editing.

• try{harder}, 6 October 2011

In this session, I compared building a game (Asteroids) using an entity framework (Ember) and an MVC framework (Robotlegs) and concluded that the entity framework was more suited to this task. I then attempted to explain why.

I also wrote a blog post that covers much of the material in this presentation.

These are the slides from the presentation at try{harder} on Thursday, 6 October 2011.

Entity systems are growing in popularity, with well-known examples like Unity, and lesser known frameworks like Actionscript frameworks Ember2, Xember and my own Ash. There’s a very good reason for this; they simplify game architecture, encourage clean separation of responsibilities in your code, and are fun to use.

In this post I will walk you through how an entity based architecture evolves from the old fashioned game loop. This may take a while. The examples will be in Actionscript because that happens to be what I’m using at the moment, but the architecture applies to all programming language.

This is based on a presentation I gave at try{harder} in 2011.

The examples

Throughout this post, I’ll be using a simple Asteroids game as an example. I like to use Asteroids as an example because it involves simplified versions of many of the systems required in larger games – rendering, physics, ai, user control of a character, non-player characters.

The game loop

To understand why we use entity systems, you really need to understand the old-fashioned game loop. A game loop for Asteroids might look something like this

function update( time:Number ):void
{
  game.update( time );
  spaceship.updateInputs( time );
  for each( var flyingSaucer:FlyingSaucer in flyingSaucers )
  {
    flyingSaucer.updateAI( time );
  }
  spaceship.update( time );
  for each( var flyingSaucer:FlyingSaucer in flyingSaucers )
  {
    flyingSaucer.update( time );
  }
  for each( var asteroid:Asteroid in asteroids )
  {
    asteroid.update( time );
  }
  for each( var bullet:Bullet in bullets )
  {
    bullet.update( time );
  }
  collisionManager.update( time );
  spaceship.render();
  for each( var flyingSaucer:FlyingSaucer in flyingSaucers )
  {
    flyingSaucer.render();
  }
  for each( var asteroid:Asteroid in asteroids )
  {
    asteroid.render();
  }
  for each( var bullet:Bullet in bullets )
  {
    bullet.render();
  }
}

This game loop is called on a regular interval, usually every 60th of a second or every 30th of a second, to update the game. The order of operations in the loop is important as we update various game objects, check for collisions between them, and then draw them all. Every frame.

This is a very simple game loop. It’s simple because

1. The game is simple
2. The game has only one state

In the past, I have worked on console games where the game loop, a single function, was over 3,000 lines of code. It wasn’t pretty, and it wasn’t clever. That’s the way games were built and we had to live with it.

Entity system architecture derives from an attempt to resolve the problems with the game loop. It addresses the game loop as the core of the game, and pre-supposes that simplifying the game loop is more important than anything else in modern game architecture. More important than separation of the view from the controller, for example.

Processes

The first step in this evolution is to think about objects called processes. These are objects that can be initialised, updated on a regular basis, and destroyed. The interface for a process looks something like this.

interface IProcess
{
  function start():Boolean;
  function update( time:Number ):void;
  function end():void;
}

We can simplify our game loop if we break it into a number of processes to handle, for example, rendering, movement, collision resolution. To manage those processes we create a process manager.

class ProcessManager
{
  private var processes:PrioritisedList;

  public function addProcess( process:IProcess, priority:int ):Boolean
  {
    if( process.start() )
    {
      processes.add( process, priority );
      return true;
    }
    return false;
  }

  public function update( time:Number ):void
  {
    for each( var process:IProcess in processes )
    {
      process.update( time );
    }
  }

  public function removeProcess( process:IProcess ):void
  {
    process.end();
    processes.remove( process );
  }
}

This is a somewhat simplified version of a process manager. In particular, we should ensure we update the processes in the correct order (identified by the priority parameter in the add method) and we should handle the situation where a process is removed during the update loop. But you get the idea. If our game loop is broken into multiple processes, then the update method of our process manager is our new game loop and the processes become the core of the game.

The render process

Lets look at the render process as an example. We could just pull the render code out of the original game loop and place it in a process, giving us something like this

class RenderProcess implements IProcess
{
  public function start() : Boolean
  {
    // initialise render system
    return true;
  }

  public function update( time:Number ):void
  {
    spaceship.render();
    for each( var flyingSaucer:FlyingSaucer in flyingSaucers )
    {
      flyingSaucer.render();
    }
    for each( var asteroid:Asteroid in asteroids )
    {
      asteroid.render();
    }
    for each( var bullet:Bullet in bullets )
    {
      bullet.render();
    }
  }
  
  public function end() : void
  {
    // clean-up render system
  }
}

Using an interface

But this isn’t very efficient. We still have to manually render all the different types of game object. If we have a common interface for all renderable objects, we can simplify matters a lot.

interface IRenderable
{
  function render();
}

class RenderProcess implements IProcess
{
  private var targets:Vector.<IRenderable>;

  public function start() : Boolean
  {
    // initialise render system
    return true;
  }

  public function update( time:Number ):void
  {
    for each( var target:IRenderable in targets )
    {
      target.render();
    }
  }
  
  public function end() : void
  {
    // clean-up render system
  }
}

Then our spaceship class might contain some code like this

class Spaceship implements IRenderable
{
  public var view:DisplayObject;
  public var position:Point;
  public var rotation:Number;

  public function render():void
  {
    view.x = position.x;
    view.y = position.y;
    view.rotation = rotation;
  }
}

This code is based on the flash display list. If we were blitting, or using stage3d, it would be different, but the principles would be the same. We need the image to be rendered, and the position and rotation for rendering it. And the render function does the rendering.

Using a base class and inheritance

In fact, there’s nothing in this code that makes it unique to a spaceship. All the code could be shared by all renderable objects. The only thing that makes them different is which display object is assigned to the view property, and what the position and rotation are. So lets wrap this in a base class and use inheritance.

class Renderable implements IRenderable
{
  public var view:DisplayObject;
  public var position:Point;
  public var rotation:Number;

  public function render():void
  {
    view.x = position.x;
    view.y = position.y;
    view.rotation = rotation;
  }
}

class Spaceship extends Renderable
{
}

Of course, all renderable items will extend the renderable class, so we get a simple class heirarchy like this

The move process

To understand the next step, we first need to look at another process and the class it works on. So lets try the move process, which updates the position of the objects.

interface IMoveable
{
  function move( time:Number );
}

class MoveProcess implements IProcess
{
  private var targets:Vector.<IMoveable>;
  
  public function start():Boolean
  {
    return true;
  }

  public function update( time:Number ):void
  {
    for each( var target:IMoveable in targets )
    {
      target.move( time );
    }
  }
  
  public function end():void
  {
  }
}

class Moveable implements IMoveable
{
  public var position:Point;
  public var rotation:Number;
  public var velocity:Point;
  public var angularVelocity:Number;

  public function move( time:Number ):void
  {
    position.x += velocity.x * time;
    position.y += velocity.y * time;
    rotation += angularVelocity * time;
  }
}

class Spaceship extends Moveable
{
}

Multiple inheritance

That’s almost good, but unfortunately we want our spaceship to be both moveable and renderable, and many modern programming languages don’t allow multiple inheritance.

Even in those languages that do permit multiple inheritance, we have the problem that the position and rotation in the Moveable class should be the same as the position and rotation in the Renderable class.

One common solution is to use an inheritance chain, so that Moveable extends Renderable.

class Moveable extends Renderable implements IMoveable
{
  public var velocity:Point;
  public var angularVelocity:Number;

  public function move( time:Number ):void
  {
    position.x += velocity.x * time;
    position.y += velocity.y * time;
    rotation += angularVelocity * time;
  }
}

class Spaceship extends Moveable
{
}

Now the spaceship is both moveable and renderable. We can apply the same principles to the other game objects to get this class hierarchy.

We can even have static objects that just extend Renderable.

Moveable but not Renderable

But what if we want a Moveable object that isn’t Renderable? An invisible game object, for example? Now our class hierarchy breaks down and we need an alternative implementation of the Moveable interface that doesn’t extend Renderable.

class InvisibleMoveable implements IMoveable
{
  public var position:Point;
  public var rotation:Number;
  public var velocity:Point;
  public var angularVelocity:Number;

  public function move( time:Number ):void
  {
    position.x += velocity.x * time;
    position.y += velocity.y * time;
    rotation += angularVelocity * time;
  }
}

In a simple game, this is clumsy but manageable, but in a complex game using inheritance to apply the processes to objects rapidly becomes unmanageable as you’ll soon discover items in your game that don’t fit into a simple linear inheritance tree, as with the force-field above.

Favour composition over inheritance

It’s long been a sound principle of object-oriented programming to favour composition over inheritance. Applying that principle here can rescue us from this potential inheritance mess.

We’ll still need Renderable and Moveable classes, but rather than extending these classes to create the spaceship class, we will create a spaceship class that contains an instance of each of these classes.

class Renderable implements IRenderable
{
  public var view:DisplayObject;
  public var position:Point;
  public var rotation:Number;

  public function render():void
  {
    view.x = position.x;
    view.y = position.y;
    view.rotation = rotation;
  }
}

class Moveable implements IMoveable
{
  public var position:Point;
  public var rotation:Number;
  public var velocity:Point;
  public var angularVelocity:Number;

  public function move( time:Number ):void
  {
    position.x += velocity.x * time;
    position.y += velocity.y * time;
    rotation += angularVelocity * time;
  }
}

class Spaceship
{
  public var renderData:IRenderable;
  public var moveData:IMoveable;
}

This way, we can combine the various behaviours in any way we like without running into inheritance problems.

The objects made by this composition, the Static Object, Spaceship, Flying Saucer, Asteroid, Bullet and Force Field, are collectively called entities.

Our processes remain unchanged.

interface IRenderable
{
  function render();
}

class RenderProcess implements IProcess
{
  private var targets:Vector.<IRenderable>;

  public function update(time:Number):void
  {
    for each(var target:IRenderable in targets)
    {
      target.render();
    }
  }
}

interface IMoveable
{
  function move();
}

class MoveProcess implements IProcess
{
  private var targets:Vector.<IMoveable>;

  public function update(time:Number):void
  {
    for each(var target:IMoveable in targets)
    {
      target.move( time );
    }
  }
}

But we don’t add the spaceship entity to each process, we add it’s components. So when we create the spaceship we do something like this

public function createSpaceship():Spaceship
{
  var spaceship:Spaceship = new Spaceship();
  ...
  renderProcess.addItem( spaceship.renderData );
  moveProcess.addItem( spaceship.moveData );
  ...
  return spaceship;
}

This approach looks good. It gives us the freedom to mix and match process support between different game objects without getting into spagetti inheritance chains or repeating ourselves. But there’s one problem.

What about the shared data?

The position and rotation properties in the Renderable class instance need to have the same values as the position and rotation properties in the Moveable class instance, since the Move process will change the values in the Moveable instance and the Render process will use the values in the Renderable instance.

class Renderable implements IRenderable
{
  public var view:DisplayObject;
  public var position:Point;
  public var rotation:Number;

  public function render():void
  {
    view.x = position.x;
    view.y = position.y;
    view.rotation = rotation;
  }
}

class Moveable implements IMoveable
{
  public var position:Point;
  public var rotation:Number;
  public var velocity:Point;
  public var angularVelocity:Number;

  public function move( time:Number ):void
  {
    position.x += velocity.x * time;
    position.y += velocity.y * time;
    rotation += angularVelocity * time;
  }
}

class Spaceship
{
  public var renderData:IRenderable;
  public var moveData:IMoveable;
}

To solve this, we need to ensure that both class instances reference the same instances of these properties. In Actionscript that means these properties must be objects, because objects can be passed by reference while primitives are passed by value.

So we introduce another set of classes, which we’ll call components. These components are just value objects that wrap properties into objects for sharing between processes.

class PositionComponent
{
  public var x:Number;
  public var y:Number;
  public var rotation:Number;
}

class VelocityComponent
{
  public var velocityX:Number;
  public var velocityY:Number;
  public var angularVelocity:Number;
}

class DisplayComponent
{
  public var view:DisplayObject;
}

class Renderable implements IRenderable
{
  public var display:DisplayComponent;
  public var position:PositionComponent;

  public function render():void
  {
    display.view.x = position.x;
    display.view.y = position.y;
    display.view.rotation = position.rotation;
  }
}

class Moveable implements IMoveable
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;

  public function move( time:Number ):void
  {
    position.x += velocity.velocityX * time;
    position.y += velocity.velocityY * time;
    position.rotation += velocity.angularVelocity * time;
  }
}

When we create the spaceship we ensure the Moveable and Renderable instances share the same instance of the PositionComponent.

class Spaceship
{
  public function Spaceship()
  {
    moveData = new Moveable();
    renderData = new Renderable();
    moveData.position = new PositionComponent();
    moveData.velocity = new VelocityComponent();
    renderData.position = moveData.position;
    renderData.display = new DisplayComponent();
  }
}

The processes remain unaffected by this change.

A good place to pause

At this point we have a neat separation of tasks. The game loop cycles through the processes, calling the update method on each one. Each process contains a collection of objects that implement the interface it operates on, and will call the appropriate method of those objects. Those objects each do a single important task on their data. Through the system of components, those objects are able to share data and thus the combination of multiple processes can produce complex updates in the game entities, while keeping each process relatively simple.

This architecture is similar to a number of entity systems in game development. The architecture follows good object-oriented principles and it works. But there’s more to come, starting with a moment of madness.

Abandoning good object-oriented practice

The current architecture uses good object-oriented practices like encapsulation and single responsibility – the IRenderable and IMoveable implementations encapsulate the data and logic for single responsibilities in the updating of game entities every frame – and composition – the Spaceship entity is created by combining implementations of the IRenderable and IMoveable interfaces. Through the system of components we ensured that, where appropriate, data is shared between the different data classes of the entities.

The next step in this evolution of entity systems is somewhat counter-intuitive, breaking one of the core tenets of object-oriented programming. We break the encapsulation of the data and logic in the Renderable and Moveable implementations. Specifically, we remove the logic from these classes and place it in the processes instead.

So this

interface IRenderable
{
  function render();
}

class Renderable implements IRenderable
{
  public var display:DisplayComponent;
  public var position:PositionComponent;

  public function render():void
  {
    display.view.x = position.x;
    display.view.y = position.y;
    display.view.rotation = position.rotation;
  }
}

class RenderProcess implements IProcess
{
  private var targets:Vector.<IRenderable>;

  public function update( time:Number ):void
  {
    for each( var target:IRenderable in targets )
    {
      target.render();
    }
  }
}

Becomes this

class RenderData
{
  public var display:DisplayComponent;
  public var position:PositionComponent;
}

class RenderProcess implements IProcess
{
  private var targets:Vector.<RenderData>;

  public function update( time:Number ):void
  {
    for each( var target:RenderData in targets )
    {
      target.display.view.x = target.position.x;
      target.display.view.y = target.position.y;
      target.display.view.rotation = target.position.rotation;
    }
  }
}

And this

interface IMoveable
{
  function move( time:Number );
}

class Moveable implements IMoveable
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;

  public function move( time:Number ):void
  {
    position.x += velocity.velocityX * time;
    position.y += velocity.velocityY * time;
    position.rotation += velocity.angularVelocity * time;
  }
}

class MoveProcess implements IProcess
{
  private var targets:Vector.<IMoveable>;

  public function move( time:Number ):void
  {
    for each( var target:Moveable in targets )
    {
      target.move( time );
    }
  }
}

Becomes this

class MoveData
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;
}

class MoveProcess implements IProcess
{
  private var targets:Vector.<MoveData>;

  public function move( time:Number ):void
  {
    for each( var target:MoveData in targets )
    {
      target.position.x += target.velocity.velocityX * time;
      target.position.y += target.velocity.velocityY * time;
      target.position.rotation += target.velocity.angularVelocity * time;
    }
  }
}

It’s not immediately clear why we’d do this, but bear with me. On the surface, we’ve removed the need for the interface, and we’ve given the process something more important to do – rather than simply delegate its work to the IRenderable or IMoveable implementations, it does the work itself.

The first apparent consequence of this is that all entities must use the same rendering method, since the render code is now in the RenderProcess. But that’s not actually the case. We could, for example, have two processes, RenderMovieClip and RenderBitmap for example, and they could operate on different sets of entities. So we haven’t lost any flexibility.

What we gain is the ability to refactor our entities significantly to produce an architecture with clearer separation and simpler configuration. The refactoring starts with a question.

Do we need the data classes?

Currently, our entity

class Spaceship
{
  public var moveData:MoveData;
  public var renderData:RenderData;
}

Contains two data classes

class MoveData
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;
}

class RenderData
{
  public var display:DisplayComponent;
  public var position:PositionComponent;
}

These data classes in turn contain three components

class PositionComponent
{
  public var x:Number;
  public var y:Number;
  public var rotation:Number;
}

class VelocityComponent
{
  public var velocityX:Number;
  public var velocityY:Number;
  public var angularVelocity:Number;
}

class DisplayComponent
{
  public var view:DisplayObject;
}

And the data classes are used by the two processes

class MoveProcess implements IProcess
{
  private var targets:Vector.<MoveData>;

  public function move( time:Number ):void
  {
    for each( var target:MoveData in targets )
    {
      target.position.x += target.velocity.velocityX * time;
      target.position.y += target.velocity.velocityY * time;
      target.position.rotation += target.velocity.angularVelocity * time;
    }
  }
}

class RenderProcess implements IProcess
{
  private var targets:Vector.<RenderData>;

  public function update( time:Number ):void
  {
    for each( var target:RenderData in targets )
    {
      target.display.view.x = target.position.x;
      target.display.view.y = target.position.y;
      target.display.view.rotation = target.position.rotation;
    }
  }
}

But the entity shouldn’t care about the data classes. The components collectively contain the state of the entity. The data classes exist for the convenience of the processes. So we refactor the code so the spaceship entity contains the components rather than the data classes.

class Spaceship
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;
  public var display:DisplayComponent;
}

class PositionComponent
{
  public var x:Number;
  public var y:Number;
  public var rotation:Number;
}

class VelocityComponent
{
  public var velocityX:Number;
  public var velocityY:Number;
  public var angularVelocity:Number;
}

class DisplayComponent
{
  public var view:DisplayObject;
}

By removing the data classes, and using the constituent components instead to define the spaceship, we have removed any need for the spaceship entity to know what processes may act on it. The spaceship now contains the components that define its state. Any requirement to combine these components into other data classes for the processes is some other class’s responsibility.

Systems and Nodes

Some core code within the entity system framework (which we’ll get to in a minute) will dynamically create these data objects as they are required by the processes. In this reduced context, the data classes will be mere nodes in the collections (arrays, linked-lists, or otherwise, depending on the implementation) used by the processes. So to clarify this we’ll rename them as nodes.

class MoveNode
{
  public var position:PositionComponent;
  public var velocity:VelocityComponent;
}

class RenderNode
{
  public var display:DisplayComponent;
  public var position:PositionComponent;
}

The processes are unchanged, but in keeping with the more common naming I’ll also change their name and call them systems.

class MoveSystem implements ISystem
{
  private var targets:Vector.<MoveNode>;

  public function update( time:Number ):void
  {
    for each( var target:MoveNode in targets )
    {
      target.position.x += target.velocity.velocityX * time;
      target.position.y += target.velocity.velocityY * time;
      target.position.rotation += target.velocity.angularVelocity * time;
    }
  }
}

class RenderSystem implements ISystem
{
  private var targets:Vector.<RenderNode>;

  public function update( time:Number ):void
  {
    for each( var target:RenderNode in targets )
    {
      target.display.view.x = target.position.x;
      target.display.view.y = target.position.y;
      target.display.view.rotation = target.position.rotation;
    }
  }
}

interface ISystem
{
  function update( time:Number ):void;
}

And what is an entity?

One last change – there’s nothing special about the Spaceship class. It’s just a container for components. So we’ll just call it Entity and give it a collection of components. We’ll access those components based on their class type.

class Entity
{
  private var components : Dictionary;
  
  public function add( component:Object ):void
  {
    var componentClass : Class = component.constructor;
    components[ componentClass ] = component'
  }
  
  public function remove( componentClass:Class ):void
  {
    delete components[ componentClass ];
  }
  
  public function get( componentClass:Class ):Object
  {
    return components[ componentClass ];
  }
}

So we’ll create our spaceship like this

public function createSpaceship():void
{
  var spaceship:Entity = new Entity();
  var position:PositionComponent = new PositionComponent();
  position.x = Stage.stageWidth / 2;
  position.y = Stage.stageHeight / 2;
  position.rotation = 0;
  spaceship.add( position );
  var display:DisplayComponent = new DisplayComponent();
  display.view = new SpaceshipImage();
  spaceship.add( display );
  engine.add( spaceship );
}

The core Engine class

We mustn’t forget the system manager, formerly called the process manager.

class SystemManager
{
  private var systems:PrioritisedList;

  public function addSystem( system:ISystem, priority:int ):void
  {
    systems.add( system, priority );
    system.start();
  }

  public function update( time:Number ):void
  {
    for each( var system:ISystem in systemes )
    {
      system.update( time );
    }
  }

  public function removeSystem( system:ISystem ):void
  {
    system.end();
    systems.remove( system );
  }
}

This will be enhanced and will sit at the heart of our entity system framework. We’ll add to it the functionality mentioned above to dynamically create nodes for the systems.

The entities only care about components, and the systems only care about nodes. So to complete the entity system framework, we need code to watch the entities and, as they change, add and remove their components to the node collections used by the systems. Because this is the one bit of code that knows about both entities and systems, we might consider it central to the game. In Ash, I call this the Engine class, and it is an enhanced version of the system manager.

Every entity and every system is added to and removed from the Engine class when you start using it and stop using it. The Engine class keeps track of the components on the entities and creates and destroys nodes as necessary, adding those nodes to the node collections. The Engine class also provides a way for the systems to get the collections they require.

public class Engine
{
  private var entities:EntityList;
  private var systems:SystemList;
  private var nodeLists:Dictionary;

  public function addEntity( entity:Entity ):void
  {
    entities.add( entity );
    // create nodes from this entity's components and add them to node lists
    // also watch for later addition and removal of components from the entity so
    // you can adjust its derived nodes accordingly
  }

  public function removeEntity( entity:Entity ):void
  {
    // destroy nodes containing this entity's components
    // and remove them from the node lists
    entities.remove( entity );
  }

  public function addSystem( system:System, priority:int ):void
  {
    systems.add( system, priority );
    system.start();
  }

  public function removeSystem( system:System ):void
  {
    system.end();
    systems.remove( system );
  }

  public function getNodeList( nodeClass:Class ):NodeList
  {
    var nodes:NodeList = new NodeList();
    nodeLists[ nodeClass ] = nodes;
    // create the nodes from the current set of entities
    // and populate the node list
    return nodes;
  }

  public function update( time:Number ):void
  {
    for each( var system:ISystem in systemes )
    {
      system.update( time );
    }
  }
}

To see one implementation of this architecture, checkout the Ash entity system framework, and see the example Asteroids implementation there too.

Conclusion

So, to summarise, entity systems originate from a desire to simplify the game loop. From that comes an architecture of entities, which represent the state of the game, and systems, which operate on the state of the game. Systems are updated every frame – this is the game loop. Entities are made up of components, and systems operate on the entities that have the components they are interested in. The engine monitors the systems and the entities and ensures each system has access to a collection of all the entities that have the appropriate components.

However, systems don’t generally care about the entity as a whole, just the specific components they require. So, to optimise the architecture and provide additional clarity, the systems operate on statically typed node objects that contain the appropriate components, where those components all belong to the same entity.

An entity system framework provides the basic scaffolding and core management for this architecture, without providing any actual entity or system classes. You create your game by creating the appropriate entities and systems.

An entity based game engine will provide many standard systems and entities on top of the basic framework.

Three entity system frameworks for Actionscript are my own Ash, Ember2 by Tom Davies and Xember by Alec McEachran. Artemis is an entity system framework for Java, that has also been ported to C#.

My next post covers some of the reasons why I like using an entity system framework for my game development projects.

Stick Sports

I am CTO at Stick Sports where I am involved in the development of these apps.

Stick Tennis

Free

Easy to play yet difficult to master, Stick Tennis – the number one sports game in 102 countries – offers fast and fluid gameplay with realistic court surfaces and a huge range of unique player styles and characteristics.

With just a simple one-fingered swipe you’ll soon be thumping crosscourt winners, yet at the core of Stick Tennis is a highly sophisticated physics engine that rewards tactical play.

Stick Cricket

Free

Chart-topping… Award-winning… GDP-reducing… Need we say more? Stick Cricket, the world’s most popular cricket game, is available for iOS and Android. Whether you’re on the job or ‘on the john’, you can still hit out or get out!

Stick Cricket Super Sixes

Free

It’s man vs machine in the ultimate test of your cricket skills! Instead of facing mere mortals, your opponent is the state-of-the-art Bowlomatic 3000: a sadistic bowling machine that is hell bent on wiping you out.

Smash as many boundaries as you can but be wary, as the Bowlomatic 3000 has plenty of tricks up his sleeve to ensure a harrowing time at the crease.

But now I’ve written an entity system framework of my own. It’s called Ash and you can find it on Github.

A few of the features of Ash are

• Uses the most performant linked list format from my tests here.
• Optional, but not required, integration with SwiftSuspenders and Robotlegs.
• The process manager is a core part of the framework.

I plan to build a game with Ash, so more features will come as I need them, and more posts on this blog. Meanwhile, if you’re building an actionscript game why not take Ash for a spin. And for comparison, check out Ember2 and Xember.

Tom in particular has done a lot of work to develop the ideas behind entity systems on the Flash platform. Without that work to feed my ideas machine I wouldn’t have built Ash, so thank you Tom.

And thank you to Till who added a feature to SwiftSuspenders to enable me to inject linked lists based on their content type.

Update

Here is a follow-up post explaining entity system frameworks and a further post explaining some of the reasons why I like using an entity system framework for my game development projects.

Update 2

Ash now has a website, at www.ashframework.org.