I’ve ported Cassio Souza’s ActionScript 3 State Machine to a Lua State Machine, and recently a Dart version, and included examples. This article has a companion video embedded below.

What Are State Machines

At their simplest form, State Machines are an Observer pattern with 2 values they watch internally: an Entity and the Current State. Whenever someone, somewhere changes the internal state, it’ll let the world know.

The high level parts are:

1. States which contain/define the behavior for the Entity
2. Transitions which occur when one State changes to another
3. Rules which define which States can change to certain other States
4. Events which are internally or externally dispatched which trigger State Transitions

When creating State Machines, you usually know all the states up front, hence the word finite. Whether a list on paper or a bunch of boxes on a flow chart with arrows denoting where you can go from where. Some states can have parent child relationships. There can be a variety of rules that allow/prevent some states from changing to others can causing state transitions.

Why Use State Machines

There are 3 use cases State Machines. These are Artificial Intelligence, modeling simulations, and a refactoring path for game entities.

For AI programming, you have the choice of deterministic or non-deterministic. Most video games have deterministic; meaning you know how the enemies will react based on different inputs. If they don’t see you, they’ll patrol. If they see you, they’ll attack you. If you hide and wait, they’ll eventually go back to patrolling. You can simulate fuzzy logic by using random numbers to change state to something random. For example, sometimes the enemy could use a grenade vs. a gun, or attack you immediately vs. sounding the alarm… or even run away to get reinforcements. Sometimes they could even talk to you instead. This randomness makes a State Machine non-deterministic, meaning you know all the States, but you don’t know exactly all the paths between States.

For modeling simulations, whether complex machinery, or situations, you often have a ton of moving parts. You’re interested in the potential interactions when certain things are in certain states. Sometimes you want these situations to be repeatable.

For example, for simulating hardware of large steel manufacturing machinery for training purposes, you want to setup the machine either in a specific state, or towards one to teach a new operator how to handle a certain negative situation in a safe environment to learn. You start a predefined set of actions to get the machine in a state where something bad is about to happen, and the operator has to learn how to push the right buttons or turn the right knobs to stop things from going bad.

You can do the same at a macro level for emulating events. Think SimCity.

This is also why unit testing deterministic state machines is pretty easy, albeit not as fun as non-deterministic, because you know all the paths ahead of time and the potential interactions.

For the purpose of this article, we’re concerned with refactoring paths for game entities. Specifically, “dude, this code is too complex to manage and there are 50 billion boolean flags/if then statements to deal with…”. Using State Machines makes your code more manageable as it grows, more organized, and easier to debug.

Behavior in a Class vs. Behavior in States

Alan Skorkin has a great article on why developers often don’t use state machines. While he’s referring to software development as a whole, not just game development, he brings up a lot of valid points. Specifically, YAGNI, or if you don’t know ahead of time you’ll have a lot of behavior, you start out building only what you need. The issue becomes down the line, the effort towards refactoring it to a proper state machine is a lot of work.

I experienced this from 2 angles. The first is what got me interested in state machines in the first place. My game entities were getting uber complex, and I asked around for advice. Colleagues recommended Finite State Machines to solve all my problems. During the refactoring, I started to learn why they’re great for lots of behavior in known states.

I then tried implementing one in a brand new code base with only a little behavior… and it was overly complex. Then I reached this mid-point where the complexity was hard to manage, but I didn’t want to go back to a State Machine again.

So I’ve had a frustrating experience and an extremely positive one.

You can see a before and after example of how State Machines can really make your game entity classes smaller and more manageable as their behavior grows.

Example 1: Simple State – Event Handler

Let’s show a simple 1942 ‘esque example in Lua. You have an overhead view of an airplane that has 3 firing modes: a single bullet, faster dual-bullets, and a 3 pronged super-fast bullet mode.

From our state flow chart below, you can see we have 3 states, with Fire 1 being the initial state. The events between states are when the plane touches a power up. If the plane hits an enemy, they’ll go back a state, from Fire 3 to Fire 2 and from Fire 2 to Fire 1.

Now let’s setup our State Machine:

fireFSM = StateMachine:new()
fireFSM:addState("fire1", {from="*"})
fireFSM:addState("fire2", {from="*"})
fireFSM:addState("fire3", {from="*"})
fireFSM:setInitialState("fire3")
fireFSM:addEventListener("onStateMachineStateChanged", onChangePlayerFireFunction)

Whenever anyone changes the fireFSM, it’ll dispatch the “onStateMachineStateChanged” event. We can then set the Entity’s proper fire function as well as the speed at which it should fire at in milliseconds.

function onChangePlayerFireFunction(event)
   local fireFunkyFunk
   local state = fireFSM.state
   local fireSpeed
   if state == "fire1" then
      fireFunkyFunk = player.fire1
      fireSpeed = 300
   elseif state == "fire2" then
      fireFunkyFunk = player.fire2
      fireSpeed = 200
   elseif state == "fire3" then
      fireFunkyFunk = player.fire3
      fireSpeed = 150
   end
   player.fire = fireFunkyFunk
   player.FIRE_TIME = fireSpeed
end

Notice we inspect what the new state is at line 69. From there it’s just a simple switch statement to determine which firing mode to switch to. Notice we actually set the data on the Entity itself, in this case “player”. The player then uses this data in his game tick (slang for a function that fires when the Game Loop decides it’s time for your game object to do something). Like so:

function player:tick(millisecondsPassed)
   if self.firing == true then
      self.startFireTime = self.startFireTime + millisecondsPassed
      if self.startFireTime >= self.FIRE_TIME then
         self.startFireTime = 0
         self:fire()
      end
   end

Notice line 144. The player/plane doesn’t know what fire actually is, it just executes it every time it’s allowed to fire. If you change it to a different fire function, it’ll use that one. Let’s take a look at those. Here’s fire1, which fires a single bullet every 300 milliseconds:

function player:fire1()
   local bullet = getBasicBullet("player_bullet_1.png", self.x + self.width / 2, self.y)
end

In game, it’ll look like this:

If we press the Fire 2 button (which simulates getting a power up), it’ll change the Entity’s fire reference to the fire2 function:

function player:fire2()
   local bullet = getBasicBullet("player_bullet_2.png", self.x, self.y)
   bullet.x = bullet.x + bullet.width / 2
end

The only difference here is a different image which is larger, and we center it on the player.

Finally, if we hit the Fire 3 button, it’ll change it to the fire3 function.

function player:fire3()
   local bullet1 = getBasicBullet("player_bullet_1.png", self.x, self.y)
   bullet1.rotation = -45
   bullet1.rot = math.atan2(bullet1.y -  -800,  bullet1.x - -800) / math.pi * 180 -90;
   bullet1.angle = (bullet1.rot -90) * math.pi / 180;

   local bullet2 = getBasicBullet("player_bullet_1.png", self.x, self.y)
   bullet2.rotation = 45
   bullet2.rot = math.atan2(bullet2.y -  -800,  bullet2.x - -800) / math.pi * 180 -90;
   bullet2.angle = (bullet2.rot) * math.pi / 180;
   
   -- override the functions with these instead
   function bullet1:tick(millisecondsPassed)
      self.x = self.x + math.cos(self.angle) * self.speed * millisecondsPassed
         self.y = self.y + math.sin(self.angle) * self.speed * millisecondsPassed
   end
   
   function bullet2:tick(millisecondsPassed)
      self.x = self.x + math.cos(self.angle) * self.speed * millisecondsPassed
         self.y = self.y + math.sin(self.angle) * self.speed * millisecondsPassed
   end

   local bullet3 = getBasicBullet("player_bullet_1.png", self.x + self.width / 2, self.y)
end

Which looks like:

Again, the sequence of events for hitting the Fire 2 button are:

1. fireFSM:setInitialState(“fire1”) puts the State Machine in the initial fire 1 state.
2. When you press the Fire 2 button, it’ll call fireFSM:changeState(“fire2”)
3. The State Machine internally will dispatch the change event “onStateMachineStateChanged”
4. In our event handler for it, we’ll inspect what the new state is, and assign the appropriate fire function.

Example 1: Simple State – Event Handlers

While using a change event is simple and results in 1 function, what if you have a lot of states? This is where using enter/exit handlers helps you organize your code more and it scales better. Taking our exact same example above, instead of using our onChangePlayerFireFunction to listen for the State Machine’s “onStateMachineStateChanged” event:

fireFSM:addEventListener("onStateMachineStateChanged", onChangePlayerFireFunction)

We’ll instead use an enter handler instead, like so:

fireFSM:addState("fire1", {from="*", enter=onEnterStateFire1})
fireFSM:addState("fire2", {from="*", enter=onEnterStateFire2})
fireFSM:addState("fire3", {from="*", enter=onEnterStateFire3})

Now, this results in 3 organized functions that are a lot smaller and easier to read. It’s also obvious what they do based on the naming convention:

function onEnterStateFire1(event)
   player.fire = player.fire1
   player.FIRE_TIME = 300
end

function onEnterStateFire2(event)
   player.fire = player.fire2
   player.FIRE_TIME = 200
end

function onEnterStateFire3(event)
   player.fire = player.fire3
   player.FIRE_TIME = 150
end

Example 2: Hierarchical State Machine

There are a variety of benefits using a hierarchical State Machine; a State Machine where States have parent child relationships.

First, it helps DRY your code. There are a lot of things some states have in common so you can run that initialization code once. Same goes for destroy/clean up code.

Secondly, it helps you organize your code; ie “Attacking code goes in this section whereas Defending code goes over here”.

Third, a State Machine can help you enforce paths to go from child to parent to sibling to child. Just like in Starcraft, a Siege Tank must first transform to assault mode from the siege mode before it can actually move and fire again.

The State Machine will throw errors if you attempt to move to an illegal path which helps you correct your code. It will also showcase missing transitions if you forgot one. Why are paths important? Just like we can’t go from Siege Mode to Move Mode using a Starcraft Siege tank, we don’t want our War Robot in Example 2 going from Artillery Mode to Move Mode. There is some time it takes to get setup for long range artillery strikes, as well as getting out of artillery mode. Our example does NOT enforce this but gives you the mechanisms to do so to ensure the player cannot do anything whilst transitioning from one State to the next.

Here’s the flow chart for Example 2, where our War Robot can be an upright walking robot for recon, a defense mode for holding up shields to protect itself, and an assault mode with 3 firing modes: laser sight, sniper, and artillery (click for larger version).

We’ll set up our State Machine much like before in Example 1, except here we’ll use a new parameter called “parent” like so:

botFSM:addState("scout", {from={"defend", "assault"}, enter=onEnterScout})
botFSM:addState("scoutLeft", {parent="scout", from="scoutRight", enter=onEnterScoutLeft, exit=onExitScoutLeft})
botFSM:addState("scoutRight", {parent="scout", from="scoutLeft", enter=onEnterScoutRight, exit=onExitScoutRight})

botFSM:addState("defend", {from={"scout", "assault"}, enter=onEnterDefendState, exit=onExitDefendState})

botFSM:addState("assault", {from={"scout", "defend"}, enter=onEnterAssaultState, exit=onExitAsstaultState})
botFSM:addState("assaultLeft", {parent="assault", from="assaultRight", enter=onEnterAssaultLeft, exit=onExitAssaultLeft})
botFSM:addState("assaultRight", {parent="assault", from="assaultLeft", enter=onEnterAssaultRight, exit=onExitAssaultRight})
botFSM:addState("sight", {parent="assault", from={"sniper", "artillery"}, enter=onEnterSightState, exit=onExitSightState})
botFSM:addState("sniper", {parent="assault", from={"sight", "artillery"}, enter=onEnterSniperState, exit=onExitSniperState})
botFSM:addState("artillery", {parent="assault", from={"sniper", "sight"}, enter=onEnterArtilleryState, exit=onExitArtilleryState})

botFSM:setInitialState("scout")

Notice our 3 main States (Scout, Defend, and Assault) clearly define which states they are allowed to be transitioned to via the from parameter. Also notice some special things about the parent parameter. The “scoutLeft” State, a child of “scout”, does not have to define its parent in the from parameter. It’s implied in the State Machine that a child state is allowed to be transitioned to by its parent. Finally, notice the use of exit to define exit handlers.

All this setup defines our states, their children, and who’s allowed to transition to whom. All of this matches our flow chart.

Our Entity, the WarBot class, is handling all the actual animations and storing the data and handling how the behavior works. What behavior it does, and when, is controlled by the State enter and exit functions. The how is affected by its internal variables, also changed by the State changes.

Let’s take a look at what happens when you enter the parent “scout” State by pressing the “Scout” button:

function onEnterScout()
   warBot:showSprite("scout")
   warBot:setSpeed(4)
end

It shows the scout sprite sheet and sets the speed to 4. If you press the “Scout Right” button, it’ll botFSM:changeState(“scountRight”) and call:

function onEnterScoutRight()
   warBot:showSprite("scoutRight")
   warBot:setDirection("right")
   warBot:startMoving()
end

This shows the scoutRight sprite sheet which is an animation of the robot running right. It also ensures it is facing the right direction and informs it needs to start animating. If you let go/stop touching the “Scout Right” button, it’ll go back to the parent “scout” state.

function onExitScoutRight()
   warBot:showSprite("scout")
   warBot:stopMoving()
end

Notice that this does NOT fire an onExitScout function; you’re still technically in the scout state since scoutLeft and scoutRight are its children. It looks like so:

Let’s take a look at the Defense State. He’s unique in that he doesn’t care where you came from; as soon as you let go of the Defend button, it’ll go to whatever the previousState was. Also of note, he’ll set some initial defense and speed variables (speed to 0 because you can’t move while in Defend State):

function onEnterDefendState()
   warBot:showSprite("defend")
   warBot:setDefense(10)
   warBot:setSpeed(0)
end

Notice we didn’t define an onExitDefendState. It’s assumed whatever State you’re going to will handle setting the speed & defense to the appropriate values.

Finally, we’re offloading a lot of the actual details of firing bullets, laser sights, etc. onto the Entity. Notice how all 3 of the Assault’s child modes tell the Entity to start or stop showing these effects. The benefit is you don’t have to worry about checking boolean flags before you run them; you can be sure the State Machine will only start and stop each one at the appropriate time. … Usually, heh.

Here’s Sniper mode’s enter and exit:

function onEnterSniperState()
   warBot:showSprite("sniper")
   warBot:setSpeed(0)
   warBot:startSniperShooting()
end

function onExitSniperState()
   warBot:showSprite("sniperReverse")
   warBot:stopSniperShooting()
end

Standard stuff here; show the correct sprite sheet, set the speed to 0 when you enter, and telling the entity to start handling touch events as sniper shots. When it exits, it shows the revert animation, and stops handling touch events as sniper shots.

State Changes Observer & Path Enforcement

Remember, the State Machine will both enforce the state paths you put in from as well as dispatch an event. Since it’s an observer, others can listen to these State changes as well. The ButtonsController we have listens to the state changes and only shows the appropriate buttons that mach our flow chart rules.

We give the ButtonsController a reference to the State Machine:

buttons:setStateMachine(botFSM)

He’ll then add an event listener to it and initialize himself to the current state:

function buttons:setStateMachine(fsm)
   if self.stateMachine then
      self.stateMachine:removeEventListener("onStateMachineStateChanged", self)
   end
   self.stateMachine = fsm
   if fsm then
      fsm:addEventListener("onStateMachineStateChanged", self)
   end
   self:onStateMachineStateChanged()
end

Now, instead of checking a bunch of rules to ensure they match our flow chart, we instead just only show the buttons you’re allowed to press in certain states:

function buttons:onStateMachineStateChanged(event)
   local state = self.stateMachine.state
   self:hideAllButtons()
   if state == "scout" or state == "scoutLeft" or state == "scoutRight" then
      self.walkLeftButton.isVisible = true
      self.walkRightButton.isVisible = true
      self.defendButton.isVisible = true
      self.attackButton.isVisible = true
   elseif state == "defend" then
      self.defendButton.isVisible = true
   elseif state == "assault" then
      self.rollLeftButton.isVisible = true
      self.rollRightButton.isVisible = true
      self.defendButton.isVisible = true
      self.scoutButton.isVisible = true
      self.sightButton.isVisible = true
      self.sniperButton.isVisible = true
      self.artilleryButton.isVisible = true
   elseif state == "assaultLeft" or state == "assaultRight" then
      self.rollLeftButton.isVisible = true
      self.rollRightButton.isVisible = true
      self.scoutButton.isVisible = true
   elseif state == "sight" or state == "sniper" or state == "artillery" then
      self.attackButton.isVisible = true
   end
end

This makes your changing the State Machine really easy because you don’t have to put tests in there; you just react and change it to match the flow chart. Here’s how moveRight works; if you press the button, it sets it to moveRight, and when you let go, it goes back to scout:

function buttons:onMoveRight(event)
   if event.phase == "began" then
      self.stateMachine:changeState("scoutRight") 
   elseif event.phase == "ended" or event.phase == "cancelled" then
      self.stateMachine:changeState("scout") 
   end
end

Example 3: Class Based States

Last up is the class version of the State Machine examples. My version of Classes in Lua are just tables using closures for scope reasons.

The class approach has some advantages. First, as your code grows in size, it’s easier to scale. You can utilize inheritance and packages help keep it clean, organized, and DRY. This also makes code reuse slightly easier as well. In the first 2 examples, you can see how the actual behavior implementation is separate from the State Machine, in main.lua. It’s not really grouped together in any organized fashion.

The second advantage is, like the enter and exit functions, the class only handles that behavior in which it is responsible for. If you look in Example 2, you’ll notice the WarBot, although not determining his behavior, is still responsible for setting himself up internally for it. Using classes, you offload the majority of that code to the appropriate state responsible for it.

The third advantage is leveraging Corona’s event system. States can both react to events from the global event bus, Runtime, as well as dispatch their own in case other State Machines need to know about something. This allows a loose coupling for inter-State Machine communication.

Downsides are moar code which requires moar unit tests which in turn is moar code. This is moar complexity which can result in a lower iteration speed. Not always ideal for games. I like it, though, coming from an OOP background.

Let’s start with a really simple State Machine: a character that can move left, right, jump, and attack.

And here’s the flow chart with the State paths. Notice if the character sits still, he can rest. That’s it (click for larger image).

Setting up the State Machine is only slightly different; you use addState2, and put a class instance inside it, like so:

fsm:addState2(ReadyState:new())
fsm:addState2(RestingState:new())
fsm:addState2(MovingRightState:new())
fsm:addState2(MovingLeftState:new())
fsm:addState2(JumpLeftState:new())
fsm:addState2(JumpRightState:new())
fsm:addState2(AttackState:new())
fsm:setInitialState("ready")

gameLoop:addLoop(fsm)

Also note I added it to the Game Loop. I default all States to have a tick method so they can tap into the global Game Loop as well.

Pay special note to the setInitialState; it takes a String name. I used a convention to keep the the API the same: ReadyState becomes “ready”, MovingRightState becomes “movingRight”, etc. All classes use their name in the constructor so the State Machine knows what their name is.

In a State class, you just import the base class, extend it, and pass in your name.

require "com.jessewarden.statemachine.BaseState"
ReadyState = {}

function ReadyState:new()
   local state = BaseState:new("ready")

From there, you can do whatever you wish. The standard methods to implement are onEnterState, onExitState, and tick. All State class have references to the Entity they are dealing with as well as the State Machine they are within as illustrated in the tick function getting local references to it:

function state:onEnterState(event)
end

function state:onExitState(event)
end

function state:tick(time)
   local player = self.entity
   local stateMachine = self.stateMachine
end

Let’s take a look at the ReadyState’s onEnterState function. He states the Entity is not recharging his stamina, resets the internal rest timer (since you have to sit still for 3 seconds to trigger a State transition to the RestingState), and listens for global events that can trigger other, valid State transitions.

function state:onEnterState(event)
   local player = self.entity
   self.recharge = false
   
   self:reset()
   
   player:showSprite("stand")
   
   Runtime:addEventListener("onMoveLeftStarted", self)
   Runtime:addEventListener("onMoveRightStarted", self)
   Runtime:addEventListener("onAttackStarted", self)
   Runtime:addEventListener("onJumpLeftStarted", self)
   Runtime:addEventListener("onJumpRightStarted", self)
end

That last part is the key. I don’t care where these events come from, I just know, if someone, somewhere says that onMoveLeftStarted, then this State class will react and say, “Ok, go ahead and change the state to the moveLeft state then.”:

function state:onMoveLeftStarted(event)
   self.stateMachine:changeStateToAtNextTick("movingLeft")
end

Notice here there are no rules enforcement. They’re entirely up to you in an opt-in way. If you do not handle, or allow a State transition here, none occurs. It’s up to your class to opt in and allow State transitions. Conversely, you can have someone else with a reference to the State Machine to actually change the states; up to you. The downside here is no help from the State Machine to see if your States actually match what’s in your flow chart. I’ve thought about adding a way to declaratively add them just like you did in Example 1 and 2.

The JumpLeftState shows the power of inheritance at work:

require "states.JumpState"

JumpLeftState = {}

function JumpLeftState:new()
   local state = JumpState:new("jumpLeft")
   
   state.superOnEnterState = state.onEnterState
   function state:onEnterState(event)
      self:superOnEnterState(event)
      
      local player = self.entity
      player:setDirection("left")
   end
   
   state.superOnExitState = state.onExitState
   function state:onExitState(event)
      local player = self.entity
      player:applyLinearImpulse(-player.jumpForwardForce / 3, 0, 40, 32)
      self:superOnExitState(event)
   end
   
   state.superTick = state.tick
   function state:tick(time)
      local player = self.entity
      player.x = player.x + -(player.jumpForwardForce)
      self:superTick(time)
   end
   
   return state
   
end

return JumpLeftState

He extends the base JumpState, allowing it to do most of the heavy lifting dealing with Box2D + Game Loop movement timing, etc. This State just sets the direction to the correct way. Notice too a rudimentary super method call to allow the base class to do it’s work first. I also extend the jump behavior by also moving the Entity in the right direction. I could let the base class do this, or the sub-class… up to you.

Be aware in all examples, the State classes have their onEnterState and onExitState methods called in the correct order, always. You do NOT have to implement them if you do not wish to. Finally, the most important thing to notice is the State classes use the changeStateToAtNextTick method for the State Machine class vs. changeState. The short reason for this is that it allows all the code in the current stack to run, including State machine class clean up, as well as avoiding common race conditions (if you’re a Flash Developer, think invalidation).

Real World Challenges

I wanted to show you some of the challenges I’ve had in the real world. While the design patterns’ rules are quite clear about “Entity’s holding the data, States implementing the behavior” sometimes it’s easier to let the Entity handle the details… especially with Box2D collisions.

An example of this is in my ZombieStick game where a Zombie grapples with the player. They get a reference to the player they grappled, add themselves as a grappler, and await the Player’s State Machine to resolve fighting off the zombie. Off-loading a lot of this code to the Entity makes them much cleaner classes, and results in less code since the Entity’s already extend a Corona DisplayObject. To pragmatists, sounds legit, to ivory tower purists, it’s pathetic… especially in a light weight and powerfully dynamic language like Lua.

This works out ok in that if a collision event fires from a Zombie, but if he’s in another state where he clearly can’t grapple the player (prone, stunned, dead), he just ignores the event. Sounds great at first, but Corona collision events are just that… events, once you miss them, they’re gone. Therefore, each State class has the burden of in its onEnterState to do some checking to see what it missed. This is basically the same problem PureMVC and Robotlegs Mediators solve in application development (data is ready, you’re not vs. you’re ready, data is not), so you can do the same here as well; you just have to ensure your Entity does a good job of exposing the variables you need to have your State boot up correctly.

For example, here’s the Zombie’s Box2D collision handler:

function zombie:collision(event)
   if self.dead == true then return true end
   if event.phase == "began" then
      if event.other.classType == "PlayerJXL" then
         if self.collisionTargets == nil then
            self.collisionTargets = {}
         end
         if table.indexOf(event.other) == nil then
            table.insert(self.collisionTargets, event.other)
         end
      end
   elseif event.phase == "ended" then
      if event.other.classType == "PlayerJXL" then
         table.remove(self.collisionTargets, table.indexOf(event.other))
         if self.targetPlayer ~= nil and event.other == self.targetPlayer then
            self:dispatchEvent({name="onTargetPlayerRemoved", target=self})
         end
      end
   end
end

All it basically does is manage an internal list of things it hit that are players. If the player moves away, great, it removes them. This allows the State classes to manage whether or not the Zombie should actually act on grappling a player not; ie the actual behavior. As soon as the State boots up, it checks this collisionTargets array in the onEnterSate function. Any time thereafter, it’ll get the proper events, thus avoiding race conditions. Additionally, the State classes can do it whenever they wish; ie whenever the State Machine moves to the IdleState, that’s the first thing he checks:

function state:handleCollisionTargets()
   local zombie = self.entity
   local targets = zombie.collisionTargets
   if targets ~= nil and #targets > 0 then
      local first = targets[1]
      zombie.targetPlayer = first
      self.stateMachine:changeStateToAtNextTick("grabPlayer")
   end
end

Again, following a common solution used in other languages and frameworks… but just 1 more thing for you to remember, and moar code. I agree with it, and you DO get in a groove, just something to be aware of.

The other thing I noticed is that 90% of the State Machine being changed to different States is handled in the State classes themselves. However, you get into these edge cases where you need someone ELSE to change it. The example I just gave, when the Zombie grapples onto the player, the Player needs to immediately react. Using the above example, it’d be better to just have the States that are capable of legally going to Grappled Defense State handling it, right? Well… no. If a Zombie grabs you, you drop what you’re doing and react… even if you’re in the middle of the air in a Jump State. Here’s a method in the Base Player class (the Entity itself) that does just that:

function player:addGrappler(dudeGrabbingMeUpInThisMug)
   -- TODO: need to ensure you can actually be grappled, need to check state. psuedo code below
   local currentState = self.fsm.state
   if currentState == "firehose" and currentState == "grapple" and currentState == "jump" and current == "jumpLeft" and currentState == "jumpRight" then
      error("Illlegal to grapple player when they're in state: ", currentState)
   end

   -- if you're grappled, you're slowed down
   local grapplers = self.grapplers
   if table.indexOf(grapplers, dudeGrabbingMeUpInThisMug) == nil then
      table.insert(grapplers, dudeGrabbingMeUpInThisMug)
      self:resolveSpeed()
      self.fsm:changeStateToAtNextTick("grappleDefense")
      return true
   else
      error("grappler already added to array")
   end
end

Yes, a code smell… further evidence that rules enforcement would mitigate this problem. So would a flow chart indicating what states a Zombie can actually grapple me in. Anyway, if you see things like this in your implementation, hopefully you now know how to solve or refactor them.

Conclusions

Again, the high level characteristics of a State Machine are:

• States which contain/define the behavior for the Entity
• Transitions which occur when one State changes to another
• Rules which define which States can change to certain other States
• Events which are internally or externally dispatched which trigger State Transitions

Using State Machines allows you to more easily scale and organize behavior code for your Game Entities, especially for AI development. The rules engine helps ensure your code matches your flowchart, and tells you at runtime if it does not (except for Classes… working on it). You can set the StateMachine’s new state anywhere, and he’ll both dispatch a change event as well as call your enter/exit functions for you. If you wish for it to utilize the global Event bus, I’ve included instructions inside of the class on how to enable this. For larger projects, the class based option helps your code scale for larger projects. All of the examples are included in the Github repo where you can download the code.

Further reading:

• Finite State Machines
• Cogs framework with presentation (scroll down)
• Johnathan Kaye’s ActionScript 3 State Engine
• Richard Lord’s “Finite State Machines for AI in ActionScript
• Why Developers Never Use State Machines

Also posted on iOS Gaming.

The following covers why you would utilize the Robotlegs MVC architecture in a lightweight, Lua game for Corona. I’ll discuss the refactoring reasoning, the common problems you run across in game architecture, and their solutions with their pro’s and con’s discussed. Finally, I conclude on how Robotlegs helps solve these common issues, specifically in a Lua & Corona context.

I’ve started the port of Robotlegs to Lua to work in Corona if you’re interested in learning more.

Refactor First

In learning Lua & Corona, I quickly ran into 2 problems with the game I’m working on. The main code controller became way too large to manage. It wasn’t quite a God object (yes, the anti-pattern) because a lot of the View’s themselves handled some of the necessary messaging & logic. Regardless, time to refactor.

The first thing was to start using classes. Lua doesn’t have classes. There are a bunch of resources out there that explain how to do them in various incarnations. I went with a version that Darren Osadchuk, creator of the Corona bundle for TextMate.

The second thing was to start using packages. Lua doesn’t have packages. There are various ways of implementing them which are all confusing as hell. The easiest way is to just put your code in a folder and use that path in the require function, but you can’t utilize folders for Android in the latest build of Corona at the time of this writing.

These are the low hanging fruit of re-factoring, and has made a huge difference in code readability & maintainability.

Burdens of Encapsulation

The downside of OOP is that it’s encapsulated. While making something a black box with internally managed state & implied reusability is good on the surface, it pushes the burden of managing communication between those encapsulated objects to someone ones.

You have 3 options: globals, messaging dependencies, or mediation.

Global Variables: The Good

Most people agree global variables are bad… in larger software development. In smaller scoped software gaming, not so much. Let’s explore their benefits.

In a lot of languages, globals are part of the language design, irrespective of how the runtime and tools/IDE’s handle them. Some languages make them first class citizens with mechanisms and rules around how they’re often used. This makes them formalized, accepted, AND useful. This is important to understand.

If it’s formalized, it means the language designers deem their usage acceptable, AND expected.

If it’s accepted, it means others will use them, incorporate them into their projects, libraries, and training & writing materials. This also means it’s then promoted amongst the community, solutions and coding strategies/solutions are built around it. This doesn’t make it inherently “good”, just accepted in that particular community.

If it’s useful, the majority of people will use it if their job is using that language as opposed to hobbyists, or those who continue to explore the language and try different ways to solve similar problems with it off of their employer’s clock.

In Lua, globals are all 3. Formalized via _G, very similar to ActionScript 1’s _global, accepted in that people do in fact use them (unknowingly a lot I’d wager), and useful since the syntax to utilize globals is terse; a Lua hallmark. Notice both have the preceding underscore to ensure they don’t interfere with the developer’s potential to create a variable called G or global. While ActionScript 1 has some security implementations to prevent certain loaded SWF’s from writing/modifying existing definitions, they had the same mechinism with strorage, first via _level’s on a per SWF basis, and later a formalized _global. Lua takes it a step farther with a series of facilities to change “which” globals your using, etc. It’s also used in package naming strategies, OOP, etc.

As a globally accessible table, access to _G is fast. Fast is good in game development. You want to be part of the solution, not part of the problem.

Global Variables: The Bad

This differs from traditional software development. If you come from any formal software development, globals are considered extremely bad practice. There is a common strategy to use the Singleton design pattern to “get away with it”. Even those are considered bad practice when over used. In fact, Singletons are often created merely because the language doesn’t offer a formalized way of doing global variables (like ActionScript 3 vs. ActionScript 1).

Why? The 3 main reasons are application state coupling, access control, and preventing testability.

Application State Coupling

Application State Coupling refers to the state of your application being dependent on usually a series of global variables. I won’t get into the why’s, but MVC and it’s MVP derivatives (Passive View, Supervising Controller, Presentation Model) have solved most of the state problems. They keep visual state in the View’s (or anything that’s a GUI that you can see), and application logic & state in the Model layer somewhere. Your application is no longer coupled to a single variable being a specific value for your application to run, to exhibit a certain bug, etc. Each piece can (usually, hehe) be run independently, and if there is a problem, you know where to look, or at least where NOT to look.

An example is if your player is dying too quickly, you know the problem isn’t in the player code, or the controller code, but rather somewhere in the model where his life state is being access/set/updated. If you used a global, it’d probably be set in player itself, or perhaps by an enemy bullet that hit him, etc. No clue where to look.

Another side effect is adding new global variables. This leads to certain parts of your application expecting the globals to be a certain value at certain times. If they aren’t, things don’t work. Because they are many different places, it becomes extremely time consuming for you to debug and track down because you don’t necessarily know who is expecting what to be set to what, and why. This is more caused by access control, however…

Access Control

Access Control refers to who can access your data, and how. In Flash & Flex apps that are smaller, we’ll usually use the server as access control. Meaning, while we provide a GUI to allow people to create, edit, and delete users from a database for example, the actual PHP/Ruby/Python/Java on the server is the access control. No matter what we do in the Flex/Flash, we can be assured the server (usually… *sigh*) will ensure we don’t delete people we’re not allowed to, delete users en-masse, put illegal characters into their name, etc. Basically anything that would corrupt the data and screw the up the GUI.

In Flex/Flash apps, and nowadays in larger JavaScript web applications, you have a notion of “application logic” or “application state”. This is because this state is no longer on the server. It used to be with some web applications, usually in the session. When you go add something to your cart on Amazon.com, it’s not stored on the page that much beyond to show you a slight graphical change. Once you change pages, that JavaScript & HTML page state is now gone and replaced with a new one… but it remembers what you added. It does this because the state is saved on the server since the client needs to be stateless if the user refreshes the page to go to another one.

We don’t have that problem as much in Flash/Flex apps. We don’t go to pages insomuch as new “Views”. These views, or graphical representations of a GUI that have internal state, are still in the same SWF embedded in the same page in a browser that doesn’t go anywhere (same thing for an AIR app on the desktop or on a mobile device). Therefore, someone has to be responsible for holding the data in a variable or series of variables, and updating it when the server gives you new data.

These are usually classes called “Models”, and they’ll usually mirror their server-side equivalents in terms of CRUD operations: create, read, update, and delete. Where they differ is how much of the server-side provided data is parsed, error handling, data access control, and how that server-side data is set internally.

Suffice to say, good Model classes are encapsulated, ensure application logic is accessed by a public API that ensures security, doesn’t allow the internal data to be corrupted, and does all this within reason. An example is our Player’s health. If every enemy collision and bullet out there has access to the player’s health, we have no easy way to track down who may be potentially doing the math wrong on calculating the new hit-points and setting them to invalid values, or thinking the player is dead when she’s not, etc. If you have a PlayerModel, you can ensure your problem’s regarding hit-points and letting the world know about player death is in one place, and problems with said state (how much health does the player currently have) starts in that class and those who access him. Access control in this case refers to ensuring the PlayerModel only exposes methods to increment/decrement the Player’s hit-points vs. allowing them to be set to -16, or NaN/Nil, etc. You don’t even have to worry about this; you just don’t allow it to happen.

Thus, the burden on accessing and setting hit-points correctly is pushed to someone else; those who access PlayerModel. THIS is where you look for bugs, but again, you need to ensure only a set few have access to the data access layer (PlayerModel).

In short, Models centralize data access, ensure it’s correct, testable, and DRY and prevent incorrect access errors, (i.e. global.playerHitPoints = “dude, pimp!”).

Preventing Testability

This third problem isn’t necessarily around unit-testing and TDD (Test Driven Development), but more around just ripping the class out, putting in a simple main.lua, and seeing if it works. If it has dependencies, they get dragged with it… and you have to instantiate and setup those guys. Suddenly quickly confirming some class or method works or not becomes a time consuming process that’s painful. If you can’t test something in isolation, you’ll have huge problems down the road isolating problems in a timely fashion.

Globals by their very nature are’t testable because they’re variables, not encapsulated classes. While Lua has some neat mechanisms to encapsulate globals in certain contexts, somewhere, someone is setting a global to some value in their own way. If a class depends on this global, that global must be set the same way before you test the class that relies on the global. Since you may not know who set the global a certain way, that global may not be the same in your test environment vs. in the game proper.

Global Conclusions

While globals in Lua are fast, formalized, and accepted, you must be aware of the rules so you can break them with confidence. First, keep in mind if you want to get something done, premature optimization is the root of all evil. With that in mind, ask yourself the quick question: Does creating a data access control class/layer around your globals to ensure it’s DRY and secure add so much overhead that the speed makes your game un-playable?

I’ve found this not to be the case in my implementations in Lua and ActionScript. They run fine, are encapsulated, and succeed in good access control. Thus, while globals are accepted in Lua, implementing a good coding practice via a data access layer does not adversely affect my performance while increasing my productivity in DRY’er code that’s easier to test with good encapsulation.

Messaging Dependencies

We’ve seen how globals can work to allow multiple View’s to talk to each other directly or indirectly via variables they all reference, or even methods/tables. We’ve also see how this leads to bad things like harder to find bugs and spaghetti code (you change 1 thing that adversely affects something else seemingly unrelated) as well as making refactoring more challenging than it needs to be.

One way to allow encapsulated objects to communicate is through messaging systems, also know as notifications or events (we’ll just call them events because that’s what ActionScript and Corona use). When something happens inside the object, such as a user clicking something, or some internal property changes, it’ll emit an event. There are 3 types of events we’re concerned with: local, global, and event context.

A local event is an event issued from an object/table. In ActionScript, anything that extends EventDispatcher, including DisplayObjects (things you can see), can emit events. In Lua, only DisplayObjects can; you have to build your own for regular tables as Lua doesn’t have an event system. So, if I create a wrapper table in Lua, I can then register for events from that table, and later when it emits them, I’ll hear them. Those are local events; events dispatched from an object/table directly. Although event objects/tables have the target property on them so I know where they come from, USUALLY event responders are not that encapsulated, and make the assumption that the event is coming from a specific object/table.

A global event is one that’s received, but we have no clue where it came from. At this point, we’re inspecting the event object itself to find context. If it’s a collision, then who collided with who? If it’s a touch event, then what was touched, and how? Global messaging systems are used for higher-level events and concerns. While you usually won’t have global events for touches because your mainly concerned with handling the touch event locally, a pause event for example could of been issued from anywhere, and while you don’t care who issued it, you’re more than capable of handling it (stopping your game loop, pausing your player’s movement, etc).

To properly handle an event, we need context. Context is basically the data the event, or message, has stored internally so when the handler gets it, he knows how to handle it. If the event is a touch event, cool, start moving. If it’s a touch release event, cool, stop moving. If it’s a collision, is it a bullet? If so, take less damage than say a missile hitting. Is the bullet’s velocity higher? If so, take more damage than usual. This context is what allows the encapsulation to happen. You issue a message, provide context, and whoever gets it doesn’t necessarily HAVE to know where it came from; they’ll have enough information to know how to handle it.

For Corona DisplayObjects, this is easy. You just use dispatch an event. But for Model/data access objects, not so much. You don’t want the overhead of a DisplayObject to just to send messages, so you build your own. This implies another class/table with the capability of sending/receiving messages. This means your classes will have a dependency on this object. For example, if I want to test my Model class in a brand new main.lua, it’ll bring along/require the messaging class. This is a dependency. One of the threads (just like OOP, encapsulation, keeping things DRY, don’t optimize too early, etc) you want to keep in the back of your head is to keep the dependencies low. You don’t want a class to have too many dependencies. Like globals, dependencies can cause spaghetti code, hard to test & debug situations, and overall just hard to manage code.

Corona makes the event dispatching dependency invisible with DisplayObjects because it’s built in. Not so for regular tables. Somehow, you have to put this dependency in every class. You can either create a public setter for it, and pass in an instance, or just reference a class globally in a base class. Both are a dependency, the latter just requires a lot less work and code.

Downside? It’s a dependency. You also force this implementation on everyone who wishes to utilize your class. If you make the messaging system events, 2 things happen. First, people using Corona get it because it’s the exact same API and functionality (excluding bubbling) that developers are used to. Secondly, it’s interchangeable and works with Corona DisplayObjects. The best solution would be to do Dependency Injection/Inversion of Control… but I haven’t figured out how to do this in Lua yet, and I’m not sure Lua supports metadata annotations. Considering it’s dynamic, you CAN inject things like this at runtime, but someone, somewhere has to do so. Why do so when every object requiring messaging needs the same mechanism? Thus, the pragmatic thing is to build it in.

Also, more importantly, DOES this messaging system add more performance overhead than using simple globals? To make the question harder to answer, can you make tighter coupling of your code and still get things done?

It’s been my experience, if you make things easier to use with less coupling, you’re more productive in the last 10% of your project. While coupling makes things easy in the beginning, it’s a farce; it has more than an exponential cost at the end.

Besides, you can always increase coupling easily; it’s removing coupling later that’s hard. If you need to optimize, great, you can. If not, great, no more work to do; you can instead focus on features. Usually, though, you’ll know pretty quick if you do iterative builds if a messaging system is making a huge performance impact on your game on not. The only surprises you’ll get is you spend days on something without a build. Do a small test, see if there is a noticeable difference. Sometimes you’ll have n-problems you won’t find till your game gets to a specific size which are unfortunate. An example is a charting component that works great building up to 5000 data points, but suddenly DRASTICALLY slows down beyond that.

These problems aren’t the fault of the API. If you take a step back, the “30,000ft view”, usually it’s the implementation that’s at fault, not the code itself.

For example, a little history lesson. Back when ActionScript 1 development was increasing in scope, we went through 4 different messaging systems. The first was the built-in one for Mouse and Keyboard, etc. It was only partially available; there wasn’t a MovieClip one. So, we used ASBroadcaster; an undocumented one inside of Flash Player. It had a known bug with removing a listener during a dispatch, and other things. Then Bokel released a version on top of that fixed it. Then Adobe created EventDispatcher, mirroring the ECMA one. They then built this into the Flash Player for Flash Player 9’s new virtual machine.

There were others that came out after ActionScript 3 was born. PureMVC had notifications in it for an easier port to other platforms & languages. Robert Penner created Signals for a light-weight, object poolable, quick to develop in C#-esque messaging system.

As you can see, why the bottleneck for most larger Flash & Flex 1.x applications at the time was EventDispatcher, even when they built it into the runtime in C, developers opt-ed for a slower system built by themselves to solve different problems.

So why the continuous talk about performance questions in this section when I rail against premature optimization? Because messaging is the core of any app, or game. The choice you make is the largest impact on what you’re building, both from performance and from a development perspective. Yes, you can just use direct access to objects, or callbacks, but that’s not very encapsulated, nor DRY, and is a pain to re-factor later if you need. Messages via Events are more encapsulated, and less coupled, but have a performance impact. Additionally, only DisplayObjects use the internal C implementation; your own uses interpreted Lua with whatever JIT’ing/machine/voodoo conversion Corona does.

Traditionally, it’s easy to switch to events from callbacks, but not the other way around. While the performance impact isn’t that large to utilize a DisplayObject and use the built-in event messaging, based on some benchmarks, this isn’t a good idea to build upon.

Mediation

The third option is using the Mediator pattern. Once you have 2 encapsulated objects that need to talk to each other, you utilize a class that handles the communication. It takes the message from ViewA and sends that to ViewB. When ViewB wishes to talk to ViewA, it sends the message and the Mediator relays it.

All the MVC/MVP articles go over A LOT about the different things a View should/should not do, particularly with it’s needs for data and how to show it. Regardless of the implementation, it’s generally understood that someone such as a Mediator or a Presenter handels the responses from a View. If it’s a Presenter, it’s a dependency in the View, and the View calls methods on it. This allows the actual logic behind both responding to View user gestures (like when I touch a button on the phone) to not muddy up the View (muddy up means TONS of code that has nothing to do with displaying graphics, putting into groups, setting up Sprite Sheets, etc), and allows you to test the behavior in isolation.

Mediator’s are similar, although, the View has no idea he/she has a Mediator, and the Mediator has the View reference passed into it by someone else. Again, more encapsulation, yet SOMEONE has to have the burden of setting up this relationship. In ActionScript this is easy; Robotlegs just listens for the Event.ADDED_TO_STAGE/REMOVED_FROM_STAGE events and creates/destroys based on an internal hash/table. In Lua, you don’t have any DisplayObjects events, so you have to manually do it.

Either way, if you DON’T Mediate your View’s, you’ll eventually have a lot of code in there that has to “know” about other objects. This’ll be either a global reference, or a dependency… and we’ve already talked about why those things are bad to do. Additionally, tons of code in general is bad; having a View just focus on graphical things and emitting events people outside would care about while the logic can be put elsewhere makes it easier to manage. When you open a View class; you know pretty quickly what you’re looking at is just GUI specific code.

There’s another more important aspect of Mediation that is similar to messaging and that is system events that affect Application Logic.

For example, many things in a game care about a Player’s health.

• the Sprite that represents the player; it needs to show different graphics for how much health it has
• a health bar at the top right of the screen that fills up with green the more health the player has
• sounds that play when the player loses and gains health

If you use globals, you’d have all 3 handled by the actual Player sprite class. It’d update it’s internal health and update the global variables. Those who have references to the globals would be informed when that value changes. Additionally, you’ve now wired them together if you do this. If you change one, you’ll break the other.

Using a Mediator allows:

• the player and the health bar both the capability to react to the change in the hit points in an encapsulated way. If you change how the Player and HealthBar look/work, the actual logic on how yo do that is centralized to either them, or their Mediators… and usually Mediators are like 1 line of actual code to change.
• The application logic of how hit points are updated and changed to be done in 1 place. As your game grows and different enemies need to do different types of damage to your player, and sometimes react differently depending on how much health the player has, this is all done and updated in 1 place. It’s DRY, and easy to find where the logic bugs are.
• A side effect of this is… the Mediator pattern (lolz). You can have View’s the capability of talking to each other without having tight coupling.

The most important feature is solving the classic race condition of is the data ready for a View when he’s created, or is it null and he has to wait. Using Medaitors, you don’t have this problem. In the onRegister, you just set it if you have it on whatever Model(s) you need, else just wait for the Model(s) to be updated and inform the view.

…I wouldn’t say totally solved; handling “null” or “nil” is still a challenge for developers even in simple View’s. Those are good problems to have, though vs. race conditions.

If you enter the optimization phase of your game and want to remove events, use callbacks, and have hard-wired references, that’s fine if benchmarks truly identify that you need the performance gains. Usually, though, Mediator communication isn’t your bottle neck, it’s collisions, lack of object-pooling, and how messages are handled.

Quickie on Commands

Commands are just formalized Controller logic. In fact, in other frameworks, they’re simply Controller classes with methods. They’re called “Commands” because they do 1 thing… and can potentially undo it. If you’ve ever used an Adobe Product, a few of them like Dreamweaver, Fireworks, Flash, and Photoshop will have a Command list, also called “History Panel”. In Flash and Fireworks, you can even get the code for these Commands. The line blurs here once you lump them all together, but in my experience, good Controllers have 2 things in common:

1. They contain the only code in the application that updates the Models (update/delete in CRUD for internal data)
2. They contain all application logic… or at least share the burden with the Models.

For #1, this is important in tracking down bugs and keeping your code DRY. You always know who’s changing your Player’s hit points, who’s actually applying your level up rewards, etc. If you can test your Models in isolation, and they’re good… then you know who to blame. This is good because again, they tend to often start by being 1 line functions with the potential to grow to 30 to 60… not a bad way to start life, nor grow. Small, readable code.

For #2, whether you have a Controller class function, or a Command, SOMEONE in your application needs to “load the level data” from your level editor. SOMEONE needs to handle the fact that your player just drank a health potion, but he’s also wearing a Ring of Health Boost + 2, and this positively affects the effects of the health potions she drinks. SOMEONE needs to handle calling the loadSaveGame service, ensuring it worked, and updating all the Models with their relevant Memento data.

This orchestrator of pulling everyone together, to read multiple Models and “make decisions”, they’re the brains of your application. For performance reasons, a lot of Controller logic is often done directly in game views, even if it just references a Controller class for ensuring logic is somewhat DRY.

There’s a lot of loathing in the community by those with a more pragmatic bent, or just on smaller code bases with shorter deadlines. The overhead associated with them completely negates their perceived value when you can just call a centralized Controller logic function via… a function call vs. some event that magically spawns some other class that has 1 function with a bunch of injected dependencies. Just depends in you read that last sentence and go “Makes sense to me, don’t see what the issue with it is… ” or “w…t…f… why!?”.

Conclusions

Remember, the above is all complete bs. If you or your team have a way of building games that works for you, great. This is just helpful tool I’ve found in Flash & Flex application development, and it seems to help me in Corona games, specifically around the GUI/HUD portions. I still have globals in my collision routines for speed purposes, hehe.

Additionally, it’s a great teaching tool, too. Joel Hooks got some similar schlack like I did in using PureMVC when he was first starting out in Objective C for iPhone. Providing a comfortable & familiar framework of development really helped him learn and have context how the new language & platform work with certain concerns; it’s how he shipped his first app on the app store. Same with me in Corona… and game development.

Finally, this isn’t an all or nothing approach. You can just use it on the parts you need, or perhaps just to learn. I find its helped me learn a lot about Lua and Corona, as well as having the flexibly to change the API of my Player and Enemies without affecting how the GUI itself around the game works. In true spirit of total disclosure, I’ll report on any adverse overhead if I find it.