Bytesize Adventures
Crafting bite-sized digital worlds

Getting started with Moai

This weekend I fancied dabbling with something a bit different. I’ve had my eye on Moai for some time now…

What is Moai?

In their own words, Moia is a “fast, minimalist, open-source Lua framework for pro game developers”. It’s also cross-platform, allowing you to target iOS, Android, PC, Mac, and Chrome (apparently Linux is coming too).

Never heard of it

It crossed my radar a while back (because of its cloud features) but more recently its been enjoying some attention because Double Fine have opted to use it for their upcoming Adventure game (the one that raised over $3 million in funding through Kickstarter).

The team at Double Fine have been sharing lots of insights into the development of the game (a perk for backers) and its been really interesting to read about how they’re using Moai. They’re even talking about feeding improvements back into the framework for the community to benefit from.


Lua is a lightweight scripting language that, as I understand, is used prolifically throughout the game development industry. Its typically embedded into the game to allow non-programmers (and programmer I guess) to easily script the game.

I’ve only dabbled with Lua fairly recently, mainly thanks to the excellent Codea for the iPad.

So, I’m new to both Moai and Lua which makes this an interesting and exciting challenge.


Moai is incredibly, perhaps deceptively, simple. Its this simplicity that causes some problems with getting your environment set up. There is documentation but to be honest its not that clearly laid out (I’m referring to the getting started stuff, not the class references).

So here are the steps I used to get an environment up and running.

First, you need to determine your primary development platform. I chose the PC because that’s the platform I want to focus on for my next game. This guide is therefore targeted at that platform.

Step 1: Tools

There isn’t a formal IDE for Moai as of yet. This means that your best bet is to choose your favourite programmers text editor and use that. Moai make reference to Notepad++ a few times in their documentation but I’m currently loving Sublime Text 2. As such, we’ll focus on getting that set up.

Download Sublime Text 2 here.

Step 2: Moai

Download Moai from here (required signup) and extract its contents to a folder on your system. I created a folder called “Development” in my user account area (so I ended up with C:\Users\Chris\Development\moai-sdk).

This folder will contain the Moai framework along with lots of sample projects.

Step 3: Setup a new project

Create a folder on your system for your projects. I opted for a folder called “Moai Projects” under my “Development” directory (this gave me C:\Users\Chris\Development\Moai Projects).

Next, copy a sample project from the Moai SDK directory to your projects directory. I went with “anim-basic” which can be found under “moai-sdk\samples\anim\anmi-basic”. Once you’ve copied it, you can now rename this folder in your projects directory (I renamed it test so I ended up with C:\Users\Chris\Development\Moai Projects\test).

Your new project folder will contain 3 files…

main.lua – this is the main lua script containing the code for the sample that we copied
run.bat – this is the batch file for running the game
moai.png – this is a resource used by the lua script for this particular sample

We’re still missing something. The config.lua file. I don’t yet know enough about Moia to know whether this file is likely to need to be changed on a per project basis or whether it can be shared across projects (the structure of the Moai samples directory suggests the latter). For now I feel more comfortable assuming it’s per project and placing it within our new project directory.

To do this, copy the config folder from the “moai-sdk\samples” directory.

You should now have a config folder containing config.lua under your new project directory (C:\Users\Chris\Development\Moai Projects\test\config).

Step 4: Setting up environment variables and modifying run.bat

Open Sublime Text 2, then do File -> Open Folder, and select your new project directory (C:\Users\Chris\Development\Moai Projects\test\).

You’ll see the 3 files mentioned above in addition to the config directory containing the config.lua file.

Click the run.bat file. Not much in here but we need to make some tweaks.

First lets setup the MOAI_BIN environment variable. Go to the windows control panel. Now navigate to system and advanced system settings. At the bottom of the dialogue box is a button titled “Environment Variables”. Click that and under User Variables, click “new”.

Call your new variable “MOAI_BIN” and enter the location of the moai executable. For me, that was “C:\Users\Chris\Development\moai-sdk\bin\win32”

For the new variable to take effect, I believe you’ll need to log off your system and log back in.

Back in Sublime text 2, we still need to modify the lua config file location. We could have created another environment variable but we’ve opted to place the config file in our project directory. So lets simply replace the relevant paths…

change this line…

if not exist “%MOAI_CONFIG%” (

to this…

if not exist “config\config.lua” (

and change this line…

“%MOAI_BIN%\moai” “%MOAI_CONFIG%\config.lua” “main.lua”

to this…

“%MOAI_BIN%\moai” “config\config.lua” “main.lua”

Okay. Now we just have to modify the config.lua file slightly.

Change this line…

package.path = package.path .. ‘;../../../src/lua-modules/?.lua’

to this…

package.path = package.path .. ‘;../../moai-sdk/include/lua-modules/moai/?.lua’

All we’re doing in all of these instances is changing the locations of the various components to reflect our setup.

Step 5: Running it

We should be able to run our sample application now. Open the windows command prompt, change directory to your new project folder (in my case, test) and type “run”. Voilà!

You can now edit the main.lua file to write your own code.

Step 6: Improving the environment

Sublime Text 2 has its own command line built in. As such, we can improve the build environment considerably.

In Sublime Text 2, navigate to Tools -> Build System -> New Build System.

Copy and paste this (all it does is launch the run.bat application)…

“cmd”: [“${project_path:${folder}}/run.bat”]

Now, Ctrl+S to save the file and call it something sensible like “Moai-Windows”.

Now set the new build system by navigating to Tools -> Build System and selecting your new build system (In my case Moia-Windows).

Now when you’re modifying main.lua, you can hit Ctrl+B to automatically run the program. You don’t need to open a separate command line any more.

Bonus Update

Here’s a video of my progress this afternoon. Not much to show but its the start of something and I’ve been impressed with both Moai and Lua.


I’m still learning and reading about the structure of Moai so I’ll likely write some follow-up articles as I learn more. If you spot anything stupid in this guide, or have any advice, then let me know in the comments :)