Difference between revisions of "File system"
(mostly formatting :-)) |
|||
(3 intermediate revisions by 2 users not shown) | |||
Line 4: | Line 4: | ||
== File system == | == File system == | ||
− | In Gideros runtime, there are | + | In Gideros runtime, there are now, 4 kinds of directories: |
*'''resource directory''' | *'''resource directory''' | ||
*'''document directory''' | *'''document directory''' | ||
*'''temporary directory''' | *'''temporary directory''' | ||
+ | *'''buffer directory''' | ||
== Resource directory == | == Resource directory == | ||
Line 26: | Line 27: | ||
The resource directory is the default directory. Therefore, to access the files you specify the file path as it is: | The resource directory is the default directory. Therefore, to access the files you specify the file path as it is: | ||
− | < | + | <syntaxhighlight lang="lua"> |
local sprite1 = Texture.new("gfx/sprite1.png") | local sprite1 = Texture.new("gfx/sprite1.png") | ||
local sprite2 = Texture.new("gfx/sprite2.png") | local sprite2 = Texture.new("gfx/sprite2.png") | ||
Line 32: | Line 33: | ||
local music = Sound.new("audio/game-music.mp3") | local music = Sound.new("audio/game-music.mp3") | ||
local click = Sound.new("audio/click.wav") | local click = Sound.new("audio/click.wav") | ||
− | </ | + | </syntaxhighlight> |
You can also use the io library provided by Lua: | You can also use the io library provided by Lua: | ||
− | < | + | <syntaxhighlight lang="lua"> |
io.read("data/list.txt") | io.read("data/list.txt") | ||
− | </ | + | </syntaxhighlight> |
Line 44: | Line 45: | ||
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: | 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: | ||
− | < | + | <syntaxhighlight lang="lua"> |
local sprite1 = Texture.new("|R|gfx/sprite1.png") | local sprite1 = Texture.new("|R|gfx/sprite1.png") | ||
− | </ | + | </syntaxhighlight> |
== Document directory == | == Document directory == | ||
Line 52: | Line 53: | ||
In order to specify a file in the document directory, append '''|D|''' to the beginning of the filename: | In order to specify a file in the document directory, append '''|D|''' to the beginning of the filename: | ||
− | < | + | <syntaxhighlight lang="lua"> |
io.write("|D|save.txt") | io.write("|D|save.txt") | ||
− | </ | + | </syntaxhighlight> |
Here is an example of how you can copy a file from the resource directory to the document directory: | Here is an example of how you can copy a file from the resource directory to the document directory: | ||
− | < | + | <syntaxhighlight lang="lua"> |
--function to copy file | --function to copy file | ||
local function copy(src, dst) | local function copy(src, dst) | ||
Line 88: | Line 89: | ||
copy("database.db", "|D|database.db") | copy("database.db", "|D|database.db") | ||
end | end | ||
− | </ | + | </syntaxhighlight> |
== Temporary directory == | == Temporary directory == | ||
Line 94: | Line 95: | ||
In order to specify a file in the temporary directory, append '''|T|''' to the beginning of the file name. Example: | In order to specify a file in the temporary directory, append '''|T|''' to the beginning of the file name. Example: | ||
− | < | + | <syntaxhighlight lang="lua"> |
io.write("|T|tempfile.txt") | io.write("|T|tempfile.txt") | ||
− | </ | + | </syntaxhighlight> |
This storage may be used to display some temporary data, like in the following example, images downloaded from the internet: | This storage may be used to display some temporary data, like in the following example, images downloaded from the internet: | ||
− | < | + | <syntaxhighlight lang="lua"> |
--download completed | --download completed | ||
local function onComplete(event) | local function onComplete(event) | ||
Line 119: | Line 120: | ||
--add event listener | --add event listener | ||
loader:addEventListener(Event.COMPLETE, onComplete) | loader:addEventListener(Event.COMPLETE, onComplete) | ||
− | </ | + | </syntaxhighlight> |
+ | |||
+ | == Buffer directory == | ||
+ | Gideros Studio now provides a '''buffer directory''' (see: [[Buffer]]) to store data into a file. The Buffer class acts as FIFO buffer with Gideros internal file system integration. Once created, buffer data can be accessed by internal gideros functions that normally use files, such as textures or sounds. | ||
+ | |||
+ | The buffer will be deleted after the application session finishes. | ||
+ | |||
+ | In order to specify a file in the buffer directory, append '''|B|''' to the beginning of the buffer name. Example: | ||
+ | <syntaxhighlight lang="lua"> | ||
+ | io.append("|B|buffer.ext") | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | This storage may be used to create a '''''Shoutcast''''' stream. Please see Gideros example '''\Audio\Shoutcast Player'''. | ||
== To sum up == | == To sum up == | ||
Here is a list of possible file operations: | Here is a list of possible file operations: | ||
− | < | + | <syntaxhighlight lang="lua"> |
io.read("file.txt") -- open file.txt in the resource directory to read | io.read("file.txt") -- open file.txt in the resource directory to read | ||
io.read("|R|file.txt") -- open file.txt in the resource directory to read (same as above) | io.read("|R|file.txt") -- open file.txt in the resource directory to read (same as above) | ||
io.read("|D|file.txt") -- open file.txt in the document directory to read | io.read("|D|file.txt") -- open file.txt in the document directory to read | ||
− | io. | + | io.get("|B|buffer.ext") -- gets the data from the buffer |
− | </ | + | </syntaxhighlight> |
== File execution order == | == File execution order == | ||
Line 155: | Line 168: | ||
'''PREV.''': [[Event system]]<br/> | '''PREV.''': [[Event system]]<br/> | ||
'''NEXT''': [[Profiling]] | '''NEXT''': [[Profiling]] | ||
+ | |||
+ | |||
+ | {{GIDEROS IMPORTANT LINKS}} |
Latest revision as of 22:22, 18 November 2023
The Ultimate Guide to Gideros Studio
File system
In Gideros runtime, there are now, 4 kinds of directories:
- resource directory
- document directory
- temporary directory
- buffer 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.
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")
Note: the resource directory is read-only and you should not try to write any files there
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")
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| to the beginning of the filename:
io.write("|D|save.txt")
Here is an example of how you can copy a file from the resource directory to the document directory:
--function to copy file
local function copy(src, dst)
local srcf = io.open(src, "rb")
local dstf = io.open(dst, "wb")
local size = 2^13 -- good buffer size (8K)
while true do
local block = srcf:read(size)
if not block then break end
dstf:write(block)
end
srcf:close()
dstf:close()
end
--function to check if file exists
local function exists(file)
local f = io.open(file, "rb")
if f == nil then
return false
end
f:close()
return true
end
--usage
if not exists("|D|database.db") then
copy("database.db", "|D|database.db")
end
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| to the beginning of the file name. Example:
io.write("|T|tempfile.txt")
This storage may be used to display some temporary data, like in the following example, images downloaded from the internet:
--download completed
local function onComplete(event)
--store image in temporary folder
local out = io.open("|T|image.png", "wb")
out:write(event.data)
out:close()
--display it to user
local b = Bitmap.new(Texture.new("|T|image.png"))
b:setAnchorPoint(0.5, 0.5)
b:setPosition(160, 240)
stage:addChild(b)
end
--load image
local loader = UrlLoader.new("http://www.giderosmobile.com/giderosmobile.png")
--add event listener
loader:addEventListener(Event.COMPLETE, onComplete)
Buffer directory
Gideros Studio now provides a buffer directory (see: Buffer) to store data into a file. The Buffer class acts as FIFO buffer with Gideros internal file system integration. Once created, buffer data can be accessed by internal gideros functions that normally use files, such as textures or sounds.
The buffer will be deleted after the application session finishes.
In order to specify a file in the buffer directory, append |B| to the beginning of the buffer name. Example:
io.append("|B|buffer.ext")
This storage may be used to create a Shoutcast stream. Please see Gideros example \Audio\Shoutcast Player.
To sum up
Here is a list of possible file operations:
io.read("file.txt") -- open file.txt in the resource directory to read
io.read("|R|file.txt") -- open file.txt in the resource directory to read (same as above)
io.read("|D|file.txt") -- open file.txt in the document directory to read
io.get("|B|buffer.ext") -- gets the data from the buffer
File execution order
By default Gideros executes all your project Lua files in the following order:
- init.lua will always be executed first
- then all the files in alphabetical order (upper case first, then lowercase), while resolving code dependencies
- 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