How To Make a Simple Game with Moai

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:

• Zipline’s Games: Wolf Toss, Slots Tycoon, and more
• Physics-Based games: Bubble Ball and more
• Minigames for Kids: Go Go Kiddo and more
• Strategy games: Crimson: Steam Pirates, You’re a Bank, and more

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

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 http://getmoai.com/sdk/moai-sdk-download.html. 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!