🥇Unity Package Manager

Unity è una piattaforma esistente da molto tempo e in continua evoluzione. Tuttavia, lavorando su più progetti contemporaneamente, si possono ancora incontrare delle difficoltà nell'utilizzo di sorgenti condivisi (.cs), librerie (.dll) e altri asset (immagini, suoni, modelli, prefab). In questo articolo condivideremo la nostra esperienza riguardo a una soluzione nativa a questo problema per Unity.

Metodi di distribuzione delle risorse comuni

Esistono più di un modo per utilizzare risorse comuni per diversi progetti, ma ogni approccio ha i suoi vantaggi e svantaggi.

1. Duplicazione — duplicare manualmente le risorse tra i progetti.

Vantaggi:

Adatto per tutti i tipi di risorse.
Nessun problema con le dipendenze.
Nessun problema con gli GUID degli asset.

Contro:

Repository enormi.
Nessuna possibilità di versioning.
Difficoltà nel monitorare le modifiche alle risorse comuni.
Difficoltà nell'aggiornare le risorse comuni.

2. Git submodules — distribuzione delle risorse comuni tramite moduli esterni.

Vantaggi:

È possibile lavorare con i sorgenti.
È possibile distribuire gli asset.
Nessun problema con le dipendenze.

Contro:

È necessaria una certa competenza con Git.
Git non è molto compatibile con i file binari — sarà necessario attivare LFS.
Controllo degli accessi per i repository.
Difficoltà nell'aggiornare o diminuire la versione.
Possibili conflitti di GUID e comportamento non univoco da parte di Unity per risolverli.

3. NuGet — distribuzione di librerie comuni tramite pacchetti NuGet.

Vantaggi:

Comoda gestione di progetti indipendenti da Unity.
Versioning e risoluzione delle dipendenze comodi.

Contro:

Unity non supporta i pacchetti NuGet "out of the box" (su GitHub si può trovare NuGet Package Manager for Unity, che risolve questo, ma ci sono delle complicazioni).
Difficoltà nella distribuzione di altri tipi di asset.

4. Unity Package Manager — distribuzione delle risorse comuni tramite una soluzione nativa per Unity.

Vantaggi:

Interfaccia nativa per lavorare con i pacchetti.
Protezione dalla sovrascrittura dei file .meta nei pacchetti in caso di conflitti di GUID.
Possibilità di versioning.
Possibilità di distribuzione di tutti i tipi di risorse per Unity.

Contro:

Conflitti di GUID possono comunque verificarsi.
Nessuna documentazione per l'implementazione.

L'ultimo metodo ha più vantaggi che svantaggi. Tuttavia, attualmente non è molto popolare a causa della mancanza di documentazione, quindi ci concentreremo su di esso in modo dettagliato.

Unity Package Manager

Unity Package Manager (di seguito UPM) è uno strumento per la gestione dei pacchetti. È stato introdotto in Unity 2018.1 ed è stato utilizzato solo per pacchetti sviluppati da Unity Technologies. Tuttavia, a partire dalla versione 2018.3 è stata introdotta la possibilità di aggiungere pacchetti personalizzati.

Interfaccia di Unity Package Manager

I pacchetti non vengono inclusi nei sorgenti del progetto (directory Assets). Si trovano in una directory separata %projectFolder%/Library/PackageCache e non influenzano in alcun modo il progetto, l'unico loro riferimento nei sorgenti è nel file packages/manifest.json.

Pacchetti nel file system del progetto

Fonti dei pacchetti

UPM può utilizzare più fonti di pacchetti:

1. File system.

Vantaggi:

Velocità di implementazione.
Non richiede strumenti esterni.

Contro:

Difficoltà di versioning.
È necessaria l'accessibilità al file system per tutti coloro che lavorano al progetto.

2. Repository Git.

Vantaggi:

Richiede solo un repository Git.

Contro:

Non è possibile passare tra le versioni tramite la finestra UPM.
Non funziona con tutti i repository Git.

3. Repository npm.

Vantaggi:

Supporta completamente la funzionalità UPM e viene utilizzato per distribuire pacchetti ufficiali Unity.

Contro:

Attualmente ignora tutte le versioni stringa dei pacchetti tranne "-preview".

Di seguito esamineremo l'implementazione di UPM + npm. Questa combinazione è comoda poiché consente di lavorare con qualsiasi tipo di risorsa e gestire le versioni dei pacchetti, oltre a supportare completamente l'interfaccia nativa UPM.

Come repository npm è possibile utilizzare Verdaccio. È disponibile una documentazione dettagliata documentazione, e per avviarlo saranno sufficienti solo un paio di comandi.

Configurazione dell'ambiente

Per iniziare è necessario installare node.js.

Creazione di un pacchetto

Per creare un pacchetto, è necessario inserire un file package.json, che ne descriva il contenuto, nella directory del pacchetto. Ecco i passaggi da seguire:

Accedere alla directory del progetto che si desidera creare come pacchetto.

Eseguire il comando npm init e durante il dialogo inserire i valori necessari. Per il nome indicare il nome nel formato inverso del dominio, ad esempio com.plarium.somepackage.
Per una visualizzazione comoda del nome del pacchetto — aggiungere la proprietà displayName nel package.json e compilarla.

Poiché npm è orientato a js, ci sono proprietà nel file che non ci interessano, come main e scripts, che Unity non utilizza. È meglio eliminarle per non appesantire la descrizione del pacchetto. Il file dovrebbe apparire più o meno così:

Accedere alla directory del progetto che si desidera creare come pacchetto.
Eseguire il comando npm init e durante il dialogo inserire i valori necessari. Per il nome indicare il nome nel formato inverso del dominio, ad esempio com.plarium.somepackage.
Per una visualizzazione comoda del nome del pacchetto — aggiungere la proprietà displayName nel package.json e compilarla.
Poiché npm è orientato a js, ci sono proprietà nel file che non ci interessano, come main e scripts, che Unity non utilizza. È meglio eliminarle per non appesantire la descrizione del pacchetto. Il file dovrebbe apparire più o meno così:
```
{
 "name": "com.plarium.somepackage",
 "displayName": "Some Package",
 "version": "1.0.0",
 "description": "Some Package Description",
 "keywords": [
   "Unity",
   "UPM"
 ],
 "author": "AUTHOR",
 "license": "UNLICENSED"
}
```
Apri Unity e genera il file .meta per package.json (Unity non riconosce le risorse senza file .meta, i pacchetti per Unity possono essere aperti solo in modalità di sola lettura).

Invio del pacchetto

Per inviare un pacchetto è necessario eseguire il comando: npm publish --registry *indirizzo del repository dei pacchetti*.

Installazione e aggiornamento dei pacchetti tramite Unity Package Manager

Per aggiungere un pacchetto a un progetto Unity, è necessario:

Modificare il file manifest.json informazioni sulla sorgente dei pacchetti. Per fare questo, è necessario aggiungere la proprietà scopedRegistries e specificare gli scope e l'indirizzo della sorgente da cui verranno cercati gli specifici scope.
```
"scopedRegistries": [
   {
     "name": "Main",
     "url": "indirizzo del repository dei pacchetti",
     "scopes": [
       "com.plarium"
     ]
   }
 ]
```
Vai su Unity e apri la finestra del Package Manager (lavorare con pacchetti personalizzati non è diverso dal lavorare con quelli integrati).
Seleziona All Packages.
Trova il pacchetto necessario e aggiungilo.

Lavorare con i sorgenti e il debugging

Per connettere i sorgenti al progetto, è necessario creare un Assembly Definition per il pacchetto.

L'uso dei pacchetti non limita le possibilità di debugging. Tuttavia, quando si lavora con i pacchetti in Unity, non è possibile passare all'IDE cliccando su un errore nella console, se l'errore è avvenuto nel pacchetto. Questo è dovuto al fatto che Unity non riconosce gli script come file separati poiché, utilizzando l'Assembly Definition, vengono compilati in una libreria e collegati al progetto. Quando si lavora con i sorgenti del progetto, il passaggio all'IDE cliccando è disponibile.

Script nel progetto con il pacchetto connesso:

Script dal pacchetto con breakpoint funzionante:

Modifiche urgenti ai pacchetti

I pacchetti Unity aggiunti al progetto sono aperti solo in modalità di sola lettura, ma possono essere modificati nella cache dei pacchetti. Per fare ciò è necessario:

Accedere al pacchetto nella cache dei pacchetti.
Apportare le modifiche necessarie.
Aggiornare la versione nel file package.json.
Inviare il pacchetto npm publish --registry *indirizzo del repository dei pacchetti*.
Aggiornare la versione del pacchetto a quella corretta tramite l'interfaccia UPM.

Conflitti di importazione dei pacchetti

Durante l'importazione dei pacchetti possono verificarsi i seguenti conflitti di GUID:

Pacchetto — pacchetto. Se durante l'importazione di un pacchetto viene rilevato che ci sono risorse con lo stesso GUID nei pacchetti già aggiunti, le risorse con GUID coincidenti del pacchetto importato non verranno aggiunte al progetto.
Pacchetto — progetto. Se durante l'importazione di un pacchetto viene rilevato che ci sono risorse nel progetto con GUID identici, le risorse del pacchetto non verranno aggiunte al progetto. Tuttavia, le risorse che dipendono da esse inizieranno a utilizzare le risorse del progetto.

Trasferimento delle risorse dal progetto al pacchetto

Se si trasferisce una risorsa dal progetto al pacchetto con Unity aperto, la sua funzionalità verrà mantenuta e i riferimenti nelle risorse dipendenti inizieranno a utilizzare la risorsa dal pacchetto.

Importante: nel copiare una risorsa dal progetto al pacchetto si verificherà un conflitto "Pacchetto — progetto", come descritto nella sezione precedente.

Possibili soluzioni ai conflitti

Riassegnazione dei GUID in base ai propri algoritmi durante l'importazione di tutte le risorse per escludere collisioni.
Aggiunta di tutte le risorse in un unico progetto e successiva suddivisione in pacchetti.
Creazione di un database contenente i GUID di tutte le risorse e validazione durante l'invio dei pacchetti.

Conclusione

UPM è una nuova soluzione per la distribuzione di risorse condivise su Unity, che può rappresentare una valida alternativa ai metodi esistenti. Le raccomandazioni descritte nell'articolo sono emerse da casi reali. Speriamo che vi siano utili.

Fonte: habr.com