Manipulation des fichiers

Il existe de nombreuses façons de créer des fichiers et/ou d’y accéder. Les chemins des fichiers et les façons d’y accéder varient selon leur type et leur emplacement.

Fonctions d’accès aux fichiers et aux dossiers

Defold propose plusieurs fonctions pour manipuler les fichiers :

• Vous pouvez utiliser les fonctions standard io.* pour lire et écrire des fichiers. Ces fonctions vous offrent un contrôle très précis sur l’ensemble du processus d’entrée/sortie.

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

• Vous pouvez utiliser os.rename() et os.remove() pour renommer et supprimer des fichiers.

• Vous pouvez utiliser sys.save() et sys.load() pour lire et écrire des tables Lua. Des fonctions sys.* supplémentaires facilitent la résolution des chemins de fichiers indépendamment de la plateforme.

-- 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() renvoie une table vide si le fichier n’existe pas. Si le fichier existe, mais n’a pas été créé par sys.save(), est corrompu ou utilise un format de table sérialisée non pris en charge, sys.load() déclenche une erreur Lua. Utilisez pcall() comme ci-dessus lorsque les données de sauvegarde endommagées ou modifiées en dehors de l’application doivent pouvoir être récupérées.

Emplacements des fichiers et des dossiers

Les emplacements des fichiers et des dossiers peuvent être répartis en trois catégories :

• Fichiers propres à votre application, créés par celle-ci
• Fichiers et dossiers inclus dans le bundle de votre application
• Fichiers propres au système auxquels votre application accède

Comment enregistrer et charger des fichiers propres à l’application

Pour enregistrer et charger des fichiers propres à l’application, comme les meilleurs scores, les paramètres utilisateur et l’état du jeu, il est recommandé d’utiliser un emplacement fourni par le système d’exploitation et spécifiquement destiné à cet usage. Vous pouvez utiliser sys.get_save_file() pour obtenir le chemin absolu d’un fichier adapté au système d’exploitation. Une fois ce chemin absolu obtenu, vous pouvez utiliser les fonctions sys.*, io.* et os.* (voir ci-dessus).

Consultez l’exemple qui montre comment utiliser sys.save() et sys.load().

Comment accéder aux fichiers inclus dans le bundle de l’application

Vous pouvez inclure des fichiers dans votre application à l’aide de ressources de bundle et de ressources personnalisées.

Ressources personnalisées

Les ressources personnalisées sont incluses dans l’archive principale du jeu au moyen du champ Custom Resources de game.project.

Le champ Custom Resources doit contenir une liste de ressources séparées par des virgules qui seront incluses dans l’archive principale du jeu. Si des répertoires sont indiqués, tous les fichiers et répertoires qu’ils contiennent sont inclus de manière récursive. Vous pouvez lire les fichiers avec 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

Ressources de bundle

Les ressources de bundle sont des fichiers et dossiers supplémentaires intégrés au bundle de votre application à l’aide du champ Bundle Resources dans game.project.

Le champ Bundle Resources doit contenir une liste, séparée par des virgules, de répertoires contenant les fichiers et dossiers de ressources à copier tels quels dans le paquet résultant lors de la création du bundle. Les répertoires doivent être spécifiés par un chemin absolu à partir de la racine du projet, par exemple /res. Le répertoire des ressources doit contenir des sous-dossiers nommés selon platform ou architecture-platform.

Les plateformes prises en charge sont ios, android, osx, win32, linux, web, switch. Un sous-dossier nommé common est également autorisé, contenant les fichiers de ressources communs à toutes les plateformes. Exemple :

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

Vous pouvez utiliser sys.get_application_path() pour obtenir le chemin de l’emplacement où l’application est stockée. Utilisez ce chemin de base de l’application pour créer le chemin absolu final vers les fichiers auxquels vous devez accéder. Une fois que vous disposez du chemin absolu de ces fichiers, vous pouvez utiliser les fonctions io.* et os.* pour y accéder.

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)

Comparaison des ressources personnalisées et des ressources de bundle

Accès aux fichiers système

L’accès aux fichiers système peut être limité par le système d’exploitation pour des raisons de sécurité. Vous pouvez utiliser l’extension native extension-directories pour obtenir le chemin absolu de certains répertoires système courants (à savoir documents, resource, temp). Une fois le chemin absolu de ces fichiers obtenu, vous pouvez utiliser les fonctions io.* et os.* pour y accéder (voir ci-dessus).

Extensions

L’Asset Portal contient plusieurs ressources qui simplifient l’accès aux fichiers et aux dossiers. Quelques exemples :

• Lua File System (LFS) - Fonctions pour manipuler les répertoires, les autorisations des fichiers, etc.
• DefSave - Un module qui facilite l’enregistrement et le chargement de la configuration et des données du joueur entre les sessions.