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

Существует множество различных способов создания и/или доступа к файлам. Пути к файлам и способы доступа к ним зависят от типа файла и его расположения.

Функции для доступа к файлам и папкам

Defold предоставляет несколько разных функций для работы с файлами:

• Вы можете использовать стандартные функции io.* для чтения и записи файлов. Эти функции дают вам очень тонкий контроль над процессом ввода-вывода.

-- открыть myfile.txt для записи в двоичном режиме
-- при ошибке возвращает nil и сообщение об ошибке
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

-- записать данные в файл, сбросить их на диск и закрыть файл
f:write("Foobar")
f:flush()
f:close()

-- открыть myfile.txt для чтения в двоичном режиме
-- при ошибке возвращает nil и сообщение об ошибке
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

-- прочитать весь файл как строку
-- при ошибке возвращает nil
local s = f:read("*a")
if not s then
	print("Error while reading file")
	return
end

print(s) -- Foobar

• Вы можете использовать os.rename() и os.remove() для переименования и удаления файлов.

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

-- получить независимый от платформы путь к файлу "highscore" для приложения "mygame"
local path = sys.get_save_file("mygame", "highscore")

-- сохранить таблицу Lua с данными
local ok = sys.save(path, { highscore = 100 })
if not ok then
	print("Failed to save", path)
	return
end

-- загрузить данные
local ok, data = pcall(sys.load, path)
if not ok then
	-- Файл существует, но повреждён, создан другим способом или имеет неподдерживаемый формат.
	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().

Как получить доступ к файлам, включённым в приложение

Вы можете включать файлы в ваше приложение с помощью ресурсов бандла и пользовательских ресурсов.

Пользовательские ресурсы

Custom resources упаковываются в основной архив игры с помощью поля Custom Resources в game.project.

Поле Custom Resources должно содержать список ресурсов, разделённых запятыми, которые будут включены в основной архив игры. Если указаны каталоги, все файлы и папки в этих каталогах будут включены рекурсивно. Читать эти файлы можно с помощью sys.load_resource().

Расширения также могут добавлять эти файлы через ext.properties. Их пути объединяются с пользовательскими ресурсами проекта как в сборках редактора, так и в архивах Bob. См. раздел Пользовательские ресурсы расширений.

-- Загрузить данные уровня в строку
local data, error = sys.load_resource("/assets/level_data.json")
-- Декодировать json строку в Lua таблицу
if data then
  local data_table = json.decode(data)
  pprint(data_table)
else
  print(error)
end

Ресурсы бандла

Bundle resources — это дополнительные файлы и каталоги, расположенные как часть application bundle с использованием поля 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.* для доступа к ним (см. выше).

Расширения

Asset Portal содержит несколько ассетов, упрощающих работу с файлами и папками. Некоторые примеры:

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