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 дозволяє це за допомогою функції під назвою паки ресурсів (файли PCK з розширенням .pck або ZIP-файли).

Переваги:

покрокові оновлення / виправлення
пропонує DLC
пропонує підтримку модів
не потрібне розкриття вихідного коду для модів
більш модульна структура проєкту
користувачі не повинні замінювати всю гру

Перший етап їх використання включає експорт та доставку проєкту гравцям. Потім, коли пізніше потрібно додати функціональність або контент, оновлення просто доставляють користувачам у вигляді PCK/ZIP-файлів.

Файли PCK/ZIP зазвичай містять, але не обмежуються:

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

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

Можна одночасно завантажувати файли PCK та ZIP як додаткові пакети. Див. Формати файлів PCK та ZIP для порівняння двох форматів.

Дивись також

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

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

Питання безпеки

Важливо зазначити, що для завантаження файлів PCK, пов’язаних із патчами, модифікаціями або додатковим контентом, таким як доповнення, вам доведеться розробити систему, яка автоматично завантажуватиме файли залежно від їхнього розташування та, можливо, імені. Це створює вразливість безпеки у трьох випадках. По-перше, користувач завантажує модифікацію, що містить шкідливий код. По-друге, на комп’ютері кінцевого користувача вже існує шкідлива програма, яка замінила файл PCK на шкідливу копію. По-третє, ви розповсюджуєте файли PCK з патчами через запускач гри, і система зазнала атаки.

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

Питання авторського права

Якщо ви хочете використовувати файли PCK для розповсюдження додаткового платного контенту, наприклад, доповнень, майте на увазі, що Godot не надає готового способу запобігти копіюванню файлу PCK та його розміщенню на комп’ютері іншої особи. Якщо ви бажаєте це зробити, ви самі несете відповідальність за впровадження будь-якої системи DRM.

Генерування файлів PCK

Щоб упакувати всі ресурси проекту у файл PCK, відкрийте проект і перейдіть до менюm Project > Export, виберіть пресет експорту та натисніть кнопку Export PCK/ZIP.

Іншим методом було б export from the command line з --export-pack. Вихідний файл повинен мати розширення .pck або .zip. Процес експорту створить файл цього типу для вибраної платформи.

Внести зміни до файлів PCK

Створення файлів Patch PCK

Щоб створити файл PCK, який міститиме лише ті ресурси, яких немає в оригінальній версії проєкту, слід створити файл PCK-патча. Його можна використовувати для патчів, модифікацій або доповнень. Для цього спочатку потрібно мати файл PCK вашого проєкту на момент його первинного випуску.

Щоб створити файл PCK з патчами, у меню експорту, вибравши потрібний пресет, перейдіть на вкладку Patching. У нижній частині екрана знаходиться розділ Base Packs. Натисніть кнопку Add Pack, а потім виберіть експортований файл PCK, який містить усі елементи вашого проєкту для його початкового випуску.

Тепер, коли ви знову спробуєте експортувати файл PCK вашого проєкту, якщо ви натиснете кнопку Export as Patch, у файл PCK будуть експортовані лише ті ресурси, які зазнали змін.

Ви також можете додавати будь-які експортовані патчі до своїх базових пакетів для подальшого використання. Наприклад, додавання файлу patch.pck гарантує, що файл patch2.pck не міститиме жодних ресурсів із цього першого патча.

Кодування Дельта

Розмір файлів патчів PCK можна зменшити за допомогою дельта-кодування. Це дозволяє оновлювати лише ті частини файлу, які зазнали змін. Однак це має недолік у вигляді збільшення часу завантаження оновлених ресурсів, і кожен патч для ресурсу сукупно збільшує час його завантаження.

Окрім фільтрів, існує два параметри кодування «дельта»:

Рівень стиснення за алгоритмом Delta: визначає ступінь стиснення файлів. Ми не рекомендуємо встановлювати значення, яке перевищує стандартне значення 19. При більшому значенні для експорту та імпорту знадобиться більше пам’яті, а виграш у якості буде незначним. Будь-яке додатне значення забезпечить однакову швидкість розпакування, однак чим вище число, тим довше триватиме експорт. Від’ємні значення вмикають швидкий режим, що означає більший розмір файлів, але вищу швидкість розпакування.
Мінімальне скорочення розміру при дельта-кодуванні: визначає, на скільки щонайменше має бути зменшений розмір файлу, щоб для нього було застосовано стиснення. Наприклад, якщо встановлено рівень 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().