Unity Package Manager

Unity — платформа, която съществува от доста време и постоянно се развива. Въпреки това, когато работите с няколко проекта едновременно в нея, все още можете да се сблъскате с трудности при използването на общи изходни файлове (.cs), библиотеки (.dll) и други активи (изображения, звуци, модели, префабрики). В тази статия ще споделим нашия опит с нативното решение на подобен проблем за Unity.

Методи за разпространение на общи ресурси

Съществуват повече от един начин да се използват общи ресурси за различни проекти, но всеки от подходите има своите плюсове и минуси.

1. Дублиране — „на ръка“ дублираме ресурсите между проектите.

Плюсове:

• Подходящо за всички видове ресурси.
• Няма проблеми със зависимостите.
• Няма проблеми с GUID-овете на активите.

Недостатъци:

• Гигантски хранилища.
• Няма възможност за версиониране.
• Трудност при проследяване на промените в общите ресурси.
• Трудност при обновяване на общите ресурси.

2. Git подмодули — разпространение на общи ресурси чрез външни подмодули.

Плюсове:

• Може да се работи с изходни файлове.
• Може да се разпространяват активи.
• Няма проблеми със зависимостите.

Недостатъци:

• Необходим е опит в работата с Git.
• Git не се справя особено добре с бинарни файлове — ще трябва да включите LFS.
• Разграничаване на достъпа до хранилищата.
• Трудности при повишаване и понижаване на версията.
• Възможни са конфликти на GUID-ове и Unity няма еднозначно поведение за тяхното разрешаване.

3. NuGet — разпространение на общи библиотеки чрез NuGet пакети.

Плюсове:

• Удобна работа с проекти, независими от Unity.
• Удобно версиониране и разрешаване на зависимости.

Недостатъци:

• Unity не може да работи с NuGet пакети "извън кутията" (в GitHub можете да намерите NuGet Package Manager for Unity, който оправя това, но има нюанси).
• Трудности при разпространение на останалите видове активи.

4. Unity Package Manager — разпространение на общи ресурси чрез нативно решение за Unity.

Плюсове:

• Нативен интерфейс за работа с пакети.
• Защита от презаписване на .meta файловете в пакетите при конфликти на GUID-ове.
• Възможност за версиониране.
• Възможност за разпространение на всички видове ресурси за Unity.

Недостатъци:

• Все още могат да се случват конфликти на GUID-ове.
• Няма документация за реализация.

Последният метод има повече предимства, отколкото недостатъци. Въпреки това, той не е много популярен в момента поради липса на документация и затова ще се спрем на него подробно.

Unity Package Manager

Unity Package Manager (наричен UPM) — инструмент за управление на пакетите. Той беше добавен в Unity 2018.1 и първоначално се използваше само за пакети, разработвани от Unity Technologies. Въпреки това, с версия 2018.3 се появи възможност за добавяне на персонализирани пакети.

Интерфейс на Unity Package Manager

Пакетите не влиза в изходния код на проекта (директория Assets). Те се намират в отделна директория %projectFolder%/Library/PackageCache и не влияят на проекта, единственото им споменаване в изходния код е във файла packages/manifest.json.

Пакети в файловата система на проекта

Източници на пакети

UPM може да използва няколко източника на пакети:

1. Файлова система.

Плюсове:

• Скорост на изпълнение.
• Не изисква външни инструменти.

Недостатъци:

• Сложност при версионирането.
• Необходим е общ достъп до файловата система за всички, които работят по проекта.

2. Git-репозиторий.

Плюсове:

• Необходим е само Git-репозиторий.

Недостатъци:

• Не може да се превключва между версиите чрез прозореца на UPM.
• Не работи с всички Git-репозитории.

3. npm-репозиторий.

Плюсове:

• Напълно поддържа функционалността на UPM и се използва за разпространение на официални пакети на Unity.

Недостатъци:

• В момента игнорира всички стринг версии на пакетите, освен „-preview“.

Наскоро ще разгледаме реализацията на UPM + npm. Тази комбинация е удобна, тъй като позволява работа с всички видове ресурси и управление на версиите на пакетите, а също така напълно поддържа нативния интерфейс на UPM.

Като npm-репозиторий може да се използва Verdaccio. Има подробна информация за него, документацияи за неговото стартиране ще са необходими буквално няколко команди.

Настройка на средата

Първо, трябва да инсталирате node.js.

Създаване на пакет

За да създадете пакет, е необходимо да поставите файла package.json, който го описва, в директорията със съдържанието на пакета. Трябва да направите следното:

Да отидете в директорията на проекта, която искате да направите пакет.

Да изпълните командата npm init и по време на диалога да въведете необходимите стойности. За name укажете име в реверс домейн формат, например com.plarium.somepackage.
За удобно показване на името на пакета — добавете свойство displayName в package.json и го попълнете.

Тъй като npm е ориентиран към js, файла съдържа ненужните ни свойства main и scripts, които Unity не използва. По-добре е да ги премахнете, за да не запълвате описанието на пакета. Файлът трябва да изглежда приблизително така:

1. Да отидете в директорията на проекта, която искате да направите пакет.
2. Да изпълните командата npm init и по време на диалога да въведете необходимите стойности. За name укажете име в реверс домейн формат, например com.plarium.somepackage.
3. За удобно показване на името на пакета — добавете свойство displayName в package.json и го попълнете.
4. Тъй като npm е ориентиран към js, файла съдържа ненужните ни свойства main и scripts, които Unity не използва. По-добре е да ги премахнете, за да не запълвате описанието на пакета. Файлът трябва да изглежда приблизително така:

   {
    "name": "com.plarium.somepackage",
    "displayName": "Some Package",
    "version": "1.0.0",
    "description": "Some Package Description",
    "keywords": [
      "Unity",
      "UPM"
    ],
    "author": "AUTHOR",
    "license": "UNLICENSED"
   }

5. Отворете Unity и генерирайте .meta файл за package.json (Unity не вижда активите без .meta файлов, пакетите за Unity се отварят само за четене).

Изпращане на пакета

За да изпратите пакета, е необходимо да изпълните командата: npm publish --registry *адрес на хранилището на пакети*.

Инсталиране и актуализиране на пакети чрез Unity Package Manager

За да добавите пакет в Unity проекта, трябва да:

1. Добавите в файла manifest.json информация за източниците на пакети. За целта трябва да добавите свойството scopedRegistries и да посочите скоуповете и адреса на източника, по който ще се търсят конкретните скоупове.

   
   "scopedRegistries": [
      {
        "name": "Main",
        "url": "адрес на хранилището на пакети",
        "scopes": [
          "com.plarium"
        ]
      }
    ]
   

2. Преход към Unity и отваряне на прозореца на Package Manager (работата с кастомни пакети не се различава от работата с вградени).
3. Изберете Всички пакети.
4. Намерете нужния пакет и го добавете.

Работа с изходния код и отладка

За да се свърже изходният код с проекта, е необходимо да създадете Assembly Definition за пакета.

Използването на пакети не ограничава възможностите за отладка. Обаче, при работа с пакети в Unity, не можете да преминете в IDE при клик на грешка в конзолата, ако грешката е настъпила в пакета. Това се дължи на това, че Unity не вижда скриптовете като отделни файлове, тъй като при използване на Assembly Definition те се компилират в библиотека и се свързват с проекта. При работа с изходен код от проекта, преходът към IDE при клик е наличен.

Скрипт в проекта с включен пакет:

Скрипт от пакета с работеща точка за прекъсване:

Спешно въвеждане на поправки в пакетите

Добавените в проекта пакети на Unity са отворени само за четене, но могат да бъдат редактирани в кеша на пакетите. За да направите това:

1. Преминете към пакета в кеша на пакетите.

   

2. Внесете необходимите промени.
3. Актуализирайте версията в файла package.json.
4. Изпратете пакета npm publish --registry *адрес на хранилището на пакети*.
5. Актуализирайте версията на пакета до поправената чрез интерфейса на UPM.

Конфликти при импорта на пакети

При импортиране на пакети могат да възникнат следните конфликти на GUID-ове:

1. Пакет — пакет. Ако при импортиране на пакет се установи, че в вече добавените пакети има активи с такъв същ GUID, активите с съвпаднали GUID от импортирания пакет няма да бъдат добавени в проекта.
2. Пакет — проект. Ако при импортиране на пакета се установи, че в проекта има асети с съвпадащи GUID, асетите от пакета няма да бъдат добавени в проекта. Въпреки това асетите, зависими от тях, ще започнат да използват асетите от проекта.

Пренос на асети от проекта в пакета

Ако пренесете асет от проекта в пакета, докато Unity е отворен, функционалността му ще остане същата, а връзките в зависимите асети ще започнат да използват асета от пакета.

Важно: при копиране на асет от проекта в пакета ще възникне конфликт „Пакет — проект“, описан в предходния раздел.

Възможни решения на конфликтите

1. Преопределяне на GUID-овете по собствени алгоритми при импортиране на всички асети, за да се избегнат колизии.
2. Добавяне на всички асети в един проект с последващо разделяне на пакети.
3. Създаване на база данни, съдържаща GUID-овете на всички асети, и провеждане на валидация при изпращане на пакетите.

Заключение

UPM — ново решение за разпространение на общи ресурси в Unity, което може да бъде достойна алтернатива на съществуващите методи. Препоръките, описани в статията, са възникнали на базата на реални казуси. Надяваме се, че ще ви бъдат полезни.

Източник: habr.com