This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English

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

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

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

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

  • Вы можете использовать стандартные функции io.* для чтения и записи файлов. Эти функции дают вам очень тонкий контроль над процессом ввода-вывода.
-- открыть myfile.txt для записи в бинарном режиме
-- возвращает nil и сообщение об ошибке в случае неудачи
local f, err = io.open("path/to/myfile.txt", "wb")
if not f then
    print("Произошла ошибка при открытии файла", 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("Произошла ошибка при открытии файла", err)
    return
end

-- прочитать весь файл как строку
-- возвращает nil в случае неудачи
local s = f:read("*a")
if not s then
    print("Ошибка при чтении файла")
    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("Не удалось сохранить", path)
    return
end

-- загрузить данные
local data = sys.load(path)
print(data.highscore) -- 100

Расположение файлов и папок

Расположение файлов и папок можно разделить на три категории:

  • Файлы, созданные вашим приложением
  • Файлы и папки, включённые в ваше приложение
  • Системные файлы, к которым обращается ваше приложение

Как сохранять и загружать файлы, созданные приложением

При сохранении и загрузке файлов, созданных приложением, таких как рекорды, настройки пользователя и состояние игры, рекомендуется использовать расположение, предоставленное операционной системой и предназначенное специально для этой цели. Вы можете использовать sys.get_save_file(), чтобы получить абсолютный путь к файлу, специфичный для ОС. После получения абсолютного пути вы можете использовать функции sys.*, io.* и os.* (см. выше).

Посмотрите пример использования sys.save() и sys.load().

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

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

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

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

The Custom 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 using sys.load_resource().

-- Загрузить данные уровня в строку
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 are additional files and folders located as a part of your application bundle using the Bundle Resources field in game.project.

The Bundle 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 by platform, or architecture-platform.

Supported platforms are ios, android, osx, win32, linux, web, switch A subfolder named common 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 use sys.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 the io.* and os.* functions to access the files.

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)

По соображениям безопасности браузеры (и, следовательно, любой JavaScript, выполняющийся в браузере) не имеют доступа к системным файлам. Операции с файлами в HTML5 сборках Defold по-прежнему работают, но только в “виртуальной файловой системе” с использованием IndexedDB API в браузере. Это означает, что нет возможности получить доступ к ресурсам бандла с помощью функций io.* или os.*. Однако вы можете получить доступ к ресурсам бандла с помощью http.request().

Пользовательские и ресурсы бандла — сравнение

Характеристика Пользовательские ресурсы Ресурсы бандла
Скорость загрузки Быстрее — файлы загружаются из архива Медленнее — файлы загружаются из файловой системы
Загрузка части файла Нет — только целиком Да — можно читать произвольные байты файла
Изменение файлов после упаковки Нет — файлы хранятся внутри бинарного архива Да — файлы хранятся в локальной файловой системе
Поддержка HTML5 Да Да — но доступ через http, а не через файловый ввод-вывод

Доступ к системным файлам

Доступ к системным файлам может быть ограничен операционной системой по соображениям безопасности. Вы можете использовать нативное расширение extension-directories, чтобы получить абсолютные пути к некоторым распространённым системным папкам (например, документы, ресурсы, временные файлы). Получив абсолютный путь к этим файлам, вы можете использовать функции io.* и os.* для доступа к ним (см. выше).

По соображениям безопасности браузеры (и, следовательно, любой JavaScript, выполняющийся в браузере) не имеют доступа к системным файлам. Операции с файлами в HTML5 сборках Defold по-прежнему работают, но только в “виртуальной файловой системе” с использованием IndexedDB API в браузере. Это означает, что нет возможности получить доступ к системным файлам в HTML5 сборках.

Расширения

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

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