Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Экспортирование пакетов, патчей и модов

Случаи использования

Зачастую возникает желание добавить функциональность в игру уже после ее развертывания.

Примеры этого включают...

Загружаемый контент: возможность добавлять функции и контент в свою игру.
Патчи: возможность исправить ошибку, которая присутствует в отправленном продукте.
Моды: предоставить другим людям возможность создавать контент для своей игры.

Эти инструменты помогают разработчикам расширить свою разработку за пределы первоначального выпуска.

Обзор файлов PCK/ZIP

Godot делает это возможным с помощью функции, называемой resource packs (файлами PCK с расширением .pck или файлами ZIP).

Преимущества:

дополнительные обновления/патчи
даёт возможность создавать DLC
даёт возможность поддержки модификаций(модов)
нет необходимости раскрывать исходный код для модов
более модульная структура проекта
пользователям не нужно заменять всю игру

Первая часть их использования включает экспорт и доставку проекта игрокам. Затем, когда позже требуется добавить функциональность или контент, они просто доставляют обновления пользователям через файлы PCK/ZIP.

Файлы PCK/ZIP обычно содержат, помимо прочего:

скрипты
сцены
шейдеры
модели
текстуры
звуковые эффекты
музыка
любой другой ассет, пригодный для импорта в игру

Файлы PCK/ZIP могут даже представлять собой совершенно другой проект Godot, который оригинальная игра загружает во время выполнения.

Можно одновременно загружать файлы PCK и ZIP в качестве дополнительных пакетов. Сравнение двух форматов см. в разделе PCK по сравнению с форматами файлов ZIP Pack.

См. также

Если вы хотите загрузить свободные файлы во время выполнения (не упакованные в PCK или ZIP-архив Godot), рассмотрите возможность использования Загрузка и сохранение файла времени выполнения. Это полезно для загрузки пользовательского контента, созданного не с помощью Godot, и не требует от пользователей упаковывать свои моды в определенный формат файла.

Недостатком такого подхода является то, что он менее прозрачен для игровой логики, поскольку не позволяет использовать те же преимущества управления ресурсами, что и файлы PCK/ZIP.

Проблемы с безопасностью

Важно отметить, что загрузка PCK-файлов для патчей, модов или дополнительного контента, такого как расширения, потребует от вас создания системы для автоматической загрузки файлов на основе их местоположения и, возможно, имени. Это представляет собой уязвимость безопасности в трёх сценариях. Во-первых, пользователь загружает мод со вредоносным кодом. Во-вторых, вредоносная программа уже существует на ПК конечного пользователя и заменила PCK-файл вредоносной копией. В-третьих, вы распространяете PCK-файлы патчей через лаунчер игры, и система была скомпрометирована.

Принимайте это во внимание при определении способа использования PCK-файлов в проекте. Для ситуаций, когда у вас есть система патчей через лаунчер, рассмотрите возможность использования асимметричной криптографии. Вы можете хранить открытый ключ в основном PCK, а файлы патчей или расширений подписывать закрытым ключом. Дополнительную информацию см. в классе Crypto.

Вопросы авторского права

Если вы хотите использовать PCK-файлы для распространения дополнительного платного контента, например, расширений, имейте в виду, что Godot не предоставляет готового способа предотвратить копирование PCK-файла и его передачу на другой компьютер. Внедрение любой системы DRM является вашей ответственностью, если вы этого хотите.

Создание файлов PCK

Чтобы упаковать все ресурсы проекта в PCK-файл, откройте проект и перейдите в Проект > Экспорт, выберите пресет экспорта и нажмите Экспорт PCK/ZIP.

Another method would be to export from the command line with --export-pack. The output file must end with a .pck or .zip file extension. The export process will build that type of file for the chosen platform.

Файлы патчей PCK

Генерация файлов патчей PCK

Чтобы создать PCK-файл, содержащий только ресурсы, отсутствующие в исходном релизе проекта, вы создадите файл патча PCK. Это можно использовать для патчей, модов или расширений. Для этого вам сначала понадобится PCK-файл вашего проекта на момент первоначального релиза.

Чтобы сгенерировать файл патча PCK, в меню экспорта с выбранным нужным пресетом перейдите на вкладку Patching. Внизу находится раздел Base Packs. Нажмите кнопку Add Pack, затем перейдите к экспортированному PCK-файлу, который содержит всё, что было в вашем проекте на момент первоначального релиза.

Теперь, когда вы снова экспортируете PCK-файл проекта, если выбрана кнопка Export as Patch, в PCK-файл будут экспортированы только изменённые ресурсы.

Вы также можете добавлять любые экспортированные патчи в свои базовые пакеты для будущего использования. Например, добавление patch.pck гарантирует, что patch2.pck не будет включать ресурсы из первого патча.

Дельта-кодирование

Файлы патчей PCK можно сделать меньше с помощью дельта-кодирования. Это обеспечивает обновление только изменённых частей файла. Это имеет недостаток в виде более длительного времени загрузки обновлённых ресурсов, и каждый патч для ресурса кумулятивно увеличивает его время загрузки.

Помимо фильтров, для дельта-кодирования предусмотрены два дополнительных параметра:

Delta Encoding Compression Level: Управляет степенью сжатия файлов. Мы не рекомендуем значения выше значения по умолчанию 19. За пределами этого требуется больше памяти для экспорта и импорта при значительно меньшем выигрыше. Любые положительные значения будут иметь одинаковую скорость распаковки, однако экспорт будет занимать больше времени при большем числе. Отрицательные значения включают быстрый режим, что означает большие файлы, но более высокую скорость распаковки.
Delta Encoding Minimum Size Reduction: Управляет тем, сколько размера должно быть сохранено как минимум для использования сжатия на отдельном файле. Например, при уровне 10%, если размер файла можно уменьшить только на 5%, то для этого файла дельта-кодирование не будет использоваться.

Обычный уровень сжатия составляет 19, это максимальный рекомендованный уровень.

Для достижения минимально возможного размера патча мы рекомендуем отключать сжатие для любых ресурсов, которые вы хотите патчить. Даже если ваши базовые PCK-файлы были сжаты, это не должно вызвать проблем.

Сжатие можно отключить в нескольких местах для разных ресурсов:

Настройки импорта, связанные со сжатием отдельных импортируемых ресурсов, таких как файлы переводов или 3D-моделей
Compress Binary Resources в настройках редактора
GDScript Export Mode на вкладке Scripts пресета экспорта

Примечание

После отключения Compress Binary Resources необходимо удалить содержимое папки .godot/imported/ вашего проекта, затем закрыть и снова открыть проект, чтобы перегенерировать его.

Важно отметить, что при экспорте дельта-кодированного патча поверх предыдущих патчей пакеты, перечисленные в Base Packs на вкладке Patching, должны быть теми же самыми файлами, которые загружаются игрой во время выполнения, в том же порядке, в котором они загружаются. Повторный экспорт предыдущих версий может привести к небольшим отличиям из-за недетерминизма в процессе экспорта Godot, что может привести к сбою патча. Это относится только к дельта-кодированным патчам, обычные не имеют этой проблемы.

Открытие файлов PCK или ZIP во время выполнения

Для загрузки файла PCK или ZIP используется синглтон ProjectSettings. В следующем примере ожидается наличие файла mod.pck в каталоге исполняемого файла игры. Файл PCK или ZIP содержит в своем корневом каталоге тестовую сцену mod_scene.tscn.

func _your_function():
    # This could fail if, for example, mod.pck cannot be found.
    var success = ProjectSettings.load_resource_pack(OS.get_executable_path().get_base_dir().path_join("mod.pck"))

    if success:
        # Now one can use the assets as if they had them in the project from the start.
        var imported_scene = load("res://mod_scene.tscn")

private void YourFunction()
{
    // This could fail if, for example, mod.pck cannot be found.
    var success = ProjectSettings.LoadResourcePack(OS.GetExecutablePath().GetBaseDir().PathJoin("mod.pck"));

    if (success)
    {
        // Now one can use the assets as if they had them in the project from the start.
        var importedScene = (PackedScene)ResourceLoader.Load("res://mod_scene.tscn");
    }
}

Предупреждение

По умолчанию, если вы импортируете файл с тем же путем/именем, что и у файла, который уже есть в вашем проекте, импортируемый файл заменит его. На это следует обращать внимание при создании DLC или модов. Эту проблему можно решить, используя инструмент, который изолирует моды в определенной подпапке mods.

Однако это также способ создания патчей для собственной игры. Такой PCK/ZIP-файл может исправить содержимое ранее загруженного PCK/ZIP-архива (поэтому порядок загрузки пакетов имеет значение).

Чтобы отказаться от этого поведения, передайте false в качестве второго аргумента функции ProjectSettings.load_resource_pack().

Примечание

Для проекта C# вам необходимо сначала создать DLL и поместить его в каталог проекта. Затем перед загрузкой пакета ресурсов вам необходимо загрузить этот DLL следующим образом: Assembly.LoadFile("mod.dll")

Устранение неполадок

Если вы загружаете пакет ресурсов и не замечаете никаких изменений, это может быть связано с тем, что пакет был загружен слишком поздно. Это особенно актуально для сцен меню, которые могут предварительно загружать другие сцены, используя preload(). Это означает, что загрузка пакета в меню не повлияет на другую сцену, которая уже была предварительно загружена.

Чтобы избежать этого, необходимо загрузить пакет как можно раньше. Для этого создайте новый скрипт autoload и вызовите ProjectSettings.load_resource_pack() в скрипте автозагрузки функцию _init(), скорее, чем _enter_tree() или _ready().

Соображения по моддингу

Если вы хотите поддерживать моды для своей игры, вам потребуется, чтобы ваши пользователи создавали аналогично экспортированные файлы. Предполагая, что исходная игра ожидает определённую структуру ресурсов PCK и/или определённый интерфейс для своих скриптов, необходимо сделать одно из двух.

Разработчик должен задокументировать ожидаемые структуры/
Разработчик должен опубликовать документацию по этим ожидаемым структурам/интерфейсам, ожидать, что моддеры установят Godot Engine, а затем также ожидать, что эти моддеры будут соответствовать заданному в документации API при создании мод-контента для игры (чтобы он работал). Затем пользователи будут использовать встроенные инструменты экспорта Godot для создания PCK-файла, как описано выше.
Разработчик использует Godot для создания GUI-инструмента для добавления своего точного API
контента в проект. Этот инструмент Godot должен работать на сборке движка с поддержкой инструментов или иметь доступ к такой сборке (распространяемой вместе с игрой или, возможно, в её файлах). Затем инструмент может использовать исполняемый файл Godot для экспорта PCK-файла из командной строки с помощью OS.execute(). Сама игра не должна использовать инструментальную сборку движка (в целях безопасности), поэтому лучше держать инструмент для моддинга и игру отдельно.