Getting setup with Moai

Installing the SDK

Moai’s website has most of what you need to get started.  You’ll need to sign up to get to the download link, which is free.  Moai is actually a few other services along with the middleware for game development.  The part you are looking for is the Moai SDK.  The other services are related to cloud services, which start free but ramp up as usage increases.  I haven’t really looked into that part of things, but it might be something to consider in the future.  Once you download the SDK, unzip it somewhere.  I ended up putting it into a subdirectory of “My Documents”, since there are a lot of .bat files in the samples directory, and Windows 8 complains if you try to run new things out of the “Program Files” directory.  In the end it shouldn’t really matter where you have it unzipped.

Running the Samples

At this point you might be curious and try to run some of the programs in the samples folder.  You are really running .bat files, which execute the main moai.exe host along with the .lua files in each sample directory.  The SDK contains precompiled versions of moai hosts for a few different platforms.  You’ll find that only some of the samples work as is, since they reference the moai.exe host with a relative path.  However, some samples reference a environment variable to find the host, so you’ll need to get that defined.  In the Control Panel / System / Advanced system settings, there should be an “Environment Variables” button.  Open that up and define 2 new system variables at the bottom.

  • MOAI_BIN should point to the directory that the host exe lives in.  This should be the directory of the SDK, and then in bin/win32.
  • MOAI_CONFIG should point to the directory of your config file, which is in the SDK, and then in samples/config

Now the rest of the samples should work, so you can play around with them.

Choosing an IDE

I tried some of the IDE’s that people mentioned in various tutorials, and here’s an overview


This is the free text editor I usually use for plain files, and there is support for syntax highlighting and a project structure.

Sublime Text 2

Sublime Text is similar to Notepad++ in that it’s a pretty basic text editor.  It isn’t really free, it’s more like shareware that never expires.  In addition to the stuff Notepad++ does, it also allows you to specify a way to run files (a configuration file that tells it what command line to run when you hit F5).

IntelliJ IDEA

IntelliJ IDEA is a commercial program meant to develop code.  It is by JetBrains, who also makes Resharper, I tool I use every day in Visual Studio.  It does more stuff than the basic text editor, and there is even a way to get Moai library auto-complete.  It does get pretty pricey for commercial use though.

ZeroBrane Studio

This is a smaller scale IDE meant just for Lua development.  It is a pay-what-you-want model, and available on Windows/Mac/Linux.  In addition to the stuff the text editors do, it does Moai specific auto-complete (though I’m not sure its context sensitive – if you start typing a function name, it will give you all the options no matter which class you are calling it on), and even lets you debug your scripts.  You can set breakpoints, examine the call stack (which also includes all variables defined at each level) and watch certain variables.  It can also detect when your MOAI_BIN environmental variable is set, and run whatever script you are currently editing.  I ended up choosing this one since it does more than the text editors, but is at a reasonable cost.  A few notes about it:

  • Instead of managing project files, it treats a folder as a project and shows all the files in there.
  • You can change your color theme by creating/editing a file in the configuration folder.  There are directions if you open up the subfolders of the installation.
  • When you hit “Run”, it will just pass your currently opened file to moai.exe.  If you are using multiple files create your game, you will always have to go back and select your main one before hitting F5.  Update – Paul, the writer of ZenBrane Studio writes in to add that you can set it to automatically run a specific .lua file by setting it in the config file.  You need to add this line to your user.lua file in the installation cfg directory – moai = {entrypoints = {"source/main.lua", "main.lua"}}.
  • In the menus, you can choose your Lua interpreter.  Select Moai here.

Setting up a Working Directory

To actually get working on a project, I ended up copying the files I needed out of the SDK install and consolidating them into a smaller directory.  Basically you need the host files (moai.exe and glut32.dll for Windows, moai for Mac), a main Lua file, and the .bat (Windows) or .sh (Mac) scripts to call the host with the Lua file.  Once these are all copied into a single directory, you can easily distribute everything you need to get your stuff running on any computer.

Now that you are all setup, we are ready to actually start working on something.  In the next post I’ll go over the basic boilerplate Lua code you’ll always need, and then start explaining some interesting things about the actual Lua language.


2 thoughts on “Getting setup with Moai”

  1. Nice write-up! Just one quick comment on ZeroBrane Studio. You wrote “If you are using multiple files create your game, you will always have to go back and select your main one before hitting F5.” There is a way to simplify this as you configure Moai “entry points” that will be recognized by ZBS. I have posted details here: (“Entry point configuration” section). Feel free to email me or ping me in #zerobrane on freenode with your feedback or if you run into any issues with ZBS. Paul.

Leave a Reply