🥇Unity Package Manager

Unity to platforma, która istnieje od dłuższego czasu i ciągle się rozwija. Pracując w niej nad wieloma projektami jednocześnie, można jednak napotkać trudności w korzystaniu z wspólnych źródeł (.cs), bibliotek (.dll) oraz innych zasobów (obrazy, dźwięki, modele, prefabrykaty). W tym artykule podzielimy się naszym doświadczeniem w pracy z natywnym rozwiązaniem tego problemu dla Unity.

Metody dystrybucji wspólnych zasobów

Istnieje więcej niż jeden sposób wykorzystania wspólnych zasobów w różnych projektach, ale każdy z nich ma swoje zalety i wady.

1. Duplikowanie — ręczne duplikowanie zasobów między projektami.

Zalety:

Nadaje się do każdego rodzaju zasobów.
Brak problemów z zależnościami.
Brak problemów z GUID-ami zasobów.

Wady:

Ogromne repozytoria.
Brak możliwości wersjonowania.
Trudności w śledzeniu zmian w wspólnych zasobach.
Trudności w aktualizacji wspólnych zasobów.

2. Podmoduły Git — dystrybucja wspólnych zasobów poprzez zewnętrzne podmoduły.

Zalety:

Można pracować z kodem źródłowym.
Można dystrybuować zasoby.
Brak problemów z zależnościami.

Wady:

Wymagana umiejętność pracy z Git.
Git nie jest zbyt przyjazny dla plików binarnych — konieczne będzie włączenie LFS.
Wydzielanie dostępu do repozytoriów.
Trudności przy podnoszeniu i obniżaniu wersji.
Możliwe kolizje GUID-ów i brak jednoznacznego zachowania ze strony Unity w ich rozwiązywaniu.

3. NuGet — dystrybucja wspólnych bibliotek poprzez pakiety NuGet.

Zalety:

Wygodna praca z projektami, które nie są zależne od Unity.
Wygodne wersjonowanie i rozwiązywanie zależności.

Wady:

Unity nie potrafi pracować z pakietami NuGet 'z pudełka' (na GitHubie można znaleźć Menedżera Pakietów NuGet dla Unity, który to naprawia, ale są pewne niuanse).
Trudności w dystrybucji innych rodzajów zasobów.

4. Menadżer pakietów Unity — dystrybucja wspólnych zasobów poprzez natywne rozwiązanie dla Unity.

Zalety:

Natywny interfejs do pracy z pakietami.
Ochrona przed nadpisywaniem plików .meta w pakietach przy konfliktach GUID-ów.
Możliwość wersjonowania.
Możliwość dystrybucji wszystkich rodzajów zasobów dla Unity.

Wady:

Mogą nadal występować konflikty GUID-ów.
Brak dokumentacji do wdrożenia.

Ostatni sposób ma więcej zalet niż wad. Jednak obecnie nie jest zbyt popularny z powodu braku dokumentacji, dlatego szczegółowo omówimy ten temat.

Menadżer pakietów Unity

Unity Package Manager (dalej UPM) — narzędzie do zarządzania pakietami. Został dodany do Unity w wersji 2018.1 i był używany tylko dla pakietów opracowywanych przez Unity Technologies. Jednak od wersji 2018.3 pojawiła się możliwość dodawania niestandardowych pakietów.

Interfejs Unity Package Manager

Pakiety nie trafiają do źródeł projektu (katalog Assets). Znajdują się w oddzielnym katalogu %projectFolder%/Library/PackageCache i w żaden sposób nie wpływają na projekt, ich jedynym odniesieniem w źródłach jest plik packages/manifest.json.

Pakiety w systemie plików projektu

Źródła pakietów

UPM może korzystać z kilku źródeł pakietów:

1. System plików.

Zalety:

Szybkość realizacji.
Nie wymaga zewnętrznych narzędzi.

Wady:

Trudności z wersjonowaniem.
Wymagana wspólna dostępność systemu plików dla wszystkich, którzy pracują nad projektem.

2. Repozytorium Git.

Zalety:

Potrzebne jest tylko repozytorium Git.

Wady:

Nie można przełączać się między wersjami za pomocą okna UPM.
Nie działa ze wszystkimi repozytoriami Git.

3. Repozytorium npm.

Zalety:

W pełni wspiera funkcjonalność UPM i jest używane do dystrybucji oficjalnych pakietów Unity.

Wady:

Obecnie ignoruje wszystkie wersje pakietów w formacie tekstowym, oprócz „-preview”.

Poniżej omówimy realizację UPM + npm. Ten zestaw jest wygodny, ponieważ pozwala pracować z różnymi rodzajami zasobów oraz zarządzać wersjami pakietów, a także w pełni wspiera natywny interfejs UPM.

Jako repozytorium npm można użyć Verdaccio. Posiada szczegółową 文档, a do jego uruchomienia wystarczy dosłownie kilka komend.

Konfiguracja środowiska

Na początek należy zainstalować node.js.

Tworzenie pakietu

Aby utworzyć pakiet, należy umieścić plik package.json, który go opisuje, w katalogu ze zawartością tego pakietu. Należy wykonać następujące kroki:

Przejść do katalogu projektu, który chcemy zamienić w pakiet.

Wykonać komendę npm init i podczas dialogu wprowadzić wymagane wartości. Dla name podajemy nazwę w formacie odwrotnego domeny, na przykład com.plarium.somepackage.
Aby wygodnie wyświetlić nazwę pakietu — dodać właściwość displayName w package.json i wypełnić ją.

Ponieważ npm jest zorientowany na js, w pliku znajdują się nam niepotrzebne właściwości main i scripts, których Unity nie używa. Lepiej je usunąć, aby nie zagracać opisu pakietu. Plik powinien wyglądać mniej więcej tak:

Przejść do katalogu projektu, który chcemy zamienić w pakiet.
Wykonać komendę npm init i podczas dialogu wprowadzić wymagane wartości. Dla name podajemy nazwę w formacie odwrotnego domeny, na przykład com.plarium.somepackage.
Aby wygodnie wyświetlić nazwę pakietu — dodać właściwość displayName w package.json i wypełnić ją.
Ponieważ npm jest zorientowany na js, w pliku znajdują się nam niepotrzebne właściwości main i scripts, których Unity nie używa. Lepiej je usunąć, aby nie zagracać opisu pakietu. Plik powinien wyglądać mniej więcej tak:
```
{
 "name": "com.plarium.somepackage",
 "displayName": "Some Package",
 "version": "1.0.0",
 "description": "Some Package Description",
 "keywords": [
   "Unity",
   "UPM"
 ],
 "author": "AUTHOR",
 "license": "UNLICENSED"
}
```
Otwórz Unity i wygeneruj plik .meta dla package.json (Unity nie widzi zasobów bez plików .meta, pakiety dla Unity są otwierane tylko w trybie tylko do odczytu).

Wysyłanie pakietu

Aby wysłać pakiet, należy wykonać polecenie: npm publish --registry *adres do repozytorium pakietów*.

Instalowanie i aktualizowanie pakietów przez Unity Package Manager

Aby dodać pakiet do projektu Unity, należy:

Wprowadzić do pliku manifest.json informacje o źródle pakietów. W tym celu należy dodać właściwość scopedRegistries i wskazać zakresy oraz adres źródła, z którego będą wyszukiwane konkretne zakresy.
```
"scopedRegistries": [
   {
     "name": "Main",
     "url": "adres do repozytorium pakietów",
     "scopes": [
       "com.plarium"
     ]
   }
 ]
```
Przejdź do Unity i otwórz okno Package Managera (praca z niestandardowymi pakietami nie różni się od pracy z wbudowanymi).
Wybierz Wszystkie Pakiety.
Znajdź potrzebny pakiet i dodaj go.

Praca z kodem źródłowym i debugowanie

Aby połączyć kod źródłowy z projektem, należy utworzyć Assembly Definition dla pakietu.

Używanie pakietów nie ogranicza możliwości debugowania. Jednak podczas pracy z pakietami w Unity nie można przejść do IDE kliknięciem na błąd w konsoli, jeśli błąd wystąpił w pakiecie. Wynika to z tego, że Unity nie widzi skryptów jako osobnych plików, ponieważ przy użyciu Assembly Definition są one kompilowane do biblioteki i dołączane do projektu. Przy pracy z kodem źródłowym z projektu przejście do IDE po kliknięciu jest dostępne.

Skrypt w projekcie z podłączonym pakietem:

Skrypt z pakietu z działającym punktem przerwania:

Pilne wprowadzenie poprawek do pakietów

Pakiety Unity dodane do projektu są otwarte tylko do odczytu, ale można je edytować w pamięci podręcznej pakietów. W tym celu należy:

Przejść do pakietu w pamięci podręcznej pakietów.
Wprowadzić niezbędne zmiany.
Zaktualizować wersję w pliku package.json.
Wysłać pakiet npm publish --registry *adres do repozytorium pakietów*.
Zaktualizować wersję pakietu do poprawionej przez interfejs UPM.

Konflikty importu pakietów

Podczas importu pakietów mogą wystąpić następujące konflikty GUID:

Pakiet — pakiet. Jeśli podczas importu pakietu okaże się, że w już dodanych pakietach znajdują się zasoby z takim samym GUID, zasoby z powtarzającymi się GUID z importowanego pakietu nie zostaną dodane do projektu.
Pakiet to projekt. Jeśli podczas importu pakietu zostaną znalezione zasoby w projekcie z identycznymi GUID-ami, zasoby z pakietu nie zostaną dodane do projektu. Jednak zasoby od nich zależne zaczną korzystać z zasobów w projekcie.

Przenoszenie zasobów z projektu do pakietu

Jeśli przeniesiesz zasób z projektu do pakietu przy otwartym Unity, jego funkcjonalność zostanie zachowana, a odniesienia w zależnych zasobach zaczną korzystać z zasobu w pakiecie.

Ważne: przy kopiowaniu zasobu z projektu do pakietu wystąpi konflikt „Pakiet — projekt”, opisany w powyższej sekcji.

Możliwe rozwiązania konfliktów

Przypisanie GUID-ów według własnych algorytmów podczas importu wszystkich zasobów, aby wykluczyć kolizje.
Dodanie wszystkich zasobów do jednego projektu, a następnie ich podział na pakiety.
Utworzenie bazy danych zawierającej GUID-y wszystkich zasobów i przeprowadzenie walidacji podczas przesyłania pakietów.

Podsumowanie

UPM to nowe rozwiązanie do dystrybucji wspólnych zasobów w Unity, które może być godną alternatywą dla istniejących metod. Zalecenia opisane w artykule powstały na podstawie realnych przypadków. Mamy nadzieję, że będą przydatne.

Źródło: habr.com