Getting started with Moai in 10 easy steps

Moai is a huge beast to tackle for a newbie, especially for people who are from the Windows background. I’d say Linux is the best operating environment to develop Moai based games. I am from the *nix background and i use a Ubuntu desktop at work for embedded C++ development. So the first question that came to my mind, when i came across Moai is whether i could use it in an environment that i’m most comfortable with. Two weeks later i can now use my Ubuntu based laptop to run the samples that come with Moai, create and view projects, debug my own moai applications, deploy projects to android,the works !!! I find this setup much simpler as compared to the hassles of installing Cywin and stuff for emulating a linux like environment on Windows. And so moving on quickly to the steps to replicate my setup on your machine..

1. Get a decent machine (Desktop/Laptop) – The best advantage of coding in lua is that there are no heavy compilation iterations that hog your cpu every time you change a string. So dont break a sweat even if your machine is slow. It should just be good enough for running a ubuntu distro, which i must say runs on pretty much anything.

2. Get Ubuntu 12.04 LTS from This is a strict pre-requisite.I had a 10.04 earlier and some of the dependant packages are just not available in the 10.04 repos. So unless you wanna sit down and compile each one of the missing Moai dependencies, 12.04 is the way to go.

3. Moai on linux is still a work in progress so there is no precompiled host and we have to compile it by ourselves. The process of compiling the Moai Linux host is already documented here – Just follow that guide to get the moai linux host compiled.

4. If you follow the guide there step by step, you should now have a (MOAI_DIR)/build/src/hosts/gluthost executable. Now on every other host like Windows or Mac, the name of the Moai executable is simply moai. But what you get here is gluthost. And this is the executable used to run your lua files.

5. Next step would be to obviously try out the installation. For that navigate to (MOAI_DIR)/samples/hello-moai/. Now please understand that the samples are seriously outdated. So before you come back saying that the samples are not working on linux please go through the sample that you are going to run and look for deprecated APIs (For e.g, pushRenderPass is deprecated,may or may not work on your host depending on your moai version). You can execute the sample like this

../relative/path/to/gluthost ../relative/path/to/optional/config.lua main.lua

The config.lua file may or may not be required for different samples. A generic config.lua file resides at (MOAI_DIR)/samples/config/config.lua. If you see a black window with the rotating image of a cat your Moai installtion is complete. Congratulations !!!

6. Using just a text editor to write code, managing multiple lua files and always using the command line to run your games is not everybody’s cup of tea. A better alternative is to use an IDE like IntelliJ, Eclipse,CPM over wine,etc. This provides you features like one key launch of your projects, debugging, code assist, etc. (Note – The use of an IDE is completely optional and some people prefer not to use them. If you are one of them, the rest of the tutorial is not of much use to you)

7. I found a wonderful code editor ZeroBrane studio. You can get a copy at the projects git repository at
Then Run (cd build and ./ to install wxlua and all its dependencies.
This IDE has been written in lua itself so you need to install lua in order to run the IDE.
sudo apt-get install lua5.1

8. To run the ZeroBrane IDE you need to cd to the ZB_DIR and execute
lua src/main.lua zbstudio &
For ease of use create a file, copy the above command in it and place it in ZB_DIR and do a chmod 777 This way everytime you need to launch the IDE you just need to do a ./ in ZB_DIR and you are good to go.

9. ZB studio requires a one time setup for use with Moai.

Go to the folder (MOAI_DIR)/build/src/hosts/
Create a symlink for gluthost by the name moai.(ZB studio recognizes moai and not gluthost)
ln -s gluthost moai
Next we need to create an environment variable that points to this moai binary.
Open ~/.bashrc and add the following lines there
export MOAI_BIN=”(MOAI_DIR)/build/src/hosts”
Replace MOAI_DIR with the absolute path to your Moai directory, save the file and restart the machine. (This way the moai binary will be picked up by ZB studio for executing your projects)
Launch the ZB studio, and change Project -> Lua Interpreter to Moai.
Done !

10. The ZB studio is now integrated with moai and and your basic game development enviroment is complete. To test the same, open ZB studio, click on the “…” icon in the project pane, navigate to the root directory of any of the sample projects and click open. Open the main.lua file and hit F6. This should run your sample project. (Note: For projects with multiple lua files, every time you try to run your project, make sure that main.lua is the currently active file.. ZB studio runs the current file and not the project. So if you are on xyz.lua ZB will execute ‘moai xyz.lua’ and you wont get the output desired.)


I have been looking around for tools/frameworks that makes the game creation easy. Here is a random list off the top of my mind.

1. Rapanui – High level framework that makes you do the same things that you could achieve with moai, but with lesser code –

2. Hanappe – Similar to Rapanui –

3. Tiled – Make tmx maps for map based games –

4. gimp – Make your game sprites/ textures –

5. PhysicsEditor – Make your own collision shapes –

6. TexturePacker – Make your spritesheets with great ease –

7. Doxygen – You can run this on your copy of the moai code to generate offline documentation for yourself –


Post any of your queries here and/or at The team there is really great and supportive.
I dont know what ill write about next, but i will, in about a weeks time. Till then, happy coding !!!

This entry was posted in Moai tutorials and tagged , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s