File system

The Ultimate Guide to Gideros Studio

File system

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")

File execution order

init.lua is the file that is loaded first.

Then we have files in alphabetical order (upper case first, then lowercase), while resolving code dependencies provided.

Finally, main.lua is loaded last.

The rules about main.lua and init.lua only apply to top level files. If they are in sub directories, they lose their specificities.

PREV.: Playing_Sound_and_Music
XXX NEXT: Extend_your_application_with_plugins XXX