I’ve entered strictly for learning purposes and to see if I can actually finish something. Game development is surprisingly very different from application development, and it’s nice to feel really stupid again.

Synopsis

I fell back to my roots and attempted to build a mobile application that used “gamification”. Basically, you make the application fun through adding gaming elements to it. I’m good at building applications so figured if I fell back to my roots and adding just a little bit of game dev to it, I’d be able to create a lot more in the same period.

I changed my lifestyle last year in March of 2012 through adding fitness and changing my diet. A year later, I feel better and look better. I wondered how I could help others reach the same goals. While people tell you it’s 50% diet, 50% exercise, I felt for me 80% of the challenge was diet. I know nothing about cooking beyond what I’ve taught myself. My mom and grand mom taught me some stuff, but for whatever reason as I kid I just never really cared to better myself at it.

So, I made a list of all the smaller things I did that had longer term impact. I realize Type A Personality techniques of making huge changes with hardcore willpower are not the most effective way at changing people’s behavior. I’ve also read the statistics on how many actually keep weight off after they’ve lost it, and the time people devote to food preparation vs. exercise. For Americans, it’s pretty dire. I took that list I wrote, and selected the ones that were the low hanging fruit, and hopefully easy attainable without requiring a Doctor’s note to attempt.

If you look at most nutrition advice, at least online or in books, it’s usually huge lifestyle changes. That’s asking a lot of people, and the #’s prove it doesn’t lead to longterm positive lifestyle changes. What DOES work is small habits that lead to longer term change. If you change a bunch of them, they collectively, slowly, lead to a more healthier, and more importantly, a self-empowered, individual. I started to make the application I wish I originally had: simple tips I could try everyday that didn’t totally shock my way of life, and that I could actually accomplish, and feel good about.

Goals

Give people simple healthy diet changes to try. From making people healthier, feel better, or empowering them to learn on their own. Giving someone 1 thing to try every day, even multiple times if they wished, to practice at being more healthy without having to focus 100% of their life on doing so. My hope was it’d be the least invasive thing in their life, thus hopefully maximizing the success rate. Kata’s are simple exercises you do in martial arts to practice and get better. I wanted something like that in a diet context vs. “OMG CHANGE YOUR LIFE!”

Additionally, they’d have both motivation in the form of videos and citations that show the positives of even minor diet changes as well as a world wide achievements bored to see how many others had already accomplished each kata (or simple exercise  to also help with motivation.

Actual Results

I didn’t finish.

That said, all of the original katas are in the app, and you can try them, and have a record of your accomplishments. So it’s technically an early alpha, heh.

I ran out of time for motivations, and the achievements board was slowed because it was the first time I used Corona’s Cloud API.

The main problem with the data entered currently is that 3 important things are missing. I wanted to ensure all health recommendations I had were based on science that had at least 1 scientific study/citation. A lot of these studies are extremely wordy. Most people just want to know either WHY something is healthy or how it’s POTENTIALLY healthy. The later is horrible in terms of how we humans operate, but it’s also a good tool to get people to do what you want them to do. Anyway, collecting + summarizing all of that information is a ton of work. I’m constantly reading nutrition books and articles and taking notes, just not finished yet.

The other issue is turning those successes into congratulatory notes. When you complete a kata, you get a success message. For example, although I assumed users didn’t do drugs nor smoke, even just stopping smoking for example has a swath of awesome things that happen to your body. It’s important you not only reward people for accomplishing the simple exercise, this builds self-confidence in them, but also you teach them WHY. Once someone knows the why and has self-confidence, change is afoot. Writing those is tough… even tweet size ones.

Finally, the questions are sometimes backwards; I need to add a boolean to the VO’s to say if yes leads to completing or starting the kata… or just make all the questions have “yes” lead to starting the kata. If you use the app now, just say yes to everything.

What Went Wrong

The main problems were:

• not enough free time
• still learning nutritional science
• Corona’s lack of basic GUI components and redraw invalidation
• not enough documentation on Corona Cloud + having to learn a new API
• Responsive Design
• explaining to people how no longer eating their favorite unhealthy things is fun… in a mobile application… yeah.

Free Time

As usual, work both in client projects as well as outside took a lot of time. My main current client has a huge feature release coming up that we’ve all be tag teaming. This requires a lot of consistent communication as well as on-site visits which means I’m travelling a lot. I also travelled back to Georgia to sell my house. I’m uncompromising in my workout schedule and picking up my kids from school which is 2 hours minimum a day. Also, it took me about 5 days to recover from March #1GAM burnout. Finally, my company released the FlowMVC framework based on the DeftJS framework that all works atop Sencha, and that took a lot of time to ensure we got the alpha out as well.

Nutrition Knowledge

I’m not classically trained in nutrition, so am learning the same way I learned how to program: read online articles, read books, and asking questions of those who appear to be experts. Suffice to say it’s just as hard as programming to get to the real truth; it’s all masked in subjectivity and utter untruths. Making definitive statements is VERY hard to back up with science. America in particular has a ton of science around how to cure sickness, but very little on how to keep us not-sick via good nutrition. Frustrating. You have tread carefully when utilizing Qualitative science from qualified individuals. Bottom line there are a few facts, and a few of studies that reach conclusions but aren’t facts.

Sadly, a lot online is useless. At least with programming you can use sites like Stackoverflow.com and communities that reference certain blogs/articles to find the good stuff. For nutrition, there are a few sites like that, but they don’t always cite their sources, nor differentiate between “the facts” and “the guesses based on the following studies which may/may not have contradictory studies”.

I wanted the app to have solid science, and getting solid science as a n00b is hard.

Corona’s App State

While Corona has made great strides on the widget front, their gaming focus, both as a company and in the runtime features are clearly biased. Even the Corona cloud library they posted on Github uses “name spacing”, a pseudo copy of how Python handles classes and packages. This, instead of using the proper class/module packages they introduced about a year ago. I reckon they did this to cater to game devs who freak out if you do 2 dots to get a “module” whereas for application developers, it’s just expected if you’re from a traditional OOP background and you get the time to actually think about class structure that often doesn’t change as much as it does in gaming.

This seems like a digression but it’s not; the simple fact they’re game focused makes even simple things application developers expect to be non-existent. For example, I DARE you to center a multiline block of text on the screen with arbitrary widths… and then put a different block of text in it. Works no problem in Flash/Flex and HTML(!). Corona doesn’t recalculate/remeasure, and your registration point is off, and using simple x and width values to center the text suddenly fail. If you just create another text field, no problem, but even game developers know you object pool where possible.

Layout in this case is made worse as they abstract away device specific text fields. While it’s nice to use native device (iOS/Android) text fields that do render well, they don’t always render like you think on the simulator, namely the native options with backgrounds/borders disabled. Haveing to compile to view on the device is just awful. It defeats the whole purpose of Lua being an instantaneous code reload solution. If I wanted to recompile and redeploy to the device, I’d use native XCode and Objective C.

These basic needs make building higher level abstractions that are actually efficient harder. As components scale in size and complexity, especially data driven ones, you need some form of invalidation routine. Invalidation is a huge topic I’ve written about before, but suffice to say it prevents common race conditions, is an efficient redraw mechanism for runtimes like Corona that share both code execution and redraw on the same thread (see elastic race track articles discussing this), and solve order of operation errors for developers using components that require multiple properties to be set to work.

I’m in the process of building one on top of their enterFrame, but it’s like a flash back to 2001 in Flash MX; i.e. it’s a lot of work for 1 person to complete. A company like Corona should have the resources to handle this. Either they don’t have the people working for them that know these problems, or they’re focused on other things. I think it’s the latter; game specific features like their 2.5 graphics and cloud initiatives whilst open sourcing the components are signs. That’s fine, but oy vey… pain…

Another annoying thing is some widgets/components don’t work with groups. I get why, but this makes layout a royal journey into frustration and workarounds, and just generally nasty looking code.

I will say the widgets they DO have are great overall and open sourcing them was a dope move. The API consistency, while I get challenging, needs to be improved in both the libraries they distribute and in their internal SDK.

Responsive Design (lack thereof)

Because of the above crunch, I didn’t get a very responsive design. This lead to some devices not scaling properly… which sucked. For games, you can just scale up or down; Corona does this automatically. For applications, however, you basically do a “responsive design“. While most web sites prefer to use media queries and funky font measurements to accomplish this, using things like Sencha, Flex, or even Corona, and you can simply have each component size itself and it’s children. As the application grows, this works out well because they’ll fill whatever space you tell them too.

The kicker here is “if the design supports it”. For example a toolbar can scale infinitely horizontally, but tends to stay 60 pixels high. On most smartphones, this is fine, but on tablets, especially the high rez ones, it gets a bit too small to work. At that point you fall back to another nav. I didn’t even get that far… as soon as I went from a Nexus One to a Droid X, my app couldn’t even handle the extra 24 pixels.

I put a 640×960 mask on stage and called it a day.

Corona Cloud

Corona Cloud is awesome. The documentation is ok. The example code is awesome, although completely ignores Corona’s package structure and they’ve foregone using metatable vs. closure based classes for the same reason a lot of JavaScript libraries do the “large object on global window” to avoid the closure vs. Object.prototype debates. Anyway, nothing major here, just hard to learn a new API in such a short time frame with all the other challenges going on, thus compounding it.

Making Health Fun

For me, I was sick and tired of being sick and tired. Once I make my mind up, there’s no changing my mind. I have discipline with certain things I set my mind to. I get that to make broader changes to the world, you need to be more pragmatic about what you expect out of the general populace. I took the approach of “simple with positive messaging as instant reward and global awareness through achievements of other users”. The “simple” was simple, the Corona cloud achievements isn’t something I need but totally get how others need that motivation.

The “positive messaging” though is rough. When you look at the back of a “Matt’s Organic Orange Juice” container for example, they’ll go off about Vitamin D, and how it’s greatest thing for you evarrr. It clearly was written by a talented marketing copy writer and put through a few revisions. Trying to do that, for every single kata, was rough. As you can see, I can write a lot, but saying a lot with few words is HARD. Fun, but hard.

What Went Right

Finding a fitting design and icons I needed on GraphicRiver was uber easy. Getting the design to work in Corona, my component issues non-withstanding, also easy.

Setting up the MVC structure, also easy. I hadn’t messed with my port of Robotlegs for Corona for almost 2 years(!) since those kind of frameworks are more used for applications and less so games, so took the opportunity to bring it up to speed.

Coming up with simple things that are healthy for people to try was actually pretty easy as well. I just charted my own path and remembered all the hard things I did, and modified the order based on difficulty and organized into levels of lifestyle impact. The app was responsive on the device, and I only had minor masking problems with the Corona widgets. Once I got some good low level components, building the GUI’s was pretty quick and easy.

Key Takeaways

I think like my Februrary entry, I’d like to come back to this, finish it, and polish it. Even in application development, you can get into “the grind”, the last, brutal 10%. It’s easier to power through if you believe in the final product.

It’s also clear I shouldn’t do anything more GUI heavy without a Corona component framework ready before I start. Oh goody, another side project! *face palm*

I need to organize my notes about nutrition more. Most of it is for me related to fitness vs. just pragmatic well being. That and I forget what research/study/book told me what, and whether it was a “study” vs. a “paper” vs. a “theory” vs. a “scientific fact”… which greatly affects the other research/beliefs it’s related to. Like programming.

Finally, I need more time with Corona Cloud. It’s really cool, just haven’t had enough time to play to learn it more.

Conclusions

May: Go back to the 2D side scroller. From my February entry, it’s clear I liked making Box2D levels, and need more practice in making them, even if I don’t finish.

Once again, I’m burnt, and need a few days to recover. This time, though, I knew it was coming and planned for it: notes for May dev all ready, concepts documented from awhile ago when I’m ready to nail down an idea, and tons of alcohol and XBox games while I recover.

The source code is up on Github and you can install on your Android device here (although I’d wait until the version says “beta” hah).

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.

Introduction: Why Unit Test?

Lua in Corona SDK has 3 issues when your game/application code base grows to any large size.

First, Lua is a dynamic language much like JavaScript, Ruby, and Python. As such, you have little to no help from the compiler to ensure your code expects even basic parameters being passed to your functions as well as misspellings.

Secondly, Lua is dynamic at runtime. You actually need to run the code to see how it actually works. Examples include combining strings together to dynamically access properties on dynamically created objects in an asynchronous way.

Third, even if encapsulated, you have no way of knowing if your new code breaks existing code, or if modifying existing code allows it to work the same way with some assurance. This problem is not unique to Lua, it’s unique to any complex code base regardless of language.

All 3 combined necessitate a need for unit tests. Some would argue even just 1 of the above.

Anatomy of Unit Testing

Unit testing, as far as we’re concerned with Lua, are a bunch of functions that make sure things work as expected. Inside of those functions, you write those expectations about how you expect things to work as a bunch of assert functions. These groups of functions aren’t actually part of your main code base; they’re grouped together in a test folder and called a test suite. The more of them you have, the more test coverage you have.

TDD or Test Driven Development is where you actually write the above paragraph test code first, and THEN actually write the code it’s testing afterwards. You start with writing a test that fails, you write the code to make it pass, and then ensure the test passes. Then you repeat.

The above 2 paragraphs can, and do fill books with the details of TDD & unit testing… but that’s all you need to know for now. Heck, you can ignore everything I write here, start to proactively use assert, and your coding life will improve a lot.

Asserts
Let’s start at the beginning. Lua already has an expectation function, called “assert”. It looks like this:

local wubWubWub = true
assert(wubWubWub, "Someone forgot to drop the bass.")

This code asserts or “states positively” that the variable is true. If it were false, an error would be thrown with that string “Someone forgot to drop the bass.” passed into the error function. If you’re not aware, the error function in Lua stops execution of the current script and prints whatever string it has to the console/terminal. Secondly, all functions in Lua are implied to be successful if they return true.

Even without unit testing, using assert, you can be proactive in finding errors. For example, I use it all the time in manual getter/setters in Lua (not metatable ones, the set/get + method name convention). Since Lua has no typing system, I ensure my inputs are sanitized like so:

function setSpeed(newValue)
   assert(newValue ~= nil, "You cannot set speed to nil.")
   assert(type(newValue) == "number", "You must set speed to a number value.")
   self.speed = newValue
end

Those 2 functions alone find ALL kinds of silly bugs where someone, somewhere accidentally set a value to nil and it made it’s way deep into the bowels of some class, and I’m wondering who’s fault it is. When everyone starts doing this, it makes it really easy to find who caused the bug, and quickly.

Yes, there is a performance cost to assert. However, it’s easier to remove a bunch of assert functions scattered everywhere via a Find / Replace from solid code then it is at add them to code that runs very fast with lots of unknown bugs.

Moar Asserts

Just about every testing framework expands upon the above function. In fact, 80% of what they offer in their libraries and frameworks are additional assert functions. Why? Three reasons. First, would you rather write this?

local icon = display.newImage("icon.png")
assert(icon ~= nil, "Icon image cannot be found.")

or this:

local icon = display.newImage("icon.png")
assert_not_nil(icon, "Icon image cannot be found.")

The second reason is it’s more clear what that is testing; the function name alone tells you what you need to know before you’ve even made it to the parameters.

Here’s another example:

local currentSpeed = character.speed
character:setSpeed(currentSpeed + 1)
assert(character.speed > currentSpeed, "Character speed did not increase.")

vs writing:

local currentSpeed = character.speed
character:setSpeed(currentSpeed + 1)
assert_gt(character.speed, currentSpeed, "Character speed did not increase.")

Now this one may appear backwards; “A comma vs. using the normal mathematical construct!?”

Keep in mind, however, many bugs are caused by misplaced operators. For example, developers often will use = instead of == to assign a value, or they’ll use > vs. >= for edge cases, etc. In writing that code, it’s completely legal, and Lua’s interpreter won’t give you an error when you run it. Using assert_gt in this instance will ensure your expected value is there, as well as ensure you’ve use the operator correctly. If not, it’ll actually… you know… help you out!

And although I bash Lua for not having a type system, it does have a type function for a reason. You can test a variety of types such as assert_not_boolean for a return value that’s supposed to be a number, and assert_metatable if you’re doing funky metatable magic.

Suites

A suite is just a series of functions that are related. For example, in my example video I show my file suite which has unit tests for testing my DeleteFileService class and my ReadFileContentsService class. Since reading and writing and deleting files are something I consider related, I created a file suite, or “a bunch of functions that test file shiz”.

While lunatest can test functions inline, as an OOP guy, to me that’s just gross. I like the more organized suites where all the functions are in their own file. Lua calls it a file, I call it a Class, Lunatest calls it a suite… we’re all happy.

Here’s my file one:

module(..., package.seeall)

function test_saveFile()
	require "com.jxl.core.services.ReadFileContentsService"

	local saveFile = SaveFileService:new()
	local data = "moo"
	assert_true(saveFile:saveFile("test.txt", system.DocumentsDirectory, data), "Failed to save test.txt")
end

function test_readFile()
	require "com.jxl.core.services.ReadFileContentsService"
	require "com.jxl.core.services.SaveFileService"

	local saveFile = SaveFileService:new()
	local data = "moo"
	assert_true(saveFile:saveFile("test.txt", system.DocumentsDirectory, data), "Failed to save test.txt for use in reading.")

	local readFile = ReadFileContentsService:new()
	local contents = readFile:readFileContents("test.txt", system.DocumentsDirectory)
	assert_string(contents, "contents are not a string.")
	assert_equal(contents, data, "Data written to file does not match what we just read out of it.")
end

2 things to note about this file. First, I use the much loathed module(…, package.seeall) at the top. This is what lunatest wants in how it loads modules so… you’ll need to do this too (yes, I temporarily hacked lunatest to support Corona’s packages, but it wasn’t worth it).

Second, notice the 2 functions are both global and start with “test_”. Any function you want Lunatest to run as a test, you need to prefix it with “test_” in the function name. Notice they aren’t prefixed with local, they’re simple global functions.

That’s it. Put a bunch of functions in that file, make an assert or two within them, save it, and then in your main file, tell luna test about it.

Advanced Suites

The above is good enough for writing suites that’ll help you. Here’s 4 more cool things suites can do.

If you have repetitive code that needs to be run before every test, you can run it in the test setup. This ensures you only have to run it once, you have the option of aborting the test, and it’s run in a protected manner (aka pcall). Additionally, you don’t have to call this yourself, nor remember to do so, Lunatest does this for you. In my StateMachineSuite, I have to instantiate the StateMachine class for every call so I put it in setup.

If you have code that needs to be cleaned up a lot or in a particular order, you can utilize the teardown. If you implement one, it’s called after every single test case. This also ensures that if everything is deleted, strange memory bugs are more easily found. Some classes require more than just nilling out their variables, in the case of Corona SDK Display Objects and Widgets which must have their removeSelf called, THEN you can nil out the variable reference. You can also ensure all of the benefits of setup, just in a function called teardown where you clean up your mess.

Finally, there is a suite_setup and a suite_teardown. Unlike setup and teardown, these are only called once for the entire suite; suite_setup before any tests are run, and suite_teardown after everything, including the last teardown, is called. Sometimes you don’t need unique setup code for your tests so you can put it here instead. This is also a good place for class imports.

Here’s my StateMachine example. Notice it has a suite_setup (but no suite_teardown). The setup instantiates the StateMachine and the teardown ensures it’s deleted so each test function gets a brand new SuiteMachine instance.

module(..., package.seeall)

function suite_setup()
	require "com.jxl.core.statemachine.State"
	require "com.jxl.core.statemachine.StateMachine"
	require "com.jxl.core.statemachine.BaseState"
end

function setup()
	machine = StateMachine:new()
end

function teardown()
	machine = nil
end

function test_classWorks()
	assert_not_nil(machine)
end

function test_verifyInitialStateIsNil()
	assert_nil(machine.state)
end

function test_verifyInitialStateIsNullWithStates()
	local initial = "playing"
	machine:addState(initial)
	machine:addState("stopped")
	assert_nil(machine.state)
end

function test_verifyInitialStateIsNotNil()
	local initial = "playing"
	machine:addState(initial)
	machine:addState("stopped")
	machine:setInitialState(initial)
	assert_equal(initial, machine.state)
end

function test_enter()
	local t = {}
	local hitCallback = false
	function t.onPlayingEnter(event)
		assert_equal(event.toState, "playing")
		assert_equal(event.fromState, "idle")
		hitCallback = true
	end
	machine:addState("idle")
	machine:addState("playing", { enter = t.onPlayingEnter, from="*"})
	machine:setInitialState("idle")
	assert_true(machine:canChangeStateTo("playing"), "Not alowed to change to state playing.")
	assert_true(machine:changeState("playing"))
	assert_equal("playing", machine.state)
	assert_true(hitCallback, "Didn't hit the onPlayingEnter callback.")
end

function test_preventInitialOnEnterEvent()
	local t = {}
	local hitCallback = false
	function t.onPlayingEnter(event)
		hitCallback = true
	end
	machine:addState("idle")
	machine:addState("playing", { enter = t.onPlayingEnter, from="*"})
	machine:setInitialState("idle")
	assert_false(hitCallback, "Hit the callback when I had no initial state set.")
end

function test_exit()
	local t = {}
	local hitCallback = false
	function t.onPlayingExit(event)
		hitCallback = true
	end
	machine:addState("idle", {exit = t.onPlayingExit})
	machine:addState("playing", {from="*"})
	machine:setInitialState("idle")
	machine:changeState("playing")
	assert_true(hitCallback, "Never called onPlayingExit.")
end

function test_ensurePathAcceptable()
	machine:addState("prone")
	machine:addState("standing", {from="*"})
	machine:addState("running", {from={"standing"}})
	machine:setInitialState("standing")
	assert_true(machine:changeState("running"), "Failed to ensure correct path.")
end

function test_ensurePathUnacceptable()
	machine:addState("prone")
	machine:addState("standing", {from="*"})
	machine:addState("running", {from={"standing"}})
	machine:setInitialState("prone")
	assert_false(machine:changeState("running"), "Failed to ensure correct path.")
end

function test_hierarchical()
	local t = {}
	local calledonAttack = false
	local calledOnMeleeAttack = false
	function t.onAttack(event)
		calledonAttack = true
	end

	function t.onMeleeAttack(event)
		calledOnMeleeAttack = true
	end

	machine:addState("idle", {from="*"})
	machine:addState("attack",{from = "idle", enter = t.onAttack})
	machine:addState("melee attack", {parent = "attack", from = "attack", enter = t.onMeleeAttack})
	machine:addState("smash",{parent = "melee attack", enter = t.onSmash})
	machine:addState("missle attack",{parent = "attack", enter = onMissle})

	machine:setInitialState("idle")

	assert_true(machine:canChangeStateTo("attack"), "Cannot change to state attack from idle!?")
	assert_false(machine:canChangeStateTo("melee attack"), "Somehow we're allowed to change to melee attack even though we're not in the attack base state.")
	assert_false(machine:changeState("melee attack"), "We're somehow allowed to bypass the attack state and go straigt into the melee attack state.")
	assert_true(machine:changeState("attack"), "We're not allowed to go to the attack state from the idle state?")
	assert_false(machine:canChangeStateTo("attack"), "We're allowed to change to a state we're already in?")
	assert_true(machine:canChangeStateTo("melee attack"), "We're not allowed to go to our child state melee attack from attack?")
	assert_true(machine:changeState("melee attack"), "I don't get it, we're in the parent attack state, why can't we change?")
	assert_true(machine:canChangeStateTo("smash"), "We're not allowed to go to our smash child state from our parent melee attack state?")
	
	assert_true(machine:canChangeStateTo("attack"), "We're not allowed to go back to our parent attack state?")
	assert_true(machine:changeState("smash"), "We're not allowed to actually change state to our smash child state.")
	assert_false(machine:changeState("attack"))
	assert_true(machine:changeState("melee attack"))
	assert_true(machine:canChangeStateTo("attack"))
	assert_true(machine:canChangeStateTo("smash"))
	assert_true(machine:changeState("attack"))
end

Pay attention to that last part, it has some good and bad practices. The whole point of unit tests is to test 1 thing or unit. You shouldn’t have 50 billion asserts like I do. Worse, you’ll notice some of the asserts at the bottom do not have custom error messages in the 3rd parameter. If any 1 of those fail, there is no way to tell which one failed. Bad, Jesse, BAD!

Run

Setting up all of the above is a snap. Ready?

In your main.lua file, import Lunatest:

require "lunatest"

Next, add your suites:

lunatest.suite("tests.com.jxl.core.ServicesSuite")
lunatest.suite("tests.com.jxl.core.services.ReadFileContentsServiceSuite")
lunatest.suite("tests.com.jxl.core.statemachine.StateMachineSuite")
lunatest.suite("tests.com.jxl.zombiestick.services.LoadLevelServiceTest")

Finally, call run:

lunatest.run()

That’s it! You’ll see the report of stuff in the console/terminal.

Conclusions

The problem with unit testing is that you need to have units to actually test. A lot of code that wasn’t written to be unit tested needs to be refactored first which can be a lot of work. If it’s also entangled with other code that’s also not easily testable… you see where this is going. That’s ok. You can start in one section, or test high level results. Yes, your setup code may be burdensome, but it’s something. Automated tests, even if a certain section, can help you a lot. Additionally, when writing new code, think about writing it in a way that’s testable, even if you never actually test it. This often results in less coupled code anyway.

Additionally, while testing is in fact creating more code, you find more bugs, early, and faster, proactively. For games that require quick iterations… this can be tricky. If the game needs to be built to verify it’s even fun, is it worth it to unit test? As you make a lot of games in the same tech (whether Lua, C#, ActionScript, Java, whatever…), you’ll start to gather are a large set of functions, libraries, and classes that are reusable from project to project. THOSE are worth unit testing.

Unit tests are just a bunch of functions that test expectations, and are organized in suites. You run a bunch of test suites inside of Lunatest. Unit tests help ensure your function types are correct since Lua has no helpful compiler to help on this front as well as spelling mistakes. It also verifies your code works as you expect at runtime. Finally, for larger code bases, you can add new code without worry of breaking old code, including if you modify old code. The more unit tests you write, the more coverage you have. The more coverage, the easier it is to manage a larger code base.

Remember, unit tests are code too. You can still follow all the best practices your used to such as OOP, DRY, and being clean. MOAR UNIT TESTS!

Title image “Moon” by S4cr4m3nt.

Also posted on iOS Gaming.