Libraries

Функция Libraries позволяет делиться ресурсами между проектами. Это простой, но очень мощный механизм, который можно использовать в рабочем процессе разными способами.

Библиотеки полезны для следующих задач:

• Копирование ресурсов из завершенного проекта в новый. Если вы делаете продолжение предыдущей игры, это удобный способ быстро начать работу.
• Создание библиотеки шаблонов, которые можно копировать в проекты, а затем настраивать или специализировать.
• Создание одной или нескольких библиотек готовых объектов или скриптов, на которые можно ссылаться напрямую. Это особенно удобно для хранения общих script-модулей или общей библиотеки графики, звуков и анимационных ресурсов.

Настройка публикации библиотеки

Предположим, вы хотите создать библиотеку с общими sprites и tile source. Начните с создания нового проекта. Определите, какими папками из проекта вы хотите делиться, и добавьте имена этих папок в свойство include_dirs в настройках проекта. Если нужно указать несколько папок, разделяйте их имена пробелами:

Прежде чем мы сможем добавить эту библиотеку в другой проект, нужен способ найти саму библиотеку.

URL библиотеки

На библиотеки ссылаются через обычный URL. Для проекта, размещенного на GitHub, это будет URL релиза проекта:

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

Можно добавить имя пользователя и пароль/токен в URL библиотеки, чтобы выполнять basic access authentication при использовании библиотек, которые не являются публично доступными:

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

Поля username и password будут извлечены и добавлены в заголовок запроса Authorization. Это работает с любым сервером, который поддерживает basic access authorization.

Чтобы не хранить учетные данные в открытом виде прямо в URL библиотеки, можно использовать строковый шаблон замены и хранить их в переменных окружения:

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

В примере выше имя пользователя и токен будут прочитаны из системных переменных окружения PRIVATE_USERNAME и PRIVATE_TOKEN.

Аутентификация GitHub

Чтобы получать библиотеку из приватного репозитория на GitHub, нужно сгенерировать personal access token и использовать его как пароль.

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

Аутентификация GitLab

Чтобы получать библиотеку из приватного репозитория на GitLab, нужно сгенерировать personal access token и передать его как параметр URL.

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

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

При использовании basic access authentication access token и имя пользователя будут доступны для любого репозитория, используемого в проекте. В команде больше чем из одного человека это может стать проблемой. Чтобы решить эту проблему, для доступа к библиотеке в репозиторий следует использовать пользователя с правами “read only”. На GitHub для этого нужна организация, команда и пользователь, которому не требуется редактировать репозиторий (то есть достаточно read only доступа).

Шаги для GitHub:

• Создайте организацию
• Создайте команду внутри организации
• Перенесите нужный приватный репозиторий в вашу организацию
• Выдайте команде доступ “read only” к репозиторию
• Создайте или выберите пользователя, который будет частью этой команды
• Используйте описанную выше “basic access authentication”, чтобы создать personal access token для этого пользователя

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

Это решение было предложено на форуме Defold и обсуждалось в этой теме.

Настройка зависимостей библиотек

Откройте проект, из которого хотите получить доступ к библиотеке. В настройках проекта добавьте URL библиотеки в свойство dependencies. При необходимости можно указать несколько зависимых проектов. Просто добавляйте их по одному кнопкой + и удаляйте кнопкой -:

Теперь выберите Project ▸ Fetch Libraries, чтобы обновить зависимости библиотек. Это происходит автоматически каждый раз при открытии проекта, так что вручную делать это нужно только в том случае, если зависимости изменились без повторного открытия проекта. Такое происходит, если вы добавили или удалили библиотеку-зависимость, либо если кто-то изменил и синхронизировал один из библиотечных проектов-зависимостей.

После этого папки, которыми вы поделились, появятся в Assets pane, и вы сможете использовать весь опубликованный контент. Любые синхронизированные изменения, внесенные в библиотечный проект, будут доступны в вашем проекте.

Редактирование файлов в зависимостях библиотек

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

Если вам нужно изменить файлы библиотеки, создайте собственный fork библиотеки и вносите изменения там. Другой вариант — скопировать всю папку библиотеки в директорию проекта и использовать локальную копию. В этом случае локальная папка затенит исходную зависимость, а ссылку на зависимость нужно удалить из 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 в game.project в настройке Render.

Если вы копируете material и хотите использовать его во всех компонентах определенного типа, может быть полезно воспользоваться шаблонами на уровне проекта.

Сломанные ссылки

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

Конфликты имен

Поскольку в настройке проекта dependencies можно указать несколько URL проектов, вы можете столкнуться с конфликтом имен. Это происходит, если два или более зависимых проекта публикуют папку с одинаковым именем в настройке проекта include_dirs.

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