How To Make a Simple Game with Moai

This is a tutorial for beginner Moak SDK developers, you’ll learn how to create a new animal-feeding game for iOS from scratch. With Moai, you don’t need to fear being locked in to one platform — you can let everyone enjoy the fruits of your labors! By .

Leave a rating/review
Save for later

In this tutorial you’ll learn how to create a simple 2D game using Moai, a Lua-based game development platform.

With Moai, you don’t need to fear being locked in to one platform — you can let everyone enjoy the fruits of your labors! It supports iOS, Android, Mac, Windows, Linux, and Chrome client applications.

Unlike other Lua-based SDKs such as Corona, Moai is completely free. In addition, it’s open source, and it’s easy to extend by adding other 3rd party Lua libraries. Finally, it’s full of features – offering more than many other SDKs.

On the other hand, it’s slightly more complicated than Corona, and takes a bit more time to learn how to use it effectively. But don’t worry – that’s what this tutorial is for! :]

In this tutorial, you’ll create a simple “Animal Feeding” game. Basically, food items will scroll across the screen, and it’s your job to get the correct food items to the correct animals.

In the process, you’ll learn all about Moai, including how to use sprites, animation, sound, collision detection, and text rendering!

This tutorial assumes you have some basic familiarity with Lua. If you’re completely new to Lua, the Lua Tutorial or official Lua documentation is a great resource to get you up to speed on Lua and what it has to offer.

What is Moai?

Moai SDK is a 2D game framework created by an indie games development studio – Zipline Games. It has four main killer features:

  • It’s cross-platform. Moai makes it easy to deploy your app to multiple platforms,
  • It supports rapid development. You code Moai apps with Lua, a quick and easy scripting language. Moai also comes with native Mac and Windows clients, which allows you to test your code quickly without needing to deploy to a device.
  • It gives full source code access. Moai comes with full source code access, so if you’d like you can dig in to see how things work or extend it with your own code!
  • It’s free! The base SDK is completely free, but requires to place the Moai logo within the app (and inform users it’s built with Moai). However, there is an optional service called Moai Cloud which is paid – more on this later.

It is currently used in a lot of games, such as:

The Moai Cloud

Moai Cloud is where the developers of Moai make their money. It’s a RESTful web service that allows you to store your user’s data, leaderboards, and achievements – in a cross-platform and easy way.

When you’re getting started, using Moai Cloud is also free (a “Sandbox” model, with limited storage and monthly bandwidth, probably sufficient for development and beta testing phase). However, as your game grows in traffic you’ll need to upgrade to a paid option.

Of course, you’re not forced to use Moai SDK with Cloud, or Cloud with the SDK – those are separate components that can be mixed however you want.

About the SDK

The most important objects in Moai are:

  • Layers: Like Layers in Cocos2D, these are “blank canvases” that you add your display objects to.
  • Partition: This is a class that you’ll use in your touch-handling code.
  • Props: Think of these as Sprites in other game frameworks.
  • MOAIRenderMgr: You pass your layers to this class so they can be rendered to the screen.

Here’s an illustration showing this at a glance:

Diagram of Moai classes you’ll be using in this tutorial

But the easiest way to understand this is to try it out. So let’s dig in!

Getting Started

First, download the Moai SDK at This tutorial covers the 1.4p0 release from March 2013.

Download and unpack the distribution file. You should see the following folders inside:

Folders inside the MOAI SDK package

Folders inside the MOAI SDK package

Take a look inside the /bin and /samples folders.

Inside /bin, you’ll see subfolders for OS X and Windows – these are the files needed to run the app in those environments.

The samples folder contains a ton of examples – you can try them out in a bit after I show you how to run Moai.

To run the Moai executable from the terminal, you must specify the full path. This will depend on where you unpacked the Moai archive. I recommend you move the Moai folder to a safe and permanent spot on your hard drive.

Enter the command below in Terminal:

$ /Users/my-username/moai-sdk/bin/osx/moai

Of course, replace the path for where you saved your Moai SDK. Bonus points for those of you who typed it in right the first time! :]

You’ll notice that the screen flickered briefly when you ran the above command, but otherwise it should exit right away without an error message if everything went well.

To simplify things, add the following line to the bottom of .bash_profile in your home directory. This will add the Moai executable’s path to your system path. Make sure to adjust the path if you unpacked the Moai archive in a different directory:

export PATH=$PATH:/Users/my-username/moai-sdk/bin/osx

Quit Terminal and re-start for this to take effect.

Now, try it out! Switch to one of the sample directories (like physics/physics-chipmunk) and run main.lua as follows:

cd /Users/my-username/moai-sdk/samples/physics/physics-chipmunk
moai main.lua

You should then see something like the following:

Chipmunk physics demo with Moai.

Chipmunk physics demo with Moai.

If that shows up, congrats – it’s working!

Note: For the rest of this tutorial, instead of the full path /some/folder/moai-sdk/bin/osx/moai, you can just run moai instead. It will be a great time saver!

Ready Player One — Getting Your Project Ready

For the game you’re making in this tutorial, I’ve created a starter project for you. It doesn’t contain any code yet, but it contains all of the files and sounds you’ll need for the game, as well as a nice directory structure.

So Download the starter project and unpack it. Inside you’ll find a project folder named AnimalFeeding. As well, you’ll find a set of image and audio assets along with the main.lua file, which will contain the main game code. The structure is shown below:

Project files

Fire up your text editor of choice and open up main.lua.

Whoa — it’s empty! That will get you nowhere fast! First, you’ll need to display a window on the screen. Every visual application needs a window (or a view in iOS) to display your work.

Paste the following code into the main.lua:

-- screen (window) initialization
-- 1.
local STAGE_WIDTH = 960
local STAGE_HEIGHT = 640
local SCREEN_WIDTH = 960
local SCREEN_HEIGHT = 640
print ( "System: ", MOAIEnvironment.osBrand )
print ( "Resolution: " .. SCREEN_WIDTH .. "x" .. SCREEN_HEIGHT )

-- 2.
MOAISim.openWindow ( "Animal Feeding", SCREEN_WIDTH, SCREEN_HEIGHT ) -- window/device size

-- 3.
local viewport = ()
viewport:setSize ( SCREEN_WIDTH, SCREEN_HEIGHT ) -- window/device size
viewport:setScale ( STAGE_WIDTH, STAGE_HEIGHT ) -- size of the "app"

-- 4. 
local layer = ()
layer:setViewport ( viewport )
layer:setClearColor (0.53, 0.53, 0.53, 1)

-- 5.
local partition = ()
layer:setPartition ( partition )

-- 6.
MOAIRenderMgr.setRenderTable ( { layer } )

Here’s a quick rundown of the code above, comment by comment:

  1. Set some local constants (stage and screen width and height) and print them out to the console. If you’re new to Lua, keep in mind that the local keyword gives the variable limited rather than global scope. In this app the scope doesn’t really matter, but it’s a good practice to limit the number of global variables floating around.
  2. Open the window, name it “Animal Feeding” and set width and height to the previously defined 960 and 640.
  3. Create the viewport, which is what allows you to “look” at the scene. The viewport size refers to the actual display size, while the scale defines the coordinates. In this case, the size and scale are the same. If you have a Retina display, you might set the size to 960×640 but the scale to 480×320.
  4. Create a layer, which is sort of like the “root” view or window. A layer needs to be viewed through a viewport, so the viewport from step #3 is linked to the layer. The “clear color” is the background color of the layer, which is set to a nice grey (RGB 0.53, 0.53, 0.53)
  5. A partition is used to catch user interactions, such as clicks and touch events. This will come in use later when you add the interactive bits.
  6. Finally, the Moai Render Manager is set up to handle rendering on the newly created layer.

To run the code, open up a Terminal window and navigate to the folder containing main.lua.

Build and run your code with this command:

$ moai main.lua

You’ll see the following stunning window:

Empty window

Success! A nice blank grey window. You should also notice the output of the two print statements in the terminal:

System: 	OSX
Resolution: 960x640

Now that the window is set up, it’s time to add something more interesting to it.