Marmalade Quick debugging with ZeroBrane Studio

Marmalade SDK is a cross-platform toolkit for developing games and mobile applications on a variety of desktop and mobile platforms. It also provides Marmalade Quick, a flexible programming environment based on Cocos2d-x with Lua scripting, which makes it a good fit to support in ZeroBrane Studio. Starting from v0.35, ZeroBrane Studio provides integration with Marmalade Quick and implements debugging support for Quick scripts; the video below demonstrates these capabilities (you may need to switch the video to 720p to make the text more readable):

The first thing you need to do is to open main.lua file from the project you want to work with (you can do this by using File | Open...) and then set the project directory to the directory with your main.lua file. You can do this by going to Project | Project Directory | Choose...
or using Project | Project Directory | Set From Current File.

To enable the integration shown in the demo, you need to select Marmalade Quick as an interpreter in ZeroBrane Studio by going to Program | Lua Interpreters | Marmalade Quick. If you installed Marmalade in the default location on OSX (/Developer/Marmalade) or on Windows (C:\Marmalade or D:\Marmalade, or in \Program Files\Marmalade), it will be found and used by the IDE. The IDE will also check for the Marmalade .MKB file in the project folder or its parent folder and will use the information from that file to set the environment for running your project.

After this is done, you can use Project | Run command to run the application. If there is a problem with finding the Marmalade Quick environment, you will see an error message in the Output window.

Enabling debugging

Add require("mobdebug").start() line to your main.lua script. This will allow you to use Project | Start Debugging to debug your application.

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). You may want to spend few minutes reviewing the Getting Started page to get familiar with debugging and other functions in the IDE.

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; you can configure the IDE to auto-open files you are trying to step into by setting editor.autoactivate = true in cfg/user.lua file (see configuration documentation and this configuration sample for details).

Selective debugging

You may notice that in some cases the application you are debugging runs slow; when you run it without the debugger the speed is likely to be at least ten times faster. This may be okay for some situations, but in many cases when the application is complex, things may get slow.

The debugger provides two methods that allow you to temporarily turn the debugging on and off. If you turn it on/off right around where the changes need to be applied, you can get almost the same performance you see without the debugger.

For example, you may want to break when a body collision is detected in Physics/Collision Events example. You can turn the debugging off at the end of main.lua script (require("mobdebug").off()) and then turn it on and off around the section you are interested in:

function bodyCollision(event)
    local target =
    if event.phase == "began" then
        require("mobdebug").on() --<-- turn the debugger on
        local c = director:createSprite(event.x, event.y, "textures/redcross8.png")
        c.xAnchor = 0.5; c.yAnchor = 0.5
        tween:to(c, {time=0.25, xScale=3, yScale=3})
        tween:to(c, {delay=0.25, time=0.25, xScale=0, yScale=0, onComplete=crossDestroy})
        require("mobdebug").off() --<-- turn the debugger off

If you set a breakpoint somewhere between on@ and @off calls, it will fire as expected. The rest of the application is running with a "normal" speed in this case (you can see the difference if you remove all off() calls).

Opening other files

You can step into functions and put breakpoints into other files (including those Lua files that are part of Quick itself), but they either need to be opened in the IDE or you need to configure the IDE to auto-open those files for you.

Known bugs and limitations

Some user events (like clicking on a button) may not reliably trigger breakpoints set in them (even though the event handler is executed as expected). This is likely to be fixed in the future; one possible workaround is to add require("socket").select = function() return {} end at the end of the main.lua script. Other non-user triggered events (like collisions) are not affected by this and should trigger a breakpoint every time the event handler is called. This has been addressed in Marmalade Quick 1.1, so the workaround is no longer needed.

Another current limitation is that it is not possible to break into a running application using Project | Break functionality. This will also be fixed in a future version. This has been fixed in Marmalade Quick 1.1 and ZeroBrane Studio 0.36+.

You should get a copy of my slick ZeroBrane Studio IDE.


Какие сочетания клавиш Вы используете?

@Борис, те же что и в меню: F10 - Step into, F5 - Start Debugging/Continue, Shift-F5 - Stop.

Все клавиши можно переназначить:


First of all many thank for all your hard work on Zerobrane Studio, very, very impressive!

I've been setting things up on my Mac and everything works great with Marmalade / Quick until I come to debugging.

I add in the required line for mobdebug (require("mobdebug").start()) and breakpoints seem to be hit but the simulator doesn't update its display at all so I can't see whats happening.

I've tried this on a Windows machine as well with the same effect. I also tried using Marmalade v6.0 and Quick 1.0 (I was trying with 6.2.2 & 1.0) as recommended on the Marmalade site but that didn't help as well.

I've tried following along like in your video and get the same results (display not updating in the Marmalade simulator). Any ideas or help?

If you need any more info please ask and I will provide.



@Peter, this may be a feature (assuming you can step through the code and I understand correctly what is going on).

breakpoints seem to be hit but the simulator doesn't update its display at all so I can't see whats happening.

When the application is suspended in the debugger (when a breakpoint is hit or when you step through the code in the debugger), it's not possible to refresh the application as it doesn't handle any events. In some cases you may be able to see what was on the screen (for example, when your app is not covered by ZBS window), but as soon as you move the window or switch apps (or do anything else that causes repainting the screen), the application will display "busy" status.

Let me know if I misunderstood what's going on.

Hi Paul,

Many thanks for your response.

To give you the extreme example if I take the 'Hello World' Marmalade Quick sample and add the moddebug start line at the top of the main.lua (like in your video) and then debug it the simulator stays 'stuck' at its default startup text, no breakpoints are set etc. When I remove it things work fine again. This is consistent with any other Marmalade Quick app.

I am also looking at GiderOS and when I switch interpreter the apps debug more how I would imagine, does this help?

Do you want me to send any logs or screenshots so you can get a better idea of whats going on?

Thanks again, hope its not a big thing as you have it working well in your video :)


@Peter, if you are using v0.36+ of ZBS, try adding the following code to your script (right before 'require("mobdebug").start()' call):

require("mobdebug").checkcount = math.huge

I'll update the documentation if this helps. I'm working with Marmalade on this issue and expect it to be resolved before the next version of ZBS and Marmalade is out.

Hi Paul,

Just tried on the Hello World sample and its working as expected now with the fix/workaround you detailed. Many thanks for your help, I'll keep my eye out for an update and send some 'support' your way should my mobile development stick with a Lua based engine (I'm evaluating a few things at the moment), great app by the way!

Thanks again

@Peter, The issue you've encountered has been fixed in Quick 1.1, so the workaround is no longer needed if you upgrade. This version also fixes some other issues (like "Project | Break" not working), so the debugging should be fully supported now...

Leave a comment

what will you say?