Why and how to use Gideros with ZeroBrane Studio IDE tutorial

Why and how to use Gideros with ZeroBrane Studio IDE

In this tutorial we give a short introduction into development with Gideros (fast lua game programming cross-platform framework) using ZeroBrane IDE (a lua integrated development enviroment), which has advanced editing and debugging features. You will see how switching from the Gideros Studio IDE to ZeroBrane can make development with Gideros much faster. If you are new to Gideros, to start to develop your games in Gideros for free, go to Giderosmobile.com To download and install ZeroBrane IDE (ZBS in short), go here: Studio.zerobrane.com We note that ZBS is a general lua editor and debugger, so you can use it with other frameworks. Also, in it's homepage there are very good documentations and tutorials about how to set up and use it with Gideros and other frameworks. Thus, this article is not comprehensive, it rather wants to give a short introduction about how you can start to use Gideros and ZBS together, give some best practices and highlight my favorite features of ZBS. Most importantly it helps you to set up ZBS for multiple on-device testing and debugging, which otherwise is not straightforward to do.

Highlights of using Gideros with ZeroBrane

ZBS has great integrated Gideros support, my favourite features are simple but important ones:

• auto-completion
• fast jump to files and functions
• one click change to many IP addresses where you want to instant test your app -> fast testing on multiple devices (your pc, iphone, android tablet, whatever)
• small size and fast startup (compared to IDE's like eclipse)
• most features can be reached in many ways (by clicking on a button, from the menu, or pressing a shortcut key)
• find and replace (also in files), mass comment/uncomment, fold/unfold functions
• advanced debugging features (stack, watch, console)

Other features that make a difference:

• cross-platform
• live coding
• lot of customization options (color schemes etc.)

How to start a Gideros Project in ZeroBrane

We assume that you have Gideros installed and that you know the basics of it. Next, download ZBS from Studio.zerobrane.com and run it. A new Gideros Project cannot be made from ZBS, so you need to start Gideros and make your new project. However, almost everything else, like adding resources, etc. can be done from inside ZBS, so you need to start the Gideros IDE only whenever you want to export your project.Now in ZBS, you need to select this folder as your project. This can be done by clicking on the [...] button in the Project window or in the 'Project | Project Directory | Choose...' submenu. Select the folder of your Gideros project. If you like, you can use an example project that comes with Gideros. Note that with [...] you can easily switch at any time between your projects, and thus transferring code from one project to another is very easy.

Next, if it is not yet set, you have to set the interpreter of ZBS to Gideros. This is done by choosing the 'Project | Lua Interpreter | Gideros' submenu.

Now you are ready to run your project from ZBS. Just press the green Play Button in the toolbar. Or you can press F6 or F5 (run or debug run) or choose 'Project | Run' or 'Project | Start Debugging' submenu. If it does not run at first click, click again on the Play button after a while.

For more info on getting started, see here: Studio.zerobrane.com .

Small things that make your life easier

1. Jump to function

One very important feature missing from the Gideros IDE is that you can navigate much faster in a file by using the 'Jump to a function definition...' button you can jump to a given function in your file.

Also, you can fold/unfold functions with the +/- button at the beginning of the first line of the function definition.

EDIT: In the latest version of ZBS (as of 20.4.2015) this dropdown is replaced by the much more practical 'Outline Window' that you can switch on by clicking on 'Menu/View/Outline Window'.

2. Edit *.gproj file to add source files, assets etc.

Notice the project file (ending with .gproj) in your project folder. You can open it with ZBS and edit it directly, most things are evident how to do just by checking some other gproj files. This way you don't need to leave ZBS just to add a new file or new resource, you can even change project properties, like size, scaling, orientation. Still you should be cautious when editing this file directly.
For example adding a source file (*.lua) or an asset file (*.png etc.) is this simple:

<file source="bird.lua"/>

Debugging

1. Configuration

Note: to experiment with debugging, it's best to have a project like the 'Graphics/Bird Animation' example, that has some event triggered at every frame. This way it makes sense to pause the project, as it does not run only once.

If you add the following line into 'main.lua' somewhere at the beginning, you expect to have "hello" printed in the console, but it is not yet happening.

print("hello")

To use debugging features you need to add mobdebug.lua to your project. Do this in Gideros Studio IDE in the usual way (copy it from "ZeroBrane installation folder"/lualibs/mobdebug folder to your project folder and add it to your assets in Gideros IDE by right clicking on the project name in the project window and 'Add Existing files...'). Finally, right click on 'mobdebug.lua' in Gideros Studio IDE and click 'Exclude from Execution'. Now you can close Gideros IDE, you won't need it anymore.

In your 'main.lua' add the following line at the very beginning (before your previous print line):

require("mobdebug").start("192.168.1.100")  --comment out this line when running from gideros ide or exporting

The IP address should be the IP of the computer you are working on. In fact, you could just put

require("mobdebug").start() --comment out this line when running from gideros ide or exporting

if you only do local debugging, but later when you do on-device debugging, the IP will be needed. Now when running your project (press the green play button) in the 'Output' window you will see the line "hello" appearing.
Remember that when you export or run your project from Gideros IDE, you should comment out the above line which requires mobdebug! Alternatively, you can change the code to:

if pcall(require, 'mobdebug')
then
require('mobdebug').start("192.168.1.100")
end

This way it runs in both ZBS and the Gideros IDE, no need to comment/uncomment anything.

2. Debugging in action

Debugging is now easy, you can pause the program by clicking on the pause button next to the play button (or going to Project | Break submenu). After stopping, you can easily add or remove breakpoints at any line in you code by clicking either on the red button on the toolbar or next to the line number in your main editor window (or going to the 'Project | Toggle Breakpoint' in the menu or pressing F9) - a red dot will be shown at the lines in which you added a breakpoint.

You can step through the code using the Step Into, Step Over, and Step Out buttons next to the pause button on the toolbar. When you are done with a debugging session, you can resume running of your project by clicking on the play button (or F5 or 'Project | Continue').

Check values of variables in different ways in the Watch window, Stack window and Console window. When paused, in the Console window you can run lua code, so e.g. you can even change the values of variables during execution.

You can find further details about debugging at Notebook.kulchenko.com

Setup multiple devices for instant on-device testing and debugging

One of the best features of Gideros is that you can instant test your project on a device. The only drawback is that in the Gideros Studio IDE it's a bit tedious to switch between IP's of the devices. This can be done with one click from ZBS, once you made some preparations.

First you need to configure your project for debugging, in the previous section you can find how to do that (don't worry, it's simple). Once configuring debugging is ready, you also need to add socket.lua to your project, similarly as you did with mobdebug.lua. Do this in Gideros Studio IDE in the usual way (copy it from "ZeroBrane installation folder"/lualibs/ folder to your project folder and add it to your assets in Gideros IDE by right clicking on the project name in the project window and 'Add Existing files...'). Note that you can add socket.lua also directly by editing the gproj file. Finally, right click on 'socket.lua' in Gideros Studio IDE and click 'Exclude from Execution'. Note that you do not need to require socket.lua in your main.lua file!

Finally, open the 'main.lua' file of your project in ZBS and add these lines at the very beginning, e.g. before requiring mobdebug.lua (for each of your devices make a new line with its IP address):

  [set remote debugging at 192.168.1.101](macro:shell(ide.config.gideros = {remote = "192.168.1.101"}))
  [set local debugging](macro:shell(ide.config.gideros = nil)) 

Now comment out these lines by adding "--[[" before and "--]]" after them. When commented, the previous lines change to clickable macros, so in the ZBS editor you should see this:

--[[
  set remote debugging at 192.168.1.101
  set local debugging
--]]   

To test your app on local computer click on 'set local debugging'. Then click on the play button, Gideros Player should start automatically and the app should load up.
To test on your remote device, first don't forget to start Gideros Player on the device, then click on the respective line (e.g. on 'set remote debugging at 192.168.1.101'). Then click on the play button, and your app should load up on your device.

Note that on whichever device you test, you have all the debugging features detailed in the previous section.

Conclusion

I was not sure that for Gideros users using ZBS is evident or not, thus I made this tutorial so that more people get to know about this cool IDE. Also, configuring some features is far from trivial, this tutorial should help you to get started. Right now there is no other editor with all the above features that is integrated to work with Gideros in this level. And if you already have your favourite external editor, some of the things in this tutorial (editing the *.gproj file) still apply.
Don't forget, if you have questions or problems, you can reach Gideros experts on the Gideros forum Giderosmobile.com, who are always very helpful.
Finally, I express my thanks to Paul Kulchenko, creator of ZBS, who explained me in detail all the tricks of how to configure ZBS and Gideros.