Оновлення вмісту за допомогою Live update

Під час пакування гри Defold включає всі ігрові ресурси до кінцевого пакета для відповідної платформи. У більшості випадків це бажано, оскільки запущений рушій має миттєвий доступ до всіх ресурсів і може швидко завантажувати їх зі сховища. Однак іноді потрібно відкласти завантаження ресурсів на пізніший етап. Наприклад:

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

Функціональність Live update розширює концепцію проксі колекції (collection proxy) механізмом, за допомогою якого середовище виконання може отримувати та зберігати в пакеті застосунку ресурси, навмисно виключені з пакета під час збирання.

Це дає змогу розділити вміст на кілька архівів:

• Базовий архів
• Спільні файли рівнів
• Набір рівнів 1
• Набір рівнів 2
• …

Підготовка вмісту для Live update

Припустімо, ми створюємо гру, що містить великі ресурси зображень високої роздільної здатності. Гра зберігає ці зображення в колекціях (collection) з ігровим об’єктом (game object) і спрайтом із зображенням:

Щоб рушій завантажував таку колекцію динамічно, можна просто додати компонент (component) проксі колекції та вказати для нього monalisa.collection. Тепер гра може вибирати, коли завантажувати вміст колекції зі сховища в пам’ять, надсилаючи повідомлення load проксі колекції. Однак ми хочемо піти далі й самостійно керувати завантаженням ресурсів, що містяться в колекції.

Для цього достатньо встановити прапорець Exclude у властивостях проксі колекції, вказавши Defold не включати вміст monalisa.collection під час створення пакета застосунку.

Налаштування Live update

Коли Defold створює пакет застосунку, виключені ресурси потрібно десь зберегти. Налаштування проєкту для Live update визначають розташування цих ресурсів. Відкрити налаштування можна через Project ▸ Live update Settings.... Якщо файлу налаштувань ще немає, його буде створено. У game.project виберіть, який файл налаштувань Live update використовувати під час пакування. Це дає змогу використовувати різні налаштування Live update для різних середовищ, наприклад робочого, QA, розробки тощо.

Наразі Defold може зберігати ресурси трьома способами. Виберіть спосіб у розкривному списку Mode у вікні налаштувань:

Zip

Цей параметр указує Defold створити файл архіву Zip з усіма виключеними ресурсами. Архів зберігається в розташуванні, указаному в налаштуванні Export path, і його можна змонтувати під час виконання за допомогою URI zip: та liveupdate.add_mount().

Folder

Цей параметр указує Defold створити папку з усіма виключеними ресурсами. Це корисно, коли потрібно додатково обробити файли перед їх передаванням на сервер або пакуванням. Папку з окремими скомпільованими файлами, розміщеними за очікуваними шляхами ресурсів, можна змонтувати під час виконання за допомогою URI file:.

Amazon

Цей параметр указує Defold автоматично передавати виключені ресурси до кошика S3 Amazon Web Service (AWS). Введіть назву свого профілю AWS у полі Credential profile, виберіть відповідний Bucket і вкажіть назву Prefix. Докладніше про налаштування облікового запису AWS можна прочитати в цьому посібнику з AWS

Пакування з Live update

Запакувати гру з Live update просто. Виберіть Project ▸ Bundle ▸ ..., а потім платформу, для якої хочете створити пакет застосунку. Відкриється діалогове вікно пакування:

Під час пакування всі виключені ресурси буде вилучено з пакета застосунку. Установивши прапорець Publish Live update content, ви вказуєте Defold передати виключені ресурси до Amazon або створити архів Zip залежно від ваших налаштувань Live update (див. вище). Опублікований вміст Live Update і далі містить liveupdate.game.dmanifest, у якому є повний список ресурсів, потрібний для віддаленого доставлення.

Під час публікування вмісту Live Update Defold автоматично вилучає записи, що стосуються лише Live Update, із включеного до пакета файлу game.dmanifest, тоді як опублікований liveupdate.game.dmanifest зберігає повний список ресурсів. Це зменшує розмір пакета й використання пам’яті під час виконання. Колишнє налаштування liveupdate.exclude_entries_from_main_manifest вилучено; якщо відповідний запис залишився в проєкті, його буде проігноровано.

У процесі роботи з архівами collectionproxy.get_resources() повертає {}, доки відповідний архів не буде змонтовано. Після монтування функція повертає хеші ресурсів для цього проксі.

Натисніть Package і виберіть розташування для пакета застосунку. Тепер можна запустити застосунок і перевірити, чи все працює належним чином.

Архіви .zip

Файл .zip для Live update містить файли, виключені з базового пакета гри.

Хоча наш поточний процес підтримує створення лише одного файлу .zip, його можна розділити на менші файли .zip. Це дає змогу зменшити обсяг окремих завантажень для гри: наборів рівнів, сезонного вмісту тощо. Кожен файл .zip також містить файл маніфесту, який описує метадані кожного ресурсу в цьому файлі .zip.

Поділ архівів .zip

Часто бажано розділити виключений вміст на кілька менших архівів для точнішого керування використанням ресурсів. Наприклад, гру з рівнями можна розділити на кілька наборів рівнів. Інший приклад — помістити оформлення інтерфейсу для різних свят в окремі архіви та завантажувати й монтувати лише тему, актуальну за календарем.

Граф ресурсів зберігається в build/default/game.graph.json і автоматично генерується під час кожного пакування проєкту. Згенерований файл містить список усіх ресурсів проєкту та залежностей кожного ресурсу. Приклад запису:

{
  "path" : "/game/player.goc",
  "hexDigest" : "caa342ec99794de45b63735b203e83ba60d7e5a1",
  "children" : [ "/game/ship.spritec", "/game/player.scriptc" ]
}

Кожен запис має поле path, яке містить унікальний шлях ресурсу в проєкті. Поле hexDigest містить криптографічний відбиток ресурсу, який використовується як ім’я файлу в архіві .zip для Live update. Нарешті, поле children — це список інших залежностей, від яких залежить цей ресурс. У наведеному вище прикладі /game/player.goc залежить від спрайта й компонента-скрипту.

Ви можете розібрати файл game.graph.json і використати цю інформацію, щоб визначити групи записів у графі ресурсів та зберегти відповідні ресурси в окремих архівах разом з оригінальним файлом маніфесту (під час виконання файл маніфесту буде скорочено так, щоб він містив лише файли з архіву).

Live Update на Android

Для завантаження й монтування вмісту Live Update можна використовувати Play Asset Delivery. Докладніше читайте в офіційному посібнику.

Перевірка вмісту

Одна з основних можливостей системи Live update — використання багатьох архівів вмісту, потенційно створених різними версіями Defold.

За замовчуванням liveupdate.add_mount() перевіряє версію рушія під час додавання точки монтування. Це означає, що і базовий архів гри, і архіви Live update потрібно створювати одночасно тією самою версією рушія за допомогою пакування. Через це всі раніше завантажені клієнтом архіви стануть недійсними, і клієнту доведеться завантажити вміст повторно.

Цю поведінку можна вимкнути за допомогою прапорця в параметрах. Якщо її вимкнено, відповідальність за перевірку вмісту повністю лежить на розробнику, який має гарантувати, що кожен архів Live update працюватиме із запущеним рушієм.

Рекомендуємо зберігати метадані для кожної точки монтування, щоб застосунок міг вирішити, чи має пакет залишатися змонтованим. Перевіряйте їх після додавання точки монтування, зокрема коли застосунок повторно додає потрібні точки монтування під час запуску. Один зі способів зробити це — додати ще один файл до архіву Zip після пакування гри. Наприклад, додайте metadata.json з будь-якою потрібною грі інформацією, а після монтування отримайте його за допомогою sys.load_resource("/metadata.json"). Використовуйте унікальний шлях ресурсу для власних даних кожної точки монтування, інакше пошук ресурсу поверне файл із точки монтування з найвищим пріоритетом.

Якщо цього не зробити, вміст може виявитися зовсім несумісним із рушієм, що змусить його завершити роботу.

Точки монтування

Система Live update може використовувати кілька архівів вмісту одночасно. Кожен архів «монтується» до системи ресурсів рушія з назвою та пріоритетом.

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

Рушій не зберігає посилання на ресурси в точці монтування. Щойно ресурс завантажено в пам’ять, архів можна демонтувати. Ресурс залишатиметься в пам’яті, доки його не буде вивантажено.

Точки монтування діють лише протягом поточного сеансу рушія. Після перезапуску застосунок має знову викликати liveupdate.add_mount() для кожного потрібного пакета. Зберігайте розташування пакета, назву й пріоритет точки монтування в постійних даних, якими керує застосунок, якщо ці параметри потрібно зберігати між сеансами.

Робота з Live Update у скриптах

Щоб використовувати вміст Live update, потрібно завантажити дані та змонтувати їх у грі. Докладніше про роботу з Live update у скриптах читайте тут.

Особливості розробки

Налагодження

Під час запуску запакованої версії гри ви не маєте прямого доступу до консолі. Це ускладнює налагодження. Проте ви можете запустити застосунок із командного рядка або безпосередньо двічі клацнути виконуваний файл у пакеті:

Тепер гра запускається з вікном оболонки, у якому відображається виведення всіх викликів print():

Примусове повторне завантаження ресурсів

Розробник може завантажити вміст до будь-якого файлу чи папки, але часто він розташований у каталозі застосунку. Розташування папки підтримки застосунку залежить від операційної системи. Його можна дізнатися за допомогою print(sys.get_save_file("", "")). Щоб примусово запустити завантаження, видаліть завантажений пакет і відповідний запис із будь-яких даних стану, якими керує застосунок. Списку точок монтування, яким керує рушій і який можна було б видалити, немає; точки монтування не зберігаються між перезапусками.