Un outil pour partager vos propres packages Unity avec OpenUPM

Il y a deux ans, j’ai écrit un article sur la gestion de vos propres assets dans le Package Manager de Unity. Ce n’était ni simple ni très pratique, il fallait donc améliorer tout ça. Un bon point de départ à l’époque avait été de séparer les packages, pour que chacun ait son propre dépôt git.

Unity a aussi fait un beau geste pour les développeurs : ils ont abandonné l’Asset Store pour la gestion des assets et utilisent désormais le Package Manager à la place (enfin !).

Tout l’intérêt de partager des packages, c’est d’avoir à la fois des blocs de code autonomes et du code et/ou des assets que vous pouvez utiliser dans plusieurs projets.

Voyons donc quel est le nouveau workflow :

1. mettre à jour un package sur github (le workflow openupm est branché sur github)
2. configurer le package sur openupm
3. ajouter openupm comme scoped registry dans les project settings.

Mettre à jour le package sur GiT

Je ne vous ferai pas l’affront de vous expliquer comment créer un dépôt git et faire un commit sur github, mais il y a tout de même quelques règles à suivre.

Pour que le package soit utilisable dans le Package Manager, vous devez créer un fichier nommé package.json dans le dossier de l’asset, conforme au modèle de package.json, voir l’exemple ci-dessous.

Une bonne pratique consiste aussi à avoir les fichiers README.md et CHANGELOG.md à la racine de votre dossier, pour que tout le monde (vous, votre équipe, l’autre développeur qui tomberait sur votre package) sache facilement ce que fait votre package, et le… eh bien, le changelog. Le fichier readme sert aussi à choisir une image d’aperçu par défaut pour le navigateur de packages d’openupm.

Donc, votre code et vos assets sont correctement structurés en package (voir mon article précédent pour les détails) et vous avez tout commité sur github, avec un tag.

Une fois que c’est fait, vous pouvez ajouter le package manuellement dans Unity, mais ça ne suffit pas.

Configurer le package sur OpenUPM

Allez sur openupm.com et remplissez le formulaire : nom du dépôt, branche, sélection du fichier package.json s’il n’est pas sélectionné par défaut (utile quand il est dans un sous-dossier), readme et licence. Voici ci-dessous la première étape : une fois l’URL du dépôt saisie (évidemment, il doit être public !), un clic sur le bouton Go lance la recherche des informations et des fichiers par openUpm.

Si votre configuration sort de l’ordinaire, vous pouvez aussi filtrer sur le nom du package, ajouter un préfixe pour le tag de version, et même une version minimale à builder.

Vous pouvez choisir une image d’aperçu à cette étape, mais je vous le déconseille : lors des mises à jour, il est plus simple de changer l’image dans le fichier readme que de modifier la description sur openupm.

Une fois le formulaire rempli, il vous faudra terminer le workflow et attendre que le traitement nocturne soit passé pour voir le package depuis Unity et dans le registre de packages openUPM.

Mais pour l’instant, vous en avez fini avec openUPM : le reste fonctionnera pour toujours et vous n’aurez pas besoin d’y revenir avant un bon moment.

Ajouter openUPM comme scoped registry dans Unity

Dernière étape de ce nouveau workflow : depuis le projet dans lequel vous voulez ajouter votre package, allez dans les project settings, dans la section package manager, où vous pouvez ajouter un scoped registry.

Depuis ce même registre, openUPM, vous pouvez ajouter plusieurs scopes si vous y trouvez d’autres assets utiles : pensez donc à ajouter tous les scopes voulus pour que Unity aille les chercher au bon endroit.

Une fois que c’est fait, vous verrez les registres correspondants dans le Package Manager de Unity, dans la section « My Registries ». Comme pour n’importe quel autre package, vous pouvez installer, mettre à jour et supprimer les packages directement ici, et ils apparaîtront dans le dossier « Packages » de votre projet.

Mon outil gratuit pour vous : Unity Package Tool

Pourtant, un autre problème me gênait : je n’ai aucun workflow de CI/CD pour ces assets, notamment quand je mets à jour la version d’un package et que je l’utilise dans un autre.

Avec plusieurs assemblies, je peux indiquer à Unity quel autre package est requis pour que la compilation fonctionne. Et avec le nom de version dans le fichier package.json, vous pouvez préciser les dépendances exactes, que le Package Manager utilise pour rechercher, télécharger ou mettre à jour automatiquement les autres packages.

Mais comment relier les deux ? Par défaut, c’est impossible.

Bonne nouvelle : avec le UnityPackageTool que j’ai créé, vous n’êtes qu’à un clic d’y arriver.

Ce que fait l’outil :

1. créer une liste des fichiers d’assembly definition à partir des packages du projet
2. lister les fichiers packages.json et leurs assemblies runtime correspondantes
3. pour chaque package trouvé, mettre à jour les dépendances à partir de l’assembly definition en trouvant la version correspondante dans les autres packages.json ou dans le package Unity.

Le dernier point était un peu délicat, car il faut utiliser toutes les assemblies connues dans le projet Unity et une API asynchrone du Package Manager, puis trouver la version dont le nom d’assembly correspond au format suivant :

<com.package.name>@<version>

Au final, il vous suffit de cliquer sur « Update dependencies » depuis Window/FredericRP pour mettre à jour tous les fichiers packages.json de votre projet avec les bonnes dépendances (nom de package et version) trouvées à partir du fichier d’assembly definition !

Vous l’aurez compris, j’avais besoin de cet outil parce que j’ai plusieurs packages qui fonctionnent ensemble. Par exemple, le package GameQuest utilise beaucoup d’autres packages comme EventManagement, Singleton, et TextMeshPro : quand je le mets à jour, je veux m’assurer que tout est synchronisé. J’utilise aussi leurs versions à jour, et il m’arrive de mettre à jour d’autres packages en fonction des besoins du package principal.

Avec cet outil, plus besoin de me demander s’il y a eu une autre mise à jour dans le projet : il corrige tout simplement le fichier package.json de l’asset que je veux commiter !

Avantages et inconvénients

Côté positif, cette configuration permet de partager des packages avec d’autres projets et de s’assurer qu’ils ont les bonnes dépendances en un seul clic. Vous pouvez aussi vérifier que tout fonctionne bien sur la page de votre package, dans la section des build pipelines :

Côté négatif, cela vous empêche de corriger un problème ou de faire évoluer le code depuis le projet où le package est ajouté : les packages importés de cette façon sont en lecture seule. Il vous faudra donc parfois mettre à jour votre package dans son projet source, puis attendre le traitement nocturne pour qu’il soit disponible dans le Package Manager. Mais j’ai un planning qui me permet de passer à une autre tâche si un package doit être mis à jour pour de nouveaux besoins ou des corrections.

C’est la méthode la plus simple que j’ai trouvée pour partager des packages entre plusieurs projets et les rendre accessibles à tous. Comme je le disais, vous pouvez trouver mes packages, et bien sûr cet outil, sur github.fredericrp.com et sur openupm.com en cherchant les packages « fredericrp. ». Dites-moi si vous trouvez ça excessif et/ou si vous connaissez une meilleure méthode !