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 :)


  1. Todd says:

    Chris – great article – thanks for sharing your impressions of Moai!

  2. Chris says:


    No problem. Thanks for taking the time to leave a comment :)

    I’m liking Moai more and more as I use it. Hope it continues to be developed and gains a large community.

  3. Brian says:

    Hey Chris, so are you working on another project in addition to the puzzle RPG, or what?

  4. Chris says:


    Yep this is absolutely in addition to my puzzle RPG. This is very much a side project (its acting as a creative break and preventing me from burning out on my main game).

    I should hopefully have another post up soon about my main game :)

  5. doglobster says:

    Thanks for this – one thing, typo in the build system script:

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

    (The double-quotes were screwy and the forward-slash before “run.bat” isn’t required.

  6. Thanks for the tutorial. I think I’ve got everything running OK, but I’m still not 100% clear on how the environment variables are set up here.

    I went ahead and added a second environment variable to point to my config folder, as the github instructions suggested. As far as I understand, if I were to use your method, I’d have to copy the config folder into each sample folder in order to view the example code in action. What’s the advantage to copying and adding it in this manner instead of setting a second environment variable?


  7. Chris says:


    You’re correct. Using my method you would need one config.lua file per project. At the time I wrote this post I wasn’t sure if the file would ever contain project specific settings which is why I placed it in the project directory.

    The way you’ve done it will work perfectly fine and is probably more maintainable.

    Thanks for reading the post and for commenting :)

  8. RITESH says:

    your tutorials were awesome..and i enjoyed doing it but during this an error message comes to the CMD screen which is stated below..

    WARNING: The MOAI_CONFIG environment variable either doesn’t exist or it’s
    pointing to an invalid path. Please point it at a folder containing config.lua.

    please help me as i am not able to overide it……


  9. Neha Mehra says:

    Hello Christopher,

    My name is Neha and i work for Packt Publishing. We have recently published a book on MOAI SDK and I was wondering if you would be interested in writing a public review of the book. You can read more about the book on

    Kindly get in touch with me on the mentioned mail address.

    Thanks & Regards,

  10. Jeff says:

    according to the github readme, this getting started guide is out of date. The environmental variable is not located in the place described.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.