Moai debugging with ZeroBrane Studio

Moai is an open-source 2D game engine for mobile development created by Zipline Games. The engine runs on various platforms (iOS, Android, Windows, Mac, and Linux) and is scripted in Lua, which makes it a natural fit to support in ZeroBrane Studio. The just released version of ZeroBrane Studio (v0.32) provides integration with Moai and implements debugging support for Moai scripts; the video below demonstrates these capabilities (you may need to switch the video to 720p to make the text more readable):

To enable the integration shown in the demo, you need to select Moai as an interpreter in ZeroBrane Studio by going to Program | Lua Interpreters | Moai. If your moai host executable is in one of the folders listed in PATH or is placed in MOAI_BIN folder, it will be found and used by the IDE. If the executable is in a different location, you may need to specify this location in cfg/user.lua file by adding path.moai = 'd:/lua/moai/moai.exe' (see cfg/user-sample.lua for details on how this is done). Make sure you include the name of the executable: if you specify a folder you are likely you get an "Access denied" error.

After this is done, you can use Project | Run command to run the application and Project | Start Debugging to debug your application. If there is a problem with finding the Moai executable, you will see an error message in the Output window.

Debugger functions

The debugger in the IDE provides access to all debugging functions you would expect: breakpoints, stepping in/over/out, the stack view (to access a stack trace and all local/upvalue values, including complex ones), the watch view (to evaluate arbitrary expressions), and the console (to run code fragments and modify values in your application while it is suspended in the debugger).

Two things to keep in mind: (1) you need to set a breakpoint before you start debugging your application, and (2) you can step through only those files from your application that have been opened in the IDE (to simplify the debugging interface).

Debugging callbacks

From the debugger's perspective, Moai has three different types of code fragments that are handled slightly differently in the debugger: (1) the main thread (this is the entry point of your application and all the other functions you call from it), (2) all the threads added in the application using or deprecated calls, and (3) callback functions configured using various setCallback calls.

The main thread and the threads registered through MOAICoroutine() calls are available for debugging by default (which means you can step through them and set breakpoints there), but callback functions are not (as you may or may not want to run them under the debugger as this may significantly slow down your application). To enable debugging of callbacks you need to add require('mobdebug').on() call to one of the callbacks; this needs to be done only once and as soon as it's executed, the debugging will be available inside callbacks. If you only want to enable it for a small fragment of your code, you can wrap that fragment into require('mobdebug').on() and require('mobdebug').off() calls. You can leave the calls in your code as when the application is running without the debugger, these calls don't do anything (they become a noop).

Entry point configuration

If your project includes a large number of files, you may not want to keep switching to main.lua (or whatever other entry point your Moai application has) to launch your application using the right file. To allow you to specify entry points for your projects, ZeroBrane Studio provides moai.entrypoints config option you can use to list possible entrypoints for your projects. If it's specified, the system will try to find one of the entry points (you can have several) in your current project and start running/debugging using that file. You don't even need to have the entry point file to be opened in the editor; if there is an error in that file, the details will be shown in the Output window.

Adding the following line to cfg/user.lua will register source/main.lua and main.lua as two possible entry points for moai projects:

moai = {entrypoints = {"source/main.lua", "main.lua"}}

If your project has main.lua, it will be use as the entry point during debugging or running the project in the IDE. If none of the entrypoints is found, then the current file is used (you will see a warning in the Output window in this case).

Download ZeroBrane Studio, open your project files in the IDE, and become faster at fixing your bugs and shipping your product.

You should get a copy of my slick ZeroBrane Studio IDE and follow me on twitter here.


Superb! ZeroBrane just became my lua/moai IDE of choice. Thanks for integrating MOAI debugging!

Thanks! Debugging works; I can set breakpoints, watch vars etc. However the moai glut window is black. This is on win7. Any ideas?

Another thing - it seemed to set the working dir to the dir of the moai exe, which prevented requires with relative paths from working. I made a fix to the (zerobrane) source, but is there a cfg/project option to set that?

cool stuff

@cd, the moai glut window is black when the application is stopped in the debugger because windows can't repaint the window (as the app can't handle events). When you do "Run" in the debugger, the window will be updated. You can see it if you position the two windows (IDE and Moai) side by size.

You don't need to set the working dir to the exe folder; in fact, the IDE should find moai.exe anywhere in PATH or MOAI_BIN. You can also configure moai path by adding "path.moai = 'd:/full/path/to/moai.exe'" to sfg/user.lua.

Your project directory should point to the project root to make the relative paths work.

Thanks for the quick response. There was no problem finding the moai exe, just that the dir of the exe becomes the working dir (I believe) and require() using relative paths didn't find lua files. Not a big deal and solvable by adjsuting the lua path - I just thought that having a 'working dir' cfg/project option could be useful. (and/or that the working dir should be from the main.lua not the exe dir)

The other issue (black screen) is independent of debugging and occurs on two machines (both win7 laptops) for me. It happens when using the zerobrane exe installer and with the zerobrane github project. And just running moai samples. Nothing special. Unmodified moai, freshly installed zerobrane. Moai latest, moai not latest etc.

A clue may be in that samples/amim/anim-curve-draw shows up fine.. but the rest are black. Perhaps because it uses drawing functions?

@cd, I've seen the black screen when Moai can't find project resources, for example, a png image of the background.

Can you open main.lua in one of the samples, and then set the project directory to the folder with that main.lua file? The simplest way is to click on a button with a small arrow in the toolbar, on the left side of the "jump to a function definition" dropdown. Then run the script and see if this fixes the black screen.

sorry, disregard the relative paths part. I didn't read your answer thoroughly enough :)

Problems solved! Thanks!

Looks like a great tool! I'm running on OSX and being a semi-newbie to the mac, it took me a some googling in order to figure out where the cfg/-folder was located. For reference, it is found by expanding the ZeroBraneStudio application in the Applications folder (that is, "right-click" and choose "Show package contents". From there it should be relatively easy to find the config file, so setting up the moai path should be quite straigthforward.

I do have a problem, however. I get the following error when I try to run:

Program starting as '"Users/myuser/moai-dev/moai-dev/bin/osx/moai" "/Users/myuser/projects/main.lua"'. Program 'moai' started in '/Users/myuser/projects' (pid: 775). execvp(Users/myuser/moai-dev/moai-dev/bin/osx/moai, /Users/myuser/projects/main.lua) failed with error 2! Program completed in 0.23 seconds (pid: 775).

Do anyone know how to resolve this? On lead I haven't been able to follow up is that it might complain due to the fact that I haven't passed in the standard config.lua that is shipped with the moai samples. Any help would be greatly appreciated!

Joar, "error 2" may mean "file not found"; this may be caused by you using a relative path instead of an absolute one. If your path is correct, try "/Users/myuser/moai-dev/moai-dev/bin/osx/moai" instead of "Users/myuser/moai-dev/moai-dev/bin/osx/moai" (note the first slash).

I'll add better reporting in those cases when the path to the executable is incorrect.

Thanks Paul! That was it. :) I must admit that I was certain I had tried that already ... oh well. Now it works, can't wait to have stacktraces etc. running. Thanks again! :)

Thank you, it's great job. but i encounter some problem with configuring this nice tool,and my interpreter is MOAI on windows 7. i have running debuging, get the following result from output window:

Program starting as '"D:/Dev/MOai/4MoaiSCAppsEagle/3rdparty/HostWin/moai-untz.exe" -e "xpcall(function() io.stdout:setvbuf('no'); require('mobdebug').loop('1234-PC',8171) end,function(err) print(debug.traceback(err)) end)"'. Program 'moai-untz.exe' started in 'D:\Dev\MOai\4MoaiSCAppsEagle\' (pid: 5100). Assertion failed: *pos != -1, file ....\src\hosts\FolderWatcher-win.cpp, line 76 Program completed in 2.52 seconds (pid: 5100).

Hi haochao, this error doesn't look like anything that may come from the IDE: "Assertion failed: *pos != -1, file ....\src\hosts\FolderWatcher-win.cpp". Does your game run without problems when you started it directly (without using ZeroBrane Studio)?

Is it possible to add auto complete for the frameworks that run on top of Moai like Rapanui SDK and Hanappe framework?

I like it a lot so far and it run very light and quick too.

@Skaflux, it is definitely possible, but someone has to put their APIs into the format that ZBS recognizes. For some APIs this is done manually, for others I have written scripts to convert. For example, for love2d I converted from another Lua format and for moai I converted from .h/.c files. You can see the format and the scripts in api/lua/ folder.

Thanks . I'll look into the scripts.

Question: I use Ubuntu. When I right click on a Lua or any other text file I can select "open with zerobrane" but what opens is a blank untitled file on zerobrane. Can you look into that?

@Skaflux, I'll need to take a look at this. ZBS executables and shell scripts all accept filenames and will open them in the editor.

@Skaflux, it turned out the Linux launcher doesn't pass the parameter to the IDE. I fixed it in the repository; you can add missing "$@" to /usr/bin/zbstudio script.

My app starts with two lua files.

moai randomstuff1.lua main.lua

Like this. How do I get it to run and debug from zerobrane?

Hello, I tried to test the debugger on to the simple moai sample included in the ZeroBrane solution.

I had this message.

Program starting as '"C:\Program Files\moai\moai.exe" "D:\DOCUME~1\ALLIONEP\LOCALS~1\Temp.1D8.tmp"'. Program 'moai.exe' started in 'F:\zerobrane\myprograms\moai-samples\live-coding-simple' (pid: 6492). F:\zerobrane\lualibs\mobdebug\mobdebug.lua:865: attempt to call a nil value

The result is the same when I run as Scratchpad. The problem doesn't seem to come from the moai script but from the IDE or its confirguration.

Is someone can help me ?


@allione, What version of ZBS and Mobdebug are you using? You can see both on 'Help | About' screen.

Have you tried on a simple sample that comes with Moai or ZBS (myprograms/moai-samples/)?

It does seem like the issue is with ZBS, but I haven't seen this before. Any additional information to reproduce it may help...

My app starts with two lua files. moai randomstuff1.lua main.lua How do I get it to run and debug from zerobrane?

@Cathryn, ZBS doesn't currently support calling multiple files (although this support is planned); what you can do is to use config.lua file, which is supported with Moai. If you put config.lua file in your project folder or into your folder with moai executable, it will be used when your scripts are executed (exactly as you indicated).

@Cathryn, it occurred to me that if your first file name is always the same, you can use path.moai configuration setting that sets full path to moai executable to pass that additional script name:

path.moai = [["c:\program files\moai-sdk\bin\moai.exe" randomstuff1.lua]]

Hi Paul, I've tried debugging Moai (1.40p) with ZeroBrane0.361 on OSX, and it didn't work. I've set the breakpoints, but the app would just run normally and not stop at any breakpoint. The console output: `Program starting as '"/Volumes/DATA/00LIB/MOAI/1-40DISTR/bin/osx/moai" "/var/folders/2c/1pwt6trx421593t6w46f0kw0000gn/T/.9CAgRZ"'. Program 'moai' started in '/Volumes/DATA/02PLAY/P1313MOAI BASE/lua' (pid: 594). Debugging session started in '/Volumes/DATA/02PLAY/P1313MOAI_ BASE/lua/'.

Debugging session completed (traced 0 instructions). Program completed in 3.72 seconds (pid: 594).`

I tried debugging Corona and it worked. I've seen that the require ("moddebug").start() was required to debug Corona, but didn't see anything like this in this Moai debug tutorial (I tried this line with Moai and it didn't work anyway).

ALSO: Is it possible to disable zooming in/out in the editor (changing the font size)? The reason: I am working with a Wacom tablet, and the app goes wild and zooms in out uncontrollably without me doing anything.

Thanks N


I can't reproduce the issue with breakpoints on OSX. I installed the same version of Moai and all the breakpoints are working as expected for me.

Are you trying to set breakpoints in callbacks by any chance? Those require special handling (see "Debugging Callbacks" section earlier on this page).

Moai is started/debugged in a different way from Corona, so "require('mobdebug').start()" is not needed there.

Is it possible to disable zooming in/out in the editor (changing the font size)?

Yes, set "editor.nomousezoom=true" in the config file (; see example in cfg/user-sample.lua.

The book by Francisco Tufró explicitly mentions that one should add:

-- MOAI Path path.moai = '~/moai-sdk/bin/osx/moai'

to user.lua in cfg, but this causes "bla-bla error 2!" ...

@Peter, try using the full path with the executable (without ~); I don't think ~ is expanded in this context. Error 2 in file operations usually means "file not found".

Leave a comment

what will you say?


I am Paul Kulchenko.
I live in Kirkland, WA with my wife and three kids.
I do consulting as a software developer.
I study robotics and artificial intelligence.
I write books and open-source software.
I teach introductory computer science.
I develop a slick Lua IDE and debugger.