Робота з файлами

Є багато різних способів створювати файли та/або отримувати до них доступ. Шляхи до файлів і способи доступу до них залежать від типу та розташування файлу.

Функції для доступу до файлів і папок

Defold надає кілька різних функцій для роботи з файлами:

• Для читання й записування файлів можна використовувати стандартні функції io.*. Ці функції дають змогу дуже точно керувати всім процесом введення-виведення.

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

• Для перейменування й видалення файлів можна використовувати os.rename() та os.remove().

• Для читання й записування таблиць Lua можна використовувати sys.save() та sys.load(). Додаткові функції sys.* допомагають визначати шляхи до файлів незалежно від платформи.

-- 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() повертає порожню таблицю, якщо файл не існує. Якщо файл існує, але його створено не за допомогою sys.save(), він пошкоджений або використовує непідтримуваний формат серіалізованої таблиці, sys.load() спричиняє помилку Lua. Використовуйте pcall(), як показано вище, коли потрібно забезпечити відновлення після пошкодження або зовнішньої зміни збережених даних.

Розташування файлів і папок

Розташування файлів і папок можна поділити на три категорії:

• Файли застосунку, які створює ваш застосунок
• Файли й папки, що входять до пакета вашого застосунку
• Системні файли, до яких звертається ваш застосунок

Як зберігати й завантажувати файли застосунку

Для зберігання й завантаження файлів застосунку, як-от рекордів, налаштувань користувача та стану гри, рекомендовано використовувати розташування, яке операційна система надає спеціально для цієї мети. За допомогою sys.get_save_file() можна отримати абсолютний шлях до файлу для відповідної ОС. Отримавши абсолютний шлях, ви можете використовувати функції sys.*, io.* та os.* (див. вище).

Перегляньте приклад використання sys.save() і sys.load().

Як отримати доступ до файлів, що входять до пакета застосунку

Ви можете включити файли до свого застосунку за допомогою ресурсів пакета (bundle resources) та користувацьких ресурсів (custom resources).

Користувацькі ресурси

Користувацькі ресурси включають до основного архіву гри за допомогою поля Custom Resources у game.project.

Поле Custom Resources має містити розділений комами список ресурсів, які буде включено до основного архіву гри. Якщо вказано каталоги, усі вкладені файли та каталоги включаються рекурсивно. Читати ці файли можна за допомогою 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

Ресурси пакета

Ресурси пакета — це додаткові файли й папки, які включають до пакета застосунку за допомогою поля Bundle Resources у game.project.

Поле Bundle Resources має містити розділений комами список каталогів із файлами та папками ресурсів, які під час пакування потрібно скопіювати до кінцевого пакета без змін. Каталоги слід указувати абсолютними шляхами від кореня проєкту, наприклад /res. Каталог ресурсів має містити підпапки з іменами у форматі platform або architecture-platform.

Підтримувані платформи: ios, android, osx, win32, linux, web, switch. Також можна використовувати підпапку common для файлів ресурсів, спільних для всіх платформ. Приклад:

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

Ви можете використати sys.get_application_path(), щоб отримати шлях до розташування застосунку. На основі цього базового шляху сформуйте кінцеві абсолютні шляхи до потрібних файлів. Отримавши їх, ви зможете звертатися до файлів за допомогою функцій io.* та os.*.

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)

Порівняння користувацьких ресурсів і ресурсів пакета

Доступ до системних файлів

Операційна система може обмежувати доступ до системних файлів із міркувань безпеки. За допомогою нативного розширення extension-directories можна отримати абсолютний шлях до деяких поширених системних каталогів (наприклад, documents, resource, temp). Отримавши абсолютний шлях до цих файлів, ви можете використовувати функції io.* та os.* для доступу до них (див. вище).

Розширення

На порталі Defold Assets є кілька ресурсів для спрощення доступу до файлів і папок. Ось деякі приклади:

• Lua File System (LFS) — функції для роботи з каталогами, дозволами на доступ до файлів тощо
• DefSave — модуль, що допомагає зберігати й завантажувати налаштування та дані гравця між сеансами.