Working with files

There are many different ways to create and/or access files. The file paths and the ways your access these files varies depending on the type of file and the location of the file.

Functions for file and folder access

Defold provides several different functions to work with files:

You can use the standardio.* functions to read and write files. These functions give you very fine-grained control over the entire I/O process.

-- open myfile.txt for writing in binary mode-- returns nil plus error message on failurelocalf,err=io.open("path/to/myfile.txt","wb")ifnotfthenprint("Something went wrong while opening the file",err)returnend-- write to the file, flush it to disk and then close the filef:write("Foobar")f:flush()f:close()-- open myfile.txt for reading in binary mode-- returns nil plus error message on failurelocalf,err=io.open("path/to/myfile.txt","rb")ifnotfthenprint("Something went wrong while opening the file",err)returnend-- read the entire file as a string-- returns nil on failurelocals=f:read("*a")ifnotsthenprint("Error while reading file")returnendprint(s)-- Foobar

You can useos.rename() andos.remove() to rename and remove files.
You can usesys.save() andsys.load() to read and write Lua tables. Additionalsys.* functions exist to help with platform independent file path resolution.

-- get a platform independent path to the file "highscore" for application "mygame"localpath=sys.get_save_file("mygame","highscore")-- save a Lua table with some datalocalok=sys.save(path,{highscore=100})ifnotokthenprint("Failed to save",path)returnend-- load the datalocaldata=sys.load(path)print(data.highscore)-- 100

File and folder locations

File and folder locations can be divided into three categories:

Application specific files created by your application
Files and folders bundled with your application
System specific files accessed by your application

How to save and load application specific files

When saving and loading application specific files such as high scores, user settings and game state it is recommended to do so in a location provided by the operating system and intended specifically for this purpose. You can usesys.get_save_file() to get the OS specific absolute path to a file. Once you have the absolute path you can use thesys.*,io.* andos.* functions (see above).

Check the example showing how to usesys.save() andsys.load().

How to access files bundled with the application

You can include files with your application using bundle resources and custom resources.

Custom Resources

Custom resources are bundled in the main game archive using theCustom Resources field ingame.project.

TheCustom Resources field should contain a comma separated list of resources that will be included in the main game archive. If directories are specified, all files and directories in that directory are recursively included. You can read the files usingsys.load_resource().

-- Load level data into a stringlocaldata,error=sys.load_resource("/assets/level_data.json")-- Decode json string to a Lua tableifdatathenlocaldata_table=json.decode(data)pprint(data_table)elseprint(error)end

Bundle Resources

Bundle resources are additional files and folders located as a part of your application bundle using theBundle Resources field ingame.project.

TheBundle Resources field should contain a comma separated list of directories containing resource files and folders that should be copied as-is into the resulting package when bundling. The directories must be specified with an absolute path from the project root, for example/res. The resource directory must contain subfolders named byplatform, orarchitecture-platform.

Supported platforms areios,android,osx,win32,linux,web,switch A subfolder namedcommon is also allowed, containing resource files common for all platforms. Example:

res├── win32│   └── mywin32file.txt├── common│   └── mycommonfile.txt└── android    ├── myandroidfile.txt    └── res        └── xml            └── filepaths.xml

You can usesys.get_application_path() to get the path to where the application is stored. Use this application base path to create the final absolute path to the files you need access to. Once you have the absolute path of these files you can use theio.* andos.* functions to access the files.

localpath=sys.get_application_path()localf=io.open(path.."/mycommonfile.txt","rb")localtxt,err=f:read("*a")ifnottxtthenprint(err)returnendprint(txt)

For security reasons browsers (and by extension any JavaScript running in a browser) is prevented from accessing system files. File operations in HTML5 builds in Defold still work, but only on a “virtual file system” using the IndexedDB API in the browser. What this means is that there is no way to access bundle resources usingio.* oros.* functions. You can however access bundle resources usinghttp.request().

Custom and Bundle resources - comparison

Characteristic	Custom Resources	Bundle Resources
Loading speed	Faster - files loaded from binary archive	Slower - files loaded from filesystem
Load partial files	No - only entire files	Yes - read arbitrary bytes from file
Modify files after bundling	No - files stored inside a binary archive	Yes - files stored on the local file system
HTML5 support	Yes	Yes - but access through http and not file I/O

System file access

Access to system files may be restricted by the operating system for security reasons. You can use theextension-directories native extension to get the absolute path to some common system directories (ie documents, resource, temp). Once you have the absolute path of these files you can use theio.* andos.* functions to access the files (see above).

Extensions

TheAsset Portal contains several assets to simplify file and folder access. Some examples:

Lua File System (LFS) - Functions to work with directories, file permissions etc
DefSave - A module to help you save / load config and player data between session.

Movatterモバイル変換