Lavorare con i file

Esistono molti modi diversi per creare file e accedervi. I percorsi dei file e le modalità di accesso variano in base al tipo di file e alla sua posizione.

Funzioni per l’accesso a file e cartelle

Defold offre diverse funzioni per lavorare con i file:

• Puoi usare le funzioni standard io.* per leggere e scrivere file. Queste funzioni offrono un controllo molto preciso sull’intero processo di I/O.

-- open myfile.txt for writing in binary mode
-- returns nil plus error message on failure
local f, err = io.open("path/to/myfile.txt", "wb")
if not f then
	print("Something went wrong while opening the file", err)
	return
end

-- write to the file, flush it to disk and then close the file
f:write("Foobar")
f:flush()
f:close()

-- open myfile.txt for reading in binary mode
-- returns nil plus error message on failure
local f, err = io.open("path/to/myfile.txt", "rb")
if not f then
	print("Something went wrong while opening the file", err)
	return
end

-- read the entire file as a string
-- returns nil on failure
local s = f:read("*a")
if not s then
	print("Error while reading file")
	return
end

print(s) -- Foobar

• Puoi usare os.rename() e os.remove() per rinominare ed eliminare file.

• Puoi usare sys.save() e sys.load() per leggere e scrivere tabelle Lua. Sono disponibili altre funzioni sys.* che aiutano a risolvere i percorsi dei file in modo indipendente dalla piattaforma.

-- get a platform independent path to the file "highscore" for application "mygame"
local path = sys.get_save_file("mygame", "highscore")

-- save a Lua table with some data
local ok = sys.save(path, { highscore = 100 })
if not ok then
	print("Failed to save", path)
	return
end

-- load the data
local ok, data = pcall(sys.load, path)
if not ok then
	-- The file exists, but is corrupt, foreign, or uses an unsupported format.
	print("Failed to load save data:", data)
	data = {}
end
print(data.highscore) -- 100

sys.load() restituisce una tabella vuota se il file non esiste. Se il file esiste ma non è stato creato da sys.save(), è danneggiato o usa un formato di tabella serializzata non supportato, sys.load() genera un errore Lua. Usa pcall() come nell’esempio precedente quando occorre poter gestire dati di salvataggio danneggiati o modificati dall’esterno.

Posizioni di file e cartelle

Le posizioni di file e cartelle si possono suddividere in tre categorie:

• File specifici dell’applicazione creati dalla tua applicazione
• File e cartelle inclusi nel bundle della tua applicazione
• File specifici del sistema a cui accede la tua applicazione

Come salvare e caricare file specifici dell’applicazione

Quando salvi e carichi file specifici dell’applicazione, come punteggi migliori, impostazioni dell’utente e stato del gioco, è consigliabile usare una posizione fornita dal sistema operativo e destinata appositamente a questo scopo. Puoi usare sys.get_save_file() per ottenere il percorso assoluto di un file nella posizione prevista dal sistema operativo. Una volta ottenuto il percorso assoluto, puoi usare le funzioni sys.*, io.* e os.* (vedi sopra).

Consulta l’esempio che mostra come usare sys.save() e sys.load().

Come accedere ai file inclusi nel bundle dell’applicazione

Puoi includere file nella tua applicazione usando risorse del bundle (bundle resources) e risorse personalizzate (custom resources).

Risorse personalizzate

Le risorse personalizzate vengono incluse nell’archivio principale del gioco tramite il campo Custom Resources in game.project.

Il campo Custom Resources deve contenere un elenco di risorse separate da virgole che verranno incluse nell’archivio principale del gioco. Se specifichi delle directory, tutti i file e le directory al loro interno vengono inclusi in modo ricorsivo. Puoi leggere i file usando sys.load_resource().

-- Load level data into a string
local data, error = sys.load_resource("/assets/level_data.json")
-- Decode json string to a Lua table
if data then
  local data_table = json.decode(data)
  pprint(data_table)
else
  print(error)
end

Risorse del bundle

Le risorse del bundle sono file e cartelle aggiuntivi inclusi nel bundle dell’applicazione tramite il campo Bundle Resources in game.project.

Il campo Bundle Resources deve contenere un elenco, separato da virgole, di directory contenenti file e cartelle di risorse da copiare senza modifiche nel pacchetto risultante durante la creazione del bundle. Le directory devono essere specificate con un percorso assoluto a partire dalla radice del progetto, per esempio /res. La directory delle risorse deve contenere sottocartelle denominate secondo lo schema platform o architecture-platform.

Le piattaforme supportate sono ios, android, osx, win32, linux, web, switch. È consentita anche una sottocartella denominata common, contenente file di risorse comuni a tutte le piattaforme. Esempio:

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

Puoi usare sys.get_application_path() per ottenere il percorso in cui si trova l’applicazione. Usa questo percorso di base dell’applicazione per costruire il percorso assoluto completo dei file a cui devi accedere. Una volta ottenuto il percorso assoluto di questi file, puoi usare le funzioni io.* e os.* per accedervi.

local path = sys.get_application_path()
local f = io.open(path .. "/mycommonfile.txt", "rb")
local txt, err = f:read("*a")
if not txt then
	print(err)
	return
end
print(txt)

Risorse personalizzate e risorse del bundle - confronto

Accesso ai file di sistema

Il sistema operativo può limitare l’accesso ai file di sistema per motivi di sicurezza. Puoi usare l’estensione nativa extension-directories per ottenere il percorso assoluto di alcune directory di sistema comuni (ad esempio documents, resource, temp). Una volta ottenuto il percorso assoluto di questi file, puoi usare le funzioni io.* e os.* per accedervi (vedi sopra).

Estensioni

L’Asset Portal contiene diversi asset per semplificare l’accesso a file e cartelle. Alcuni esempi:

• Lua File System (LFS) - Funzioni per lavorare con directory, autorizzazioni dei file, ecc.
• DefSave - Un modulo che aiuta a salvare e caricare la configurazione e i dati del giocatore tra una sessione e l’altra.