MOAI Tutorial – a step by step guide on how to start working with MOAI

We would like to introduce you to working with Moai with this comprehensive guide which is to teach you the basics of this program. Moai is getting more and more talked about in the circle of application and game developers. The reason for this is, that it’s a simple program and it’s easy to get started with it and work with it. We will try our best to be as clear with the instructions as possible, and we advise you to save the scripts for later use.

Who is this guide for?

While Moai is an easy program for newstarters we would advise everyone to attent a course on programming basics and have some prior experience with programming using other programs as this will make the tutorial a whole lot more understandable for you. All in all you need to be aware of the following:

  • Using Windows Commander
  • Using simple commands
  • Familiar with one programming interface
  • Familiar with one programming language and its use

What is Moai?

Named after the faces of ancestors on Eastern Island Moai or Moai SDK is a C++ game engine which has a cross platform and works with a scripting interface which is called Lua. Lua, just like HTML or Java is a scripting language, which is specifically used for Moai to write programs or games especially those which are geared towards smartphone users. More and more people use Moai to write simple games and then try to offer them either on iTunes or in Android store.

While we will not cover Lua this time around, the language is getting so popular that you will surely find tons of separate tutorials about it on the internet. Another good thing about Moai is that it’s free to use and it’s being worked on by pro developers as a free contribution, to make the whole program better.

How to install Moai?

There are several pages you can download the program from, Github is one of these. The pages may require you to sign up while proceeding with the download. After the download is complete unzip the program. Before concentrating on Android or IPhone let’s find a Windows host by opening Windows Commander and typing in the following command:

setx PATH “%PATH%;c:\moai-sdk\bin\win32”

 After this is done, exit the program, then open it up again and start the program. If all is installed correctly then you should see a small windows that says “Moai has installed correctly, check out the samples folder”

The samples folder is mainly for exercising and making friends with the programs language and on how to use it.

Now you have your Moai open, but you still cannot do much of anything with it. If you want to get started you need to make sure the development environment is up and it’s running. This is something that we advise it to be done by installing a helper, namely IntelliJ IDEA that’s available from several free resources with tons of step by step guides on how to use it. The most important is, that this will help you to connect to plugins namely Lua which you must connect to. After you are done with all these steps you need to restart the whole programs in order to be able to start a new Project.

You can go through tons of setting features in order to run the program in development mode. If you are not familiar with the process it’s best to ask for an advice from someone who is more familiar with programming.

Getting started:

First off we create a basic script then run it.

  1. Go to Projects – New – Lua script
  2. Enter your script there. In our case we borrow a script from

screenWidth = MOAIEnvironment.screenWidth

screenHeight = MOAIEnvironment.screenHeight

print(“Starting up on:” .. MOAIEnvironment.osBrand  .. ” version:” .. MOAIEnvironment.osVersion)

if screenWidth == nil then screenWidth =640 end

if screenHeight == nil then screenHeight = 480 end


viewport =



layer =




  1. Run your script via Tools – Moai- Run Moai
  2. And you will see a nice pink window opening up
  3. Save this script for you to have it for later use.
What this script is all about?

There aren’t many coordinates here, so the two key information to collect includes the following:

  • the actual size of the windows that’s been set to 640 pixels x 480 pixels
  • The color to be used which is pink ( color code 1,0.41,0.70,1)

Color codes are easy to collect from the internet as they are often used jointly by multiple programming languages.

As you can see, without having a basic knowledge in Lua, you won’t be able to do much of anything with Moai. Therefore we definitely suggest you to get that first if you are serious about programming with Moai. Similarly to all coding languages Moai has its own ways to “tell” what it wants and how it wants it to be run. Of course you can choose a different color code with different coordinates if you want to further experiment with this script.

Project Nr. 2:  Creating a greeting

This is another project excellent for newstarters. However it will seem complex, after you get more familiar with coding using Lua, you will understand more and more as to how Moai works.

The first step is to go to c:\windows\fonts\  and choose a font you would like your greeting to be, you will use that tff. file to give instructions as to which font should the program use for you. This can be arial.tff, courier.tff or any other font type of your choice.

After you are done, start a new script in Moai and paste the following script there:

MOAISim.openWindow (“Greetings”, 800,600)

Viewport =

Viewport:setSize( 800,600)

Viewport:setScale( 800,600)

layer =



chars = ‘DEHLORW’

font =


text =








What this script is all about:
  • We create a window
  • The window will have a viewport with the size 800 * 600
  • The viewport will have a new layer which we are to render
  • We give the command to feature “ Greetings”
  • We give the coordinates of the font type
  • We create a textbox with the set text with the font size 110×72
  • We then flip it because Moai inverts the text for unknown reasons.
  • We will position the text to be displayed in the middle
  • With “Insert prop” command we finish adding the textbox to the layer

Now, all you need is to run your script and if all goes fine the text “Greetings” should display right in the middle.

Getting in deeper:

We could enlist tons more examples for you and show you how to do this or that. But the fact of the matter is that without you knowing exactly what you do, you won’t really be able to get in deeper. This means, that you will need to have at least a basic proficiency in the use of the Lua language.

The beginner course also covers aspect on the following topics:

  • Drawing an image
  • Making an image touchable and clickable ( to react to clicking )
  • Creating buttons – configuring MOAIGUI

About MOAIGUI: if you want to indulge deeper in programming then you must find the way to have the latest GUI installed. GUI means graphical user interface and this is exactly what you need if you want to create reactive things such as clickable icons, buttons etc.

How to get the MOAIGUI?

You can either get it installed from a page like github. You can also find it somewhere in the samples folder of the default program but that can also be outdated so we suggest you to download the latest. We suggest you to have a git program also installed to keep track of these downloads and to make the copying to MOAI directory all the faster.

By using the following git clone you should be able to copy the GUI straight into your project file:

 And from this point on you can go ahead and start creating reactive objects.

Programming is a rather long and daunting process and you can only get to know more about this, once you start learning how to code. Of course, once you get on the level to use reusable scripts, things will get much easier. From then on, all you need to do is to change coordinates in the same script according to your own preferences.

Below is the script of how to create a 3 button layout with all 3 buttons being reactive to mouse pointing or hovering over:

 screenWidth = MOAIEnvironment.screenWidth

screenHeight = MOAIEnvironment.screenHeight

if screenWidth == nil then screenWidth =1280 end

if screenHeight == nil then screenHeight = 800 end


viewport =



package.path = ‘./moaigui/?.lua;’ .. package.path

require “gui/support/class”

local moaigui = require “gui/gui”

local resources = require “gui/support/resources”

local filesystem = require “gui/support/filesystem”

local inputconstants = require “gui/support/inputconstants”

local layermgr = require “layermgr”

local gui = moaigui.GUI(screenWidth,screenHeight)

gui:addToResourcePath(filesystem.pathJoin(“moaigui/resources”, “fonts”))

gui:addToResourcePath(filesystem.pathJoin(“moaigui/resources”, “gui”))

gui:addToResourcePath(filesystem.pathJoin(“moaigui/resources”, “media”))

gui:addToResourcePath(filesystem.pathJoin(“moaigui/resources”, “themes”))

layermgr.addLayer(“gui”,99999, gui:layer())



function onButtonClick(event,data)

label1:setText(“You clicked the button”)


function onLessProgressButtonClick(event,data)

local curProgress = progress:getProgress()

if(curProgress > 0) then




function onMoreProgressButtonClick(event,data)

local curProgress = progress:getProgress()

if(curProgress < 100) then




button = gui:createButton()



button:setText(“This is a button”)



progress = gui:createProgressBar()



progress:setText(“This is a progress bar”)

button2 = gui:createButton()



button2:setText(“Less Progress”)



button3 = gui:createButton()



button3:setText(“More Progress”)




label1 = gui:createLabel()



label1:setText(“Click the top button”)


function onPointerEvent(x, y)

gui:injectMouseMove(x, y)


function onMouseLeftEvent(down)

if(down) then






function onTouchEvent(eventType,idx,x,y,tapCount)


onPointerEvent(x, y)

if (MOAITouchSensor.TOUCH_DOWN == eventType) then


elseif (MOAITouchSensor.TOUCH_UP == eventType) then




if MOAIInputMgr.device.pointer then






 Once you know LUA more then you will be able to vary this script according to your own preferences. For now, it’s best to save it and use it for exercising purposes. What makes these programs hard to use for beginners is the fact that you need to go fishing for this and that and you need to have an experience in finding resources, connecting them with the program to make it work. But with time and exercise you will get into it and will see how much fun it is to work with MOAI.

Leave a Reply

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