The first thing we will do before building our application using Gideros is, setting up the environment and trying it out. We will need to download the latest version of Gideros designed specifically for your operating system, install it, create a project with some test code, and run it on both a computer and your mobile device.
As Gideros operates separately from Android or iOS SDKs and does not need them (context: Android or iOS SDKs) for testing or exporting apps, it is assumed that the user already has those SDKs installed; thus, it will not be covered in this chapter.
This chapter will guide you step by step on how to install Gideros on your operating system and prepare everything so you will be ready to develop your mobile game. This chapter will also introduce you to some of the basics of using Gideros Studio, managing your project, and running simple code.
Here is a list of links that might help you resolve any problems you might encounter with Gideros:
Gideros Developer Guide: http://giderosmobile.com/guide
Gideros API Reference: http://docs.giderosmobile.com/reference/
Gideros Documentation: http://docs.giderosmobile.com/
Gideros Developer Wiki: http://www.giderosmobile.com/DevCenter/
Gideros Knowledgebase (FAQ): http://members.giderosmobile.com/knowledgebase.php
Gideros Community Forum: http://giderosmobile.com/forum/
The following topics will be covered in this chapter:
Explaining what is Gideros and why you should use it
Installing Gideros on Windows/Mac OS X/Linux
Installing Gideros Player for on-device testing (Android, iOS)
Creating a new project and running it on both, the desktop and device
Providing the basics of coding in Gideros
Managing the project files
Managing the project settings
Exporting a Gideros project to Android or Xcode projects
Gideros is a set of software packages created and managed by a company named Gideros Mobile. It provides developers with the ability to create 2D games for multiple platforms by reusing the same code. Games created with Gideros run as native applications, thus having all the benefits of high performance and the utilization of the hardware power of a mobile device.
Gideros uses Lua as its programming language, which is a lightweight scripting language with an easy learning curve and it is quite popular in the context of game development.
Its rapid prototyping and fast development time by providing a single-click on-device testing that enables you to compile and run your game from your computer to device in an instant
A clean object-oriented approach that enables you to write clean and reusable code
Additionally, Gideros is not limited to its provided API and can be extended to offer virtually any native platform features through its plugin system
You can use all of these to create and even publish your game for free, if you don't mind a small Gideros splash screen being shown before your game starts
Currently, Gideros has no registration requirements for downloading its SDK, so you can easily navigate to their download page (http://giderosmobile.com/download) and download the version that is suitable for your operating system. As Gideros can be used on Linux only using the WINE emulator, it means that even for Linux you have to download the Windows version of Gideros.
So, to sum it up:
Download the Windows version for Windows and Linux OS
Download the Mac version for OS X
Gideros consists of multiple programs providing you with a basic package needed to develop your own mobile games.
An offline copy of the Gideros documentation and Reference API to get you started
1 GHz processor
1 GB RAM
210 MB disk space for MS Windows
340 MB disk space for Mac OS X
64-bit Snow Leopard version or later for Mac OS X
Gideros does not require the Android or iOS SDK's to develop, run, and export your app projects, thus you could build your app on Windows for both iOS and Android platforms. But you will require those SDKs after exporting, when you will want to build and submit your apps to the proper market.
Although installing and setting up those SDKs is not part of this chapter, let's examine what you need for each platform to build an exported project and submit them to the markets.
Apple Developer License
To build your app for the Android platform you will need the following:
Java JDK compatible with Android
Android SDK 2.2 or higher
Android compatible IDE (as Eclipse + ADT or Android Studio)
To install Gideros on your Windows operating system, download the Windows version of Gideros from http://giderosmobile.com/download. Then double-click on the downloaded
.exe file to launch the installation wizard.
The next dialog will allow you to choose the directory where you want to install Gideros. You may provide any directory you want by clicking on the Browse button and navigating to your desired directory, or leave the default value and proceed by clicking on the Install button.
After that, the Gideros installation will start copying all the needed files and you will see the progress bar filling. When it completes, there will be a Completed message displayed and you may click on the Close button to finish the installation.
After that, you may launch Gideros Studio from your provided install location or from the Start menu, if you had chosen the default option to create shortcut there.
To install Gideros on your Mac OS X, download the Mac version of Gideros from http://giderosmobile.com/download. Then double-click on the downloaded
.dmg file to mount it.
After that, all you have to do is to drag-and-drop the Gideros folder into your
Applications directory. It will create a Gideros folder inside your
Applications folder, where you will be able to access all Gideros-related files and programs.
There is no Linux-specific version of Gideros, but it is possible to use a WINE emulator to run the Windows version of Gideros on Linux. If you don't have WINE already, you can install it using the
apt-get install wine command or if you are using the Software Center, you can simply do the following:
Open Software Center
After that, you can download the Windows version of Gideros from http://giderosmobile.com/download.
Then, in the command line, navigate to the folder where you downloaded Windows installer and type
Then, to launch a specific Gideros application, for example, Gideros Studio, you need to navigate to the directory where Gideros was installed (typically,
/home/USER/.wine/drive_c/Program Files/Gideros/) and type the following command:
After you have downloaded and installed Gideros, you can try to create your first Gideros project. Although Gideros is IDE independent, and lot of other IDE's such as LuaGlider, ZeroBrane, IntelliJ IDEA, and even Sublime can support Gideros, I would recommend that first-time users choose the provided Gideros Studio. That is what we will be using in this book.
You should note that I will be using the Windows version for screenshots and explanations, but Gideros Studio on other operating systems is quite similar, if not exactly the same. Therefore, it should not cause any confusion if you are using other versions of Gideros.
Create New Project
Access offline the Getting Started guide
Access offline the Reference Manual
Browse and try out Gideros Example Projects
Go ahead and click on Create New Project, a New Project dialog will open.
Now enter the name of your project, for example,
New Project. Change the location of the project if you want to or leave it set to the default value, and click on OK when you are ready.
But first let's draw our attention to the Project pane, where you can see your chosen project name inside. In this pane, you will manage all the files used by your app.
One important thing to note is that file/folder structure in Gideros Project pane is completely independent from your filesystem. This means that you will have to add files manually to the Gideros Studio Project pane. They won't show up automatically when you copy them into the project folder.
This feature gives you the flexibility of managing multiple projects with the same code or asset base. When you, for example, want to include specific things in the iOS version of the game, which Android won't have, you can create two different projects in the same project directory, which could reuse the same files and simultaneously have their own independent, platform-specific files.
Like in many Lua development environments, an application should start with a
main.lua file; so name your file
main.lua and click on OK. You will now see that
main.lua was added to your Project pane. And if you check the directory of your project in your filesystem, you will see that it also contains the
So let's try it out. Write a simple line of code:
What this line will do is simply print out the provided string (
Hello world!) inside the output console.
Now save the project by either using the File menu or a diskette icon on the toolbar and let's run this project on a local desktop player.
Additionally, the desktop player provides different customizations:
You can make it appear on the top of every window by navigating to View | Always on Top.
You can change the zoom by navigating to View | Zoom. It is helpful when running the player in high resolutions, which might not fit the screen.
You can select the orientation (portrait or landscape) of the player by navigating to Hardware | Orientation, to suit the needs of your app.
You can provide the resolution you want to test your app in by navigating to Hardware | Resolution. It provides the most popular resolution templates to choose from.
You can also set the frame rate of your app by navigating to Hardware | Frame Rate.
Resolution selected in Gideros Player settings corresponds to the physical device you want to test your application on.
All these options give you the flexibility to test your app across different device configurations from within one single desktop player.
Now when the player is launched, you should see that the start and stop buttons of Gideros Studio are now enabled. And to run your project, all you need to do is click on the start button.
You might need to launch Gideros Player and Gideros Studio with proper permissions and even add them to your Antivirus or Firewall's exceptions list to allow them to connect.
The IP address and Gideros version of the player should disappear and you should only see a white screen there. That is because we did not actually display any graphical object as image. But what we did was printing some information to the console. So let's check the Output pane in the Gideros Studio.
As you see the Output pane, there are some information messages, like the fact that
main.lua was uploaded and the uploading process to the Gideros Player was finished successfully; but it also displays any text we pass to Lua
The Output pane is very handy for a simple debugging process by printing out the information using the
Now when we know what an Output pane is, let's actually display something on the player's screen.
stage is the root of the hierarchy of the objects we want to display on the screen. So anything you want to display on the screen, you need to add it to the
stage variable or to any of the child elements that have been added to
Another thing to note is the coordinate system used by Gideros. It is the Cartesian coordinate system with (0, 0) coordinate in the top-left corner. And objects with higher y-axis value will be placed lower.
Gideros uses the Cartesian coordinate system, where the values of the y axis increase downward, thus making (0, 0) coordinate appear in the top-left corner, and (0, 100) coordinate appears below it.
Since this chapter will include more coding examples, every time you get lost and don't know how to use any specific class (what method the class has, which parameters it takes, and what is the purpose of the class), you can get more information in the reference manual provided with the copy of Gideros. You can easily locate it under the Help menu by selecting API Documentation. It should open a webpage with the list of all Gideros classes, and also their methods, properties, and events for each class, to show you what it does and how to use it.
The first thing we will display is simple text. To do that, we need to create an instance of the
TextField class, which would represent our text on the screen. Usually, we need to provide a font and text to the
TextField class, but in this situation, we will simply provide
nil instead of font. This is because we don't have any fonts yet and
nil will tell Gideros that there is nothing we want to provide as font, and
TextField would use the internal Gideros system font.
local text = TextField.new(nil, "This is a simple text") text:setPosition(10, 20) text:setScale(2) stage:addChild(text)
After that we store the instance of
TextField in the local variable named
We then set the position of the text we want to display. By default, the position coordinate is (0, 0), which is in the upper-left corner. But we provide a small
(10, 20) coordinate offset because text is positioned by the baseline and it won't appear whole at (0, 0) coordinates, but rather be a little outside the screen.
Once the position is set, we scale the text twice as large as it is in the original, because the default font in Gideros is quite small.
In the end, we add the text to the
stage variable, which will render this text on the screen.
Now let's try and run this modified project again by clicking on the start button inside Gideros Studio. If everything is right, you will see in the
Output pane that
main.lua is being uploaded again and the provided text should appear on the screen of Gideros Player.
The next thing we will try to display on the screen is a simple image. For that purpose, you can use any image you have (or use the one provided in code examples); I will be using
ball.png, which is an image of a simple football.
The first thing to do is to copy the image in your Gideros project folder. After you have copied the image, go back to Gideros Studio. You should see that your image did not automatically appear in the Project pane and you need to add it manually. So just to emphasize this difference between Gideros Project files and your filesystem, let's create a folder inside the Project pane, where we will store our images.
To do that, right-click the mouse button on your project name in the Project pane and select New Folder. This should create a folder in the Project pane file hierarchy. Now name it
After it is done, let's add our image to this folder by right-clicking on the
images folder, selecting Add Existing Files, and selecting our copied image in the opened file dialog. Our image should now have been added to the Project pane.
Just to sum it up and emphasize the difference between Gideros project's file management and what actually happens on your filesystem, you can see that in Gideros Studio, your image is in the
images folder. But if you open the directory of your project in your filesystem, you will see that there is no
images directory and your image is where you copied it to.
This is an important difference that you need to understand and take advantage of when managing multiple projects that share the same codebase and assets.
So, our image is already in the project; now let's modify our project and display this image on the Gideros Player's screen.
local texture = Texture.new("images/ball.png") local image = Bitmap.new(texture) image:setPosition(40, 40) stage:addChild(image)
First, we need to create a texture representation of the image using the
Texture class. After that, we can create the image object by providing our texture to the
Then, we set it's position to
(40, 40) coordinate and add it to the
stage variable to render. If you run the project, you should see that the image is positioned at (40, 40) coordinate at its top-left corner. But Bitmap objects also have an option to position themselves using different internal points as positioning anchors, called anchor points.
For example, what if we want an image's center to be at (40, 40) coordinate. Of course we could calculate that! If we take a 80 x 80 image and want to position its center at (40,40), we need to position its left corner at (0, 0) coordinate.
But we also could simply change its anchor point to the relative center using (0.5, 0.5) as the anchor point like this:
Anchor points provide an easy way to position an image relative to the provided origin point from 0 (image's top or left-side) to 1 (image's bottom or right-hand side). By default, the anchor point is (0, 0), which means that image will be positioned by its top-left corner. But when we set the anchor point to (0.5, 0.5), we say that we want to position the image by its center.
Thus in our case, the image's center will be on (40, 40) coordinate and not at the top-left corner.
And in the end, as usual, we must add the image to the
stage variable for it to be rendered.
Efficiently reusing textures
Easily changing the textures of an existing Bitmap without changing the Bitmap object itself
Allowing us to use textures for other purposes such as, for example, filling the shapes
And again we can try and run this modified project by clicking on the start button in Gideros Studio. If everything is ok it should display the image on top of the previously added text.
I made the image to overlay the text deliberately, just to show you how Z-ordering works in Gideros. Text was added to the
stage as a first element, and the image was added after it. Thus, if we position text and an image in the way they would overlay, the image would be on top of the text (only because it was added to the
stage after the text).
Another thing we will try to display on the screen would be our drawn shape. For that purpose, there is a
Shape class in Gideros, which could draw any shape from the provided coordinates that can have line style and fill style of a solid color image.
local shape = Shape.new() shape:setLineStyle(5, 0xff0000, 1) shape:setFillStyle(Shape.SOLID, 0x0000ff, 0.5)
First we create the
Shape instance and store it in the
shape variable. After that, we set the style of the lines used in the shape. In the example, by calling
shape:setLineStyle(5, 0xff0000, 1), we use red lines that are 5 px wide and with full opacity. An opacity or alpha channel can be provided as values between 0 (fully transparent) and 1 (not transparent).
After we set our line styles, we also provide a fill style using the
shape:setFillStyle(Shape.SOLID, 0x0000ff, 0.5) method call. Here,
Shape.SOLID specifies that we will be using a solid color to fill the shape (we could also use texture to fill the shape by providing
Shape.TEXTURE). Then, similar to what we did before, we provide a fill color and an alpha value. In our case, blue and semi-transparent alpha value.
shape:beginPath() shape:moveTo(0,0) shape:lineTo(0, 100) shape:lineTo(100, 100) shape:lineTo(100, 0) shape:closePath() shape:endPath()
After we have set the style of our shape, we can draw something with that. To let the
shape object know we want to start drawing, we need to call the
shape:beginPath() method. After that, we can imagine that we have a pencil and we need to move it using
shape:moveTo to some relative coordinate; in our case, (0, 0) coordinate. Then we can draw a line to another coordinate using the
shape:lineTo method. In our case, we are drawing a square with 100 px wide sides.
When we've finished drawing, we can call the
shape:closePath() method, which would automatically draw the line from a last and first point in the shape. Then, we tell the
shape object that we've finished drawing by calling the
shape:setPosition(40, 40) stage:addChild(shape)
And the last thing we should do is to position the shape and add it to the
stage variable, so it would be rendered.
Let's again run the project by clicking on the start button in Gideros Studio.
Now, on the Gideros Player screen you should see some text and an image positioned over the text, because it was added to the
stage variable after it. And you should see a square with red line and a blue semi-transparent filling over the image (because it was added to the
stage variable after the image). As the filling of the square is semi-transparent, you should also see the image underneath it.
There is also an alternative to
Shape, which is called the
Mesh class, and it allows you to draw in triangles and provide much wider functionality, such as setting separate colors for vertices and creating gradients.
Additionally, meshes are more efficient than shapes, but they are also much more complex to use (you would have to represent all shapes in triangles to use meshes) and have their own limitations, for example, mesh triangles can't be transformed (rotated, scaled) as
By now, we should have three objects positioned in the way they overlay each other. But what if we want to position them somewhere else on the screen while maintaining their relative positions (they would still overlay in exactly the same way)?
The first thought would be to move them separately by the same amount of coordinates. It might be ok to do so while there are three objects, but imagine if we had hundreds of objects to move; it might not be so easy or efficient to move them separately.
For that purpose we can use the
Sprite class, which is actually just a dummy holder (without anything to render) and is meant to group other objects. So instead of adding our text, image, and shape straight to the
stage variable, we first create a
Sprite object to group them and store it in the variable named
group. Then we add our objects to
group and in the end, add this group to the
local group = Sprite.new() group:addChild(text) group:addChild(image) group:addChild(shape) stage:addChild(group)
After this modification, we can move the whole group; so for example, if we call the
group:setPosition(100, 100) method, the whole group would be moved to (100, 100) coordinates, maintaining their relative positions to each other.
This is one of the most common usages of the
Sprite class, but there is another one, which is meant for dividing groups of objects into layers.
Now, for example, we have a need to add and remove objects in our game, but we want to add each new object underneath our current three objects, so that our
shape objects would always be on top overlaying any newly added object.
Of course, it may seem hard to achieve because Gideros uses a Z index based on an object's position in the rendering hierarchy, so all new elements will always be on top. But actually, it can be done very easily by using the
Sprite object as a layer.
First, we will create a new group using the
Sprite class and store it in the
bottomLayer variable. Then we will add this layer below our
group by using the
stage:addChildAt method and providing index 1, which means first. It will add
group, thus making it appear overlapped.
local bottomLayer = Sprite.new() stage:addChildAt(bottomLayer, 1)
After that, there is no need to use
stage:addChildAt anymore, because every object you add to
bottomLayer will automatically be underneath the
group (because this layer by itself is underneath the
This example perfectly demonstrates how the rendering hierarchy works in Gideros, and you can experiment more with it to understand it better and use it to your advantage.
Now when we have something to see in our Gideros Player, let's experiment more with a player's customizations and change its resolution to something higher, such as an iPad's resolution (768 x 1024). When you have done this, hit the start button in our Gideros Studio to refresh the project.
group, when set to (100, 100) coordinates, was almost at the center of the app, but now it's in the top-left corner. Why is that?
Well, previously we ran our app in the default (320 x 480) resolution, but now there is a higher resolution (768 x 1024), and relatively, our positioned
group is still at the (100, 100) coordinate.
But does this mean you will have to create a different app layout for each resolution? Of course not, Gideros can handle the automatic scaling for you. Let's try it out.
Select a scaling mode
Provide logical dimensions in which you will develop the application
Set application orientation
Set project FPS
While Orientation and FPS are self-explanatory, Logical Dimensions and Scale Mode may seem confusing at first.
Let's try selecting Letterbox as Scale Mode and clicking on OK. Then click on the start button to reload the project in Gideros Player. If you did not have the iPad resolution selected in Gideros Player, then select it and reload the project again.
You should now see the same effect that was at the default resolution—our
group is now at similar position.
I try to use the Letterbox scale mode in all my projects as it provides the most resistance to all resolutions, but let's see what the other options are:
No Scale – Top Left: This mode does not scale the project
No Scale – Center: This mode does not scale the project, but centers it
Pixel Perfect: This mode centers the app and scales it with scale increments such as 1/3, 1/2, 1, 2, or 3
Letterbox: This mode scales the project maximally preserving the aspect ratio and without cropping the screen
Crop: This mode fills the screen completely by cropping all the content if needed and preserving the aspect ratio
Stretch: This mode stretches the app on both dimensions without preserving the aspect ratio
Fit Width/Height: This mode fits only one dimension preserving the aspect ratio
To learn more about scale modes, check out the Gideros documentation here: http://docs.giderosmobile.com/automatic_screen_scaling.html.
So the Letterbox scaling does what we need; but if you look at the image closely, you will note that it is quite pixelated and appears in poor quality.
There are two ways to handle this problem. The first one would be by applying anti-aliasing to the image. You can do that by providing the second parameter
true when creating texture like this:
local texture = Texture.new("images/ball.png", true). Try it out and reload the project in the player by clicking on the start button inside Gideros Studio. You will see it looks better.
While this works great for small scaling, it is better to use larger images, for example, twice as large images for iPad retina resolution than used in iPhone. And again, Gideros comes to aid on this problem.
Another killer feature of Gideros is the automatic image resolution selection. Basically, it allows you to provide the same image in different (higher and lower) resolutions. Gideros will automatically select the image that suits the current screen resolution best, based on your logical dimensions and the scaling mode.
To do that, you need to specify the scaling ratios you will be using in your images. This can be done by navigating to the Project Properties and clicking the + button in the Graphics tab under Image Scales.
You can specify any suffix you want together with the ratio, for example, let's specify three ratios such as:
suffix: @small, ratio: 0.5
suffix: @medium, ratio: 1
suffix: @big, ratio: 2
Then create images with resolutions in these ratios and name them accordingly:
If you add all those images to Gideros Studio, then while running the app in different resolutions, Gideros will automatically choose the image that suits the device best. Thus for example, in Letterbox scaling, the image won't be so upscaled anymore, because the larger version of it will be used automatically.
Apart from the key inputs, there are two types of input events in Gideros:
Mouse events meant for desktops
Touch events meant for mobile devices
The settings on the Input tab allow you to generate mouse events on mobile devices and touch events (with single touch) on a desktop player. So both of the events would be compatible with any platform. Also for example, you could use mouse events to handle single touches more easier and touch events for multiple touches. Thus, it is recommended to enable generation of both events.
On the last tab, there are some iOS-specific settings allowing you to enable or disable the retina support and autorotation for a specific set of iOS devices. Due to the Apple policy, when reviewing apps, it is recommended to enable retina and autorotation either for both iPad and iPhone (if you are creating a universal project) or for the specific device you will be supporting in your app.
To test your Gideros project on the device, you must first install the Gideros Player app (specific to each platform), then it will work similar to the Gideros desktop player, but without all the customization options, it will simply use your device settings.
By uploading to a memory card on the phone
By using your phone's data transfer cable
.apkfile to the server and accessing it there from the phone
Additionally, Gideros provides a way to easily install and update your Gideros Android player from this address: http://giderosmobile.com/player/. You can simply bookmark it on your phone and access it with every new Gideros version.
GiderosiOSPlayer.zipfrom the Gideros installation folder
Unzip and open it inside Xcode
Connect your iOS device to your Mac (assuming you have already certified your device)
And run the project on your device
Similar to Android, you can also get the latest Gideros iOS player project from: http://giderosmobile.com/player/
Now when you have Gideros Player installed on your device, let's try to run our project on it.
To do that, first we need to launch the player on the device. Then take a note of the IP address the device player is displaying. This is the IP address we will input in Gideros Studio so it could connect to the device.
It will pop up the Player Settings dialog. There you need to uncheck the Localhost checkbox and enter the IP address displayed on the device. After that, you can click on OK.
The start button inside Gideros Studio should become inactive for some time and then again reactivate when Studio finally connects to the device. After that, you can simply click on the start button and the project you previously saw on the desktop player will appear on your device screen within seconds.
If the start button does not become active, ensure the following:
Both the phone and computer are in the same LAN (connected to the same router)
Gideros Studio is added to firewall and any antivirus exceptions you might have
No other Gideros Studio is connected to your Gideros player (or vice versa)
Gideros Studio uses the TCP protocol with 15000 port, make sure no other program blocks it
This can be easily done by accessing the File menu and selecting Export Project. If this is the first time you are exporting an app, you may see a message: You do not have a license installed. Please run Gideros License Manager.
It means you need to license your copy of Gideros (even free accounts have to license it). To do that, you must have an account with Gideros (you can register one here: http://giderosmobile.com/members/register, if you haven't done so already).
Once registered, go to your Gideros installation folder and run
Enter the username and the password you used when registering with the Gideros website and click on Login.
If, for some reason, Gideros License Manager can't install a license, you can do it manually by logging into your Gideros account and accessing this page, http://giderosmobile.com/members/license, which allows you to get the license file and also provides detailed information on how to install it.
In the Export Project dialog, you can chose the platform to which you want to export with an option to provide some platform-specific settings. Additionally, you can select exporting a full project or checking Export assets only.
A full export should be done the first time you are exporting your Gideros project. It will create a platform-specific (Android or Xcode) project with all your files inside.
After that, you may select to Export assets only, especially if you did some modifications to the exported Android or Xcode project (for example, installed some platform specific plugins).
When exporting assets only, Gideros will only export your files (images, code, and so on) that come from the Gideros Studio Project pane and will not override previously exported Xcode or Android project and its settings.
After that, you may import the exported project in the platform-specific IDE and build or run it as you would when developing the app natively for this specific platform.
We have successfully installed Gideros and tried it out. In this chapter, we created our first project and added text, images, and shapes to it. We also ran it on Gideros desktop and our installed device player. We discussed the settings provided for each app and how to use them to your advantage.
In the next chapter, we will start building our game with the basics we learned here by creating separate scenes each game should require, such as start screen and settings screens. We will achieve this by using the Gideros OOP approach and creating our own Gideros classes.