Hardware and OS

The Ultimate Guide to Gideros Studio

Handling touch and mouse input

Note: The easiest way to detect if the player touches the screen with two fingers, is to control the length of event.allTouches array. If it is 2, then exactly 2 fingers is touching the screen.

local function onTouchesBegin(event)
  local isTwoFinger = (#event.allTouches == 2)
end

Vibration

Gideros Studio provides a function for vibration. Consider the following example:

application:vibrate()

The vibration period is 300 ms for Android. For iOS, device vibrates for a duration which is determined by the operating system.

Disabling screen dimming

Some games may require that player doesn't touch the screen for a long time, e.g. those using accelerometer and gyro to control the actors on the screen. In this case, the screen may dim, depending on the user's activity and device settings. To disable (or enable) screen dimming, use the following commands:

-- disable screen dimming and device sleeping
application:setKeepAwake(true)
-- enable screen dimming and device sleeping
application:setKeepAwake(false)

Note: this function has no effect on desktop player.

Filesystem

In Gideros runtime, there are 3 kinds of directories: resource, document, and temporary.

Resource directory

Your code, image, audio and all other files are reside at resource directory. Consider the test project below, and examine the 3 directories and corresponding files.

The files seen above are stored on a real device and Gideros Player like the following:

{resource directory}/gfx/sprite1.png
{resource directory}/gfx/sprite2.png
{resource directory}/gfx/background.png
{resource directory}/audio/game-music.mp3
{resource directory}/audio/click.wav
{resource directory}/data/list.txt
{resource directory}/main.lua
{resource directory}/game.lua

Resource directory is the default directory. Therefore, to access the files at resource directory, specify the file path as it is:

local sprite1 = Texture.new("gfx/sprite1.png")
local sprite2 = Texture.new("gfx/sprite2.png")
local background = Texture.new("gfx/background.png")
local music = Sound.new("audio/game-music.mp3")
local click = Sound.new("audio/click.wav")

Also, you can use the io library provided by Lua:

io.read("data/list.txt")

You don't need to know the exact path of resource, document, and temporary directories because Gideros Studio provides an easy way to specify files at these directories.

Document directory

You can store a file created by your application in "document" directory. The files created in this directory are permanent among application sessions. For example, you can create and then read files at document directory to save player progress, or keep latest GPS coordinates.

In order to specify a file in document directory, append "|D|" to the beginning of the filename:

io.write("|D|save.txt")

Temporary directory

Gideros Studio provides a temporary directory to store files that may not stay permanent between different sessions. Therefore, files created in this directory are not guaranteed to exist when applications runs next time, and may be deleted after application session finishes.
In order to specify a file at temporary directory, append "|T|" to the begining of the file name. Consider the example below:

io.write("|T|temp.txt")

Note: Optionally, you can access the files at resource directory by adding "|R|" to the beginning of the file name (but you don't need to):

local sprite1 = Texture.new("|R|gfx/sprite1.png")

To sum up, here's a list of file operations on the device:

-- open file.txt at resource directory to read
io.read("file.txt")
-- open file.txt at resource directory to read (same as above)
io.read("|R|file.txt")
-- open file.txt at documents directory to read
io.read("|D|file.txt")
-- open file.txt at temporary directory to read
io.read("|T|file.txt")