Difference between revisions of "File system"

From GiderosMobile
m (formatting)
Line 4: Line 4:
  
 
== File system ==
 
== File system ==
 
+
In Gideros runtime, there are 3 kinds of directories:
In Gideros runtime, there are 3 kinds of directories: resource, document, and temporary.
+
*resource directory
 +
*document directory
 +
*temporary directory
  
 
=== Resource directory ===
 
=== Resource directory ===
 
+
Your code, images, audios and all other files reside in the resource directory. Consider the test project below, and examine the 3 directories and corresponding files.
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.
 
  
 
[[File:Resource directory.png]]
 
[[File:Resource directory.png]]
  
 
The files seen above are stored on a real device and Gideros Player like the following:
 
The files seen above are stored on a real device and Gideros Player like the following:
<br/>
 
  
 
{resource directory}/gfx/sprite1.png<br/>
 
{resource directory}/gfx/sprite1.png<br/>
Line 24: Line 24:
 
{resource directory}/main.lua<br/>
 
{resource directory}/main.lua<br/>
 
{resource directory}/game.lua<br/>
 
{resource directory}/game.lua<br/>
<br/>
 
 
Resource directory is the default directory. Therefore, to access the files at resource directory, specify the file path as it is:
 
<br/>
 
  
 +
The resource directory is the default directory. Therefore, to access the files you specify the file path as it is:
 
<source lang="lua">
 
<source lang="lua">
 
local sprite1 = Texture.new("gfx/sprite1.png")
 
local sprite1 = Texture.new("gfx/sprite1.png")
Line 36: Line 33:
 
local click = Sound.new("audio/click.wav")
 
local click = Sound.new("audio/click.wav")
 
</source>
 
</source>
<br/>
 
  
Also, you can use the io library provided by Lua:
+
You can also use the io library provided by Lua:
 
<source lang="lua">
 
<source lang="lua">
 
io.read("data/list.txt")
 
io.read("data/list.txt")
 
</source>
 
</source>
<br/>
 
 
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 ===
 
=== Document directory ===
 +
You can store a file created by your application in the '''document directory'''. The files created in this directory are permanent among application sessions. For example, you can create and then read files in the document directory to save player progress, or keep latest GPS coordinates, ...
  
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 the document directory, append '''|D|''' at the beginning of the filename:
<br/>
 
 
 
In order to specify a file in document directory, append "|D|" to the beginning of the filename:
 
<br/>
 
 
 
 
<source lang="lua">
 
<source lang="lua">
 
io.write("|D|save.txt")
 
io.write("|D|save.txt")
Line 59: Line 48:
  
 
=== Temporary directory ===
 
=== 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 the application runs next time, and may be deleted after the application session finishes.
  
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 in the temporary directory, append '''|T|''' at the beginning of the file name. Example:
<br/>
 
In order to specify a file at temporary directory, append "|T|" to the begining of the file name. Consider the example below:
 
 
<source lang="lua">
 
<source lang="lua">
io.write("|T|temp.txt")
+
io.write("|T|tempfile.txt")
 
</source>
 
</source>
<br/>
 
 
   
 
   
'''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):
+
'''Note''': you can access the files in the resource directory by adding "|R|" at the beginning of the file name, but you don't need to:
 
<source lang="lua">
 
<source lang="lua">
 
local sprite1 = Texture.new("|R|gfx/sprite1.png")
 
local sprite1 = Texture.new("|R|gfx/sprite1.png")
 
</source>
 
</source>
<br/>
 
  
 
To sum up, here's a list of file operations on the device:
 
To sum up, here's a list of file operations on the device:
<br/>
 
 
 
<source lang="lua">
 
<source lang="lua">
-- open file.txt at resource directory to read
+
-- open file.txt in the resource directory to read
 
io.read("file.txt")
 
io.read("file.txt")
-- open file.txt at resource directory to read (same as above)
+
-- open file.txt in the resource directory to read (same as above)
 
io.read("|R|file.txt")
 
io.read("|R|file.txt")
-- open file.txt at documents directory to read
+
-- open file.txt in the document directory to read
 
io.read("|D|file.txt")
 
io.read("|D|file.txt")
-- open file.txt at temporary directory to read
+
-- open file.txt in the temporary directory to read
 
io.read("|T|file.txt")
 
io.read("|T|file.txt")
 
</source>
 
</source>
  
=== File execution order ===
+
== File execution order ==
By default Gideros executes all lua files on both players and in real app.
+
By default Gideros executes all your project Lua files.
  
We can assume that the order of execution is pretty random, but there are two things guaranteed:
 
 
*init.lua will always be executed first
 
*init.lua will always be executed first
 +
*then all the files in alphabetical order (upper case first, then lowercase), while resolving code dependencies provided
 
*main.lua will always be executed last
 
*main.lua will always be executed last
  
init.lua is the file that is loaded first.
+
'''Note''': the rule about main.lua and init.lua only applies to top level files. If they are in sub directories, they lose their specificity.
Then we have files in alphabetical order (upper case first, then lowercase), while resolving code dependencies provided.
+
 
Finally, main.lua is loaded last.
+
== strict.lua ==
 +
strict.lua checks uses of undeclared global variables.
 +
 
 +
If strict.lua is executed, all global variables must be ‘declared’ through a regular assignment (even assigning nil will do) in a main chunk before being used anywhere or assigned to inside a function.
  
'''Note''': the rule about main.lua and init.lua only applies to top level files. If they are in sub directories, they lose their specificity.
+
Although optional, it is a good habit to use it when developing Lua code.
  
=== strict.lua ===
 
 
For a detailed explanation of strict.lua, please refer to http://www.lua.org/pil/14.2.html
 
For a detailed explanation of strict.lua, please refer to http://www.lua.org/pil/14.2.html
 
strict.lua checks uses of undeclared global variables. If strict.lua is executed, all global variables must be ‘declared’ through a regular assignment (even assigning nil will do) in a main chunk before being used anywhere or assigned to inside a function. Although optional, it is a good habit to use it when developing Lua code.
 
  
 
To execute strict.lua before all other Lua files, simply add strict.lua and init.lua to asset library and make strict.lua dependent to init.lua.
 
To execute strict.lua before all other Lua files, simply add strict.lua and init.lua to asset library and make strict.lua dependent to init.lua.

Revision as of 02:47, 10 May 2020

The Ultimate Guide to Gideros Studio

File system

In Gideros runtime, there are 3 kinds of directories:

  • resource directory
  • document directory
  • temporary directory

Resource directory

Your code, images, audios and all other files reside in the resource directory. Consider the test project below, and examine the 3 directories and corresponding files.

Resource directory.png

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

The resource directory is the default directory. Therefore, to access the files you 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")

You can also use the io library provided by Lua:

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

Document directory

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

In order to specify a file in the document directory, append |D| at 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 the application runs next time, and may be deleted after the application session finishes.

In order to specify a file in the temporary directory, append |T| at the beginning of the file name. Example:

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

Note: you can access the files in the resource directory by adding "|R|" at 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 in the resource directory to read
io.read("file.txt")
-- open file.txt in the resource directory to read (same as above)
io.read("|R|file.txt")
-- open file.txt in the document directory to read
io.read("|D|file.txt")
-- open file.txt in the temporary directory to read
io.read("|T|file.txt")

File execution order

By default Gideros executes all your project Lua files.

  • init.lua will always be executed first
  • then all the files in alphabetical order (upper case first, then lowercase), while resolving code dependencies provided
  • main.lua will always be executed last

Note: the rule about main.lua and init.lua only applies to top level files. If they are in sub directories, they lose their specificity.

strict.lua

strict.lua checks uses of undeclared global variables.

If strict.lua is executed, all global variables must be ‘declared’ through a regular assignment (even assigning nil will do) in a main chunk before being used anywhere or assigned to inside a function.

Although optional, it is a good habit to use it when developing Lua code.

For a detailed explanation of strict.lua, please refer to http://www.lua.org/pil/14.2.html

To execute strict.lua before all other Lua files, simply add strict.lua and init.lua to asset library and make strict.lua dependent to init.lua.

You can download strict.lua from File:Strict.lua that originally comes with the Lua distribution.


PREV.: Event system
NEXT: Profiling