Moai SDK Desktop Basics
The community SDK bundles a tested version of libmoai and a suite of tools to allow you to quickly create moai projects and export to multiple platforms.
Start by grabbing the latest Community SDK for your platform from here
The community releases for windows and osx include a precompiled moai desktop binary in the bin folder to help you get started quickly. You can add the bin folder to your path and you will be able to run any Moai script from any folder.
While you can use the moai desktop binary provided to run your moai lua code, you will eventually want to build your own host. Building your own host is required to run and deploy your project on other platforms (android, ios, html) or to customize the desktop version with your own icon and customisations or in preparation for submission to an app store.
To build/rebuild the moai libraries ensure you have the prequisites for your target operating system installed:
OSX and iOS Requirements
- Xcode 7+
- CMake 3.1+
apt-get install cmake git-core build-essential libglu1-mesa-dev libxmu-dev libxi-dev libxxf86vm-dev libxcb-util0-dev
Configure the SDK
Once the prerequisites are installed, you will need to tell the SDK where to find all the pieces.
scripts folder of the SDK, there is a
env-local.(bat|sh).template file which contains the
environment variables that the SDK uses to find its prerequisites. Create a copy the file and remove the
Edit the values in there to point to the required locations. Note that not all of the variables are mandatory.
Build Libmoai for your platform
The first step is to compile libmoai for your desired platforms.
From the SDK/scripts directory run
source env-osx.sh or
source env-linux.sh to setup your environment.
To build the library for each platform run the corresponding
build-xxxxx file in the script folder:
- For Windows:
- For Linux:
- For OSX:
build-linux also build the basic SDL host for the platform as well as the libraries
Create A Project
You now should have a Moai binary for your current host and a libmoai built for each platform.
We can use the
pito command to manage our projects and hosts going forward.
To create a project with pito:
- Ensure that the
sdk\binfolder is on your path.
- Find or create a folder (with no spaces in the path) to place your moai project
- Create a new project using
pito new-project <project-name>
- cd into
<project-name>folder to see the new project.
Write and Run your game code
With the project setup, you can write your lua game code. Put a main.lua file in the
You can run this now by typing
moai from the src folder. You should see the Moai version followed by
Create project specific hosts
Although you can just use the moai binary from the sdk to ship your product, the odds are you will want to create a custom host.
Managing and building these per platform hosts can be a headache and repeating the process for each project can get annoying.
Thankfully this sdk provides a set of utility scripts to help with building and creating moai projects called
pito uses a lua based config file
hostconfig.lua to create host projects with the correct settings and correct lua src location.
hostconfig.lua file in your project directory contains default settings for each platform, and should be edited to setup the name, source location, icon etc for the project you wish to build.
Creating a host project for a platform
You can create (or recreate) a host project for a particular platform by running
pito host create <host-name>
host-name is the name of the host you want to create (normally named after the target plaform). For a list of supported host-names run
pito host list
The created host will be in a subfolder called
hosts\<host-name> in your current project.
Customising the created host project
To customize the created host, you can just edit the files in
hosts\<host-name> using either the ide (xcode, visual studio, android studio) for the project, or just with a text editor.
A better option (when applicable) is to just update the
hostconfig.lua with new values and run
pito host create <host-name> again.
This will remove your old
hosts/<host-name> folder and create a new host with new settings.
The advantage of this method is that you can recreate your host projects after updating the moai sdk to get all the latest fixes or customisations you have made to the sdk.
Building the created host projects
To build the created hosts you can launch the created project in the relevant ide (xcode, visual studio, android studio) or you can run
pito host build <host-name>
pito host run <host-name>
These scripts will create the host if it doesn't exist, then build it using the build.sh|bat script in the host directory.
The run command will also call the run.bat|sh script in the host directory (if available) to launch the build application.
NB You may need to ensure you environment is configured via the
env-xxxx script again)
You can now build moai from source and create games. You have full control over your build. Time to grab your favourite editor, IDE and produce that next/first title.
Brush up on how the Moai SDK works from a lua perspective by reading the basics
Update your hello world application you just made into a real game by following the Rocket Lobster tutorial