Бібліотеки

Бібліотеки (Libraries) дають змогу спільно використовувати ресурси в різних проєктах. Це простий, але дуже потужний механізм, який можна по-різному застосовувати у своєму робочому процесі.

Бібліотеки корисні для таких завдань:

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

Налаштування спільного використання бібліотеки

Припустімо, ви хочете створити бібліотеку зі спільними спрайтами та джерелами плиток (tile sources). Почніть зі створення нового проєкту. Визначте, які папки проєкту потрібно надати для спільного використання, і додайте їхні назви до властивості include_dirs у налаштуваннях проєкту. Якщо потрібно вказати кілька папок, розділіть їхні назви пробілами:

Перш ніж додати цю бібліотеку до іншого проєкту, потрібно визначити, як її знайти.

URL бібліотеки

На бібліотеки посилаються за допомогою стандартного URL. Для проєкту, розміщеного на GitHub, це буде URL випуску проєкту:

Базова автентифікація доступу

До URL бібліотеки можна додати ім’я користувача та пароль або токен для базової автентифікації доступу під час використання бібліотек, які не є загальнодоступними:

https://username:password@github.com/defold/private/archive/main.zip

Поля username і password буде видобуто й додано як заголовок запиту Authorization. Це працює з будь-яким сервером, який підтримує базову авторизацію доступу.

Щоб уникнути випадкового витоку облікових даних через їх зберігання у відкритому вигляді в URL бібліотеки, можна також використати шаблон заміни рядків і зберігати облікові дані у змінних середовища:

https://__PRIVATE_USERNAME__:__PRIVATE_TOKEN__@github.com/defold/private/archive/main.zip

У наведеному вище прикладі ім’я користувача й токен буде зчитано із системних змінних середовища PRIVATE_USERNAME і PRIVATE_TOKEN.

Автентифікація на GitHub

Щоб завантажувати дані з приватного репозиторію на GitHub, потрібно створити персональний токен доступу і використовувати його як пароль.

https://github-username:personal-access-token@github.com/defold/private/archive/main.zip

Автентифікація на GitLab

Щоб завантажувати дані з приватного репозиторію на GitLab, потрібно створити персональний токен доступу і передавати його як параметр URL.

https://gitlab.com/defold/private/-/archive/main/test-main.zip?private_token=personal-access-token

Розширена автентифікація доступу

За базової автентифікації доступу токен доступу та ім’я користувача будуть доступні у всіх репозиторіях, які використовуються для проєкту. У команді з кількох людей це може стати проблемою. Щоб її вирішити, для доступу до бібліотеки в репозиторії потрібно використовувати користувача з правами «лише для читання». На GitHub для цього потрібні організація, команда й користувач, якому не потрібно редагувати репозиторій (тобто достатньо прав лише для читання).

Кроки для GitHub:

• Створіть організацію
• Створіть команду в організації
• Перенесіть потрібний приватний репозиторій до своєї організації
• Надайте команді доступ до репозиторію «лише для читання»
• Створіть або виберіть користувача, який буде учасником цієї команди
• Скористайтеся описаною вище базовою автентифікацією доступу, щоб створити персональний токен доступу для цього користувача

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

Це рішення запропонували на форумі Defold і обговорили в цій темі.

Налаштування залежностей від бібліотек

Відкрийте проєкт, з якого хочете отримувати доступ до бібліотеки. У налаштуваннях проєкту додайте URL бібліотеки до властивості dependencies. За потреби можна вказати кілька проєктів-залежностей. Додавайте їх по одному за допомогою кнопки + і видаляйте за допомогою кнопки -:

Тепер виберіть Project ▸ Fetch Libraries, щоб оновити залежності від бібліотек. Це відбувається автоматично щоразу, коли ви відкриваєте проєкт, тож виконувати цю дію потрібно лише тоді, коли залежності змінилися, а ви не відкривали проєкт повторно. Таке трапляється, якщо ви додаєте або видаляєте бібліотеки-залежності, або хтось змінює та синхронізує один із проєктів бібліотек-залежностей.

Тепер папки, які ви надали для спільного використання, з’являться на панелі Assets, і ви зможете користуватися всім їхнім вмістом. Усі синхронізовані зміни в проєкті бібліотеки будуть доступні у вашому проєкті.

Редагування файлів у бібліотеках-залежностях

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

Якщо ви хочете змінювати файли бібліотеки, створіть власний форк бібліотеки та вносьте зміни в ньому. Інший варіант — скопіювати й вставити всю папку бібліотеки до каталогу свого проєкту та використовувати локальну копію. У такому разі локальна папка матиме пріоритет над початковою залежністю, а посилання на залежність слід видалити з game.project (після цього не забудьте вибрати Project ▸ Fetch Libraries).

builtins — це також бібліотека, яку надає рушій. Якщо ви хочете редагувати її файли, скопіюйте їх до свого проєкту й використовуйте ці копії замість початкових файлів builtins. Наприклад, щоб змінити default.render_script, скопіюйте обидва файли /builtins/render/default.render і /builtins/render/default.render_script до папки свого проєкту як my_custom.render і my_custom.render_script. Потім змініть локальний файл my_custom.render, щоб він посилався на my_custom.render_script замість вбудованого скрипту, і вкажіть власний файл my_custom.render у налаштуванні Render у game.project.

Якщо ви копіюєте й вставляєте матеріал і хочете використовувати його в усіх компонентах (components) певного типу, можуть стати в пригоді шаблони для окремого проєкту.

Пошкоджені посилання

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

Колізії імен

Оскільки в налаштуванні проєкту dependencies можна вказати URL кількох проєктів, ви можете зіткнутися з колізією імен. Вона виникає, якщо у двох або більше проєктах-залежностях у налаштуванні include_dirs вказано папки з однаковою назвою для спільного використання.

Defold розв’язує колізії імен, просто ігноруючи всі посилання на папки з однаковою назвою, крім останнього, за порядком URL проєктів у списку dependencies. Наприклад, якщо ви вкажете в залежностях URL 3 проєктів бібліотек і кожен із них надаватиме для спільного використання папку з назвою items, відображатиметься лише одна папка items — та, що належить проєкту, який стоїть останнім у списку URL.