Improve this doc

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

Building Moai

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.

Install prerequisites

To build/rebuild the moai libraries ensure you have the prequisites for your target operating system installed:

Windows Requirements

OSX and iOS Requirements

  • Xcode 7+

Linux Requirements

  • CMake 3.1+
  • apt-get install cmake git-core build-essential libglu1-mesa-dev libxmu-dev libxi-dev libxxf86vm-dev libxcb-util0-dev

Android Requirements

HTML/JS Requirements

Configure the SDK

Once the prerequisites are installed, you will need to tell the SDK where to find all the pieces. In the 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 .template suffix. 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 env-win.bat or 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: build-windows, build-android, build-html
  • For Linux: build-linux, build-android, build-html
  • For OSX: build-osx, build-ios, build-android, build-html

build-windows, build-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\bin folder 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 src subfolder. lua print("Hello World")

You can run this now by typing moai from the src folder. You should see the Moai version followed by Hello World.

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.

pito: https://en.wiktionary.org/wiki/pito

Edit hostconfig.lua

pito uses a lua based config file hostconfig.lua to create host projects with the correct settings and correct lua src location. The 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>

where 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>

or 

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)

Done

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

Or

Update your hello world application you just made into a real game by following the Rocket Lobster tutorial