Moai SDK is an embeddable cross-platform game development SDK written in C++ and scriptable in Lua. You can use Moai to write games or apps, or you can embed Moai in other programs. You can also use Moai as an overlay in your apps.
Multiple build systems are supported in this project. Sourcecode is kept in a common folder. There is a separate folder for each build system in the project root.
For IDE build systems (Xcode, Android Studio, Visual Studio), reference projects are provided. Cmake is also supported for Android and HTML5.
Third party libraries are included as git submodules (in some cases). The rest are vendored in. As a rule, we do not make any code changes to third party libraries. If functionality must be configured or replaced, we use a header injection pattern to do so.
A goal of the project is one-step build for the reference binaries. We don't want users to have to download and configure dependencies, or build parts of the SDK in advance. If you open the xcode/osx project (for example) and click 'build,' then Moai SDK should build for you in its entirety. This goal isn't always realized across all platforms, but it is something we strive for and if you want contribute build process improvements, please keep this goal in mind.
The project's principal developer (patrickmeehan) primarily works on OSX these days. As a result, the xcode/osx project is typically the most actively maintained. (For major releases, we update and test all projects.)
pito is a command line toolbelt for automating some aspects of the project. pito is just a bootstrapper that use command line Moai to run lua scripts. To use pito, make sure moai-dev/pito is somewhere in your path. When you first run pito, if the Moai binary is missing, pito will attempt to build it.
At the Moai SDK project level, pito does very little beyond generating the HTML documentation for Moai's Lua interface and running some build scripts that can be used for CI. If you want to extend pito with other commands, type 'pito help' on the command line and you will see an explanation of how pito searches upward through the directory hierarchy for extensions.
- 3rdparty - Submodules and third party source.
- 3rdparty/contrib - Third party code snippets included in Moai.
- android-ndk - Android JNI build project.
- android-studio - Android Studio reference project.
- bin - Moai executables, organized by OS type, generated by the various build systems.
- cmake - Cmake build project.
- docs - Legal notices and attribution images. Run 'pito make-lua-docs' to generate API reference.
- legacy - Old stuff kept for reference. Unless you are a moai maintainer, you can ignore this.
- lib - Moai static libraries, organized by OS type, generated by the various build systems.
- pito - Moai command line utility.
- samples - Moai SDK desktop and mobile samples.
- src - All Moai SDK source code for Moai libraries and hosts.
- test - This is a legacy, Lua-based test runner. Will be replaced by Google Test.
- vs2019 - Visual Studio reference build system and reference project.
- xcode - Xcode build system and reference projects.
Be sure to check for README files in these folders.
Reference projects are the projects we use for day-to-day development work on Moai. We do not provide any kind of Moai project generator or IDE templates (though this functionality is somewhat provided by Cmake). The usage pattern for Moai is to copy one of the reference projects, manually update the paths to either the Moai source or libraries, and tailor it to your needs. This might sound onerous, but in our experience, if you know how to use the IDEs it should only take you a few minutes.
In the past, members of the community have provided extensions to pito that generate high quality IDE projects from project templates. We don't maintain these in moai-dev; the moai-community repository was created to hold them.
Start with command line Moai. Add moai-dev/bin/ to your path then run some of the samples. We try to keep these up to date, but don't always have time (though for official releases of the SDK they all should work).
The samples are very, very simple. You will find Moai to be unopinionated and low-level. It is very much intended to be an SDK. You can piece it together however you want to make your game or app.
Once you get the hang of using Moai, start your project using a window size that uses a resolution/aspect ration you are comfortable with. You can adapt this later to handle multiple resolutions and aspect ratios. It is fine to prototype on desktop; mobile support is robust enough that you can port your work once you have something going.
There's no official support for the project right now. Check the forums or see if you can get an invite to the Slack team.
If you have lots of money and want to hire someone to work on features for you or help you with your Moai project, you can try your luck by emailing 'moai-sdk' at fallguyconsulting.com.
- For any kind of serious app, you will need to figure out how to handle transitions yourself (screen-to-screen or level-to-level). There is no official way of doing this.
- Don't get too wrapped up in writing class systems of abstractions on top of Lua or Moai. At least not at first. A light touch is usually the way to go.
- Moai does not attempt to hide or abstract low-level graphics concepts. To get the most out of Moai, you will need to understand coordinate systems and shaders. Game development is hard. Our goal is to provide convenience, flexibility and power, not to simplify.
- You will eventually need to manage the garbage collector and hunt down objects that get left in scope. Don't worry: when you get there you will find that there are powerful mechanism in Lua and some memory analysis tools build in to Moai that will make this tractable.
- Once you understand Moai viewports and scale settings, you will understand how you can write your app to use a device-independent coordinate system. For 2D games, you will be able to update your assets to use higher or lower resolutions without changing object dimensions. In our projects, we typically use at our highest targeted resolution for all assets and downsample for lower resolution devices.
- Plan your letterboxing scheme early. You will want to decide up front if you will reposition UI elements or draw extra UI to avoid black bars.
- Prototype on desktop, but test (a bunch) on device, well ahead of release.