Vos assets dans le Package Manager d'Unity depuis un sous-dossier Git

Depuis la fermeture de mon studio de jeux vidéo, j’ai réussi à reconstruire une version améliorée des assets que nous avions conçus à cette époque. Pour mes propres projets comme pour ceux des autres, c’est un moyen simple d’améliorer rapidement un projet de jeu, alors j’ai commencé à les partager sur github.com/FredericRP et même directement sur l’asset store, gratuitement.

Avec le Package Manager, désormais utilisé à la fois pour les packages Unity et pour les packages des éditeurs de l’asset store, et avec de plus en plus d’assets à publier, une question revenait sans cesse : comment permettre d’importer facilement uniquement les assets souhaités, tout en gardant une gestion de versions simple à partager avec tout le monde ?

Après réflexion et quelques discussions avec d’autres développeurs de jeux, la réponse était en fait très simple : je devais modifier mon dépôt GiT pour qu’on puisse choisir quoi importer dans le Package Manager, sans avoir à se battre avec la ligne de commande. Plus simple à gérer pour moi, plus simple pour chacun de choisir l’asset précis dont il a besoin ou le package complet, sans avoir à découper le dépôt. J’ai rencontré quelques problèmes, alors je partage ici ce qui a fonctionné pour moi.

Quelques règles

J’ai rédigé quelques exigences que je voulais respecter :

1. continuer à utiliser mon dépôt « Standard Assets »
2. importer facilement un ou plusieurs assets dans n’importe quel projet Unity
3. ne pas utiliser de plugin tiers pour le processus d’import
4. se limiter à des serveurs de confiance ou connus (Unity, GitHub, etc.)

Le point de départ

La hiérarchie que j’utilise dans le dépôt reprend celle de mes projets précédents : un dossier racine, et un dossier par asset.

Comme on le voit ci-dessus, j’utilisais le sous-dossier spécial « Plugins » d’un seul dépôt pour l’inclure dans mes projets Unity. Ce dossier spécial permet d’indiquer à Unity de le compiler dans un assembly avant les autres. Vous verrez que cela va changer. À partir de ce dossier, j’exportais un package unique qui contenait tout. Un fichier README pour l’ensemble des assets, et un autre dans chaque sous-dossier, qui n’était en gros qu’un copier/coller du paragraphe correspondant.

Maintenant, je dois comprendre quels changements apporter à la hiérarchie des dossiers et comment les importer dans Unity sans erreur.

Il faut savoir que l’import d’un sous-dossier dans le Package Manager ne fonctionne qu’à partir de Unity 2020.1.a21, MAIS la fonctionnalité a aussi été rétroportée dans Unity 2019.3.4f1. Je l’ai testée dans Unity 2020.1.0b7 et 2019.3.5f1.

Pour la plupart des assets, cela ne devrait pas poser de problème de les importer dans une autre version de Unity (au moins une version 2018), mais si vous rencontrez un souci et devez utiliser une version spécifique, n’hésitez pas à me demander de l’aide.

Modifications de la hiérarchie des dossiers

Le sous-dossier Plugins pourrait rester, cela n’a pas d’importance pour l’instant, mais je déplace les images de chaque asset dans leur sous-dossier « Documentation~ » respectif, ce qui me permet de garder un aperçu depuis la page principale GitHub tout en ayant tout regroupé dans le sous-dossier de chaque asset.

Pour chaque asset, je dois respecter la structure de package demandée : je dois déplacer tous les scripts et autres assets dans le sous-dossier « Runtime », à l’exception des assets d’éditeur, qui doivent aller dans le sous-dossier « Editor ».

J’avais déjà un fichier README.MD, je dois donc simplement le mettre à jour pour utiliser les images présentes dans le sous-dossier de chaque asset et non plus celles du dossier d’images racine. Pour l’instant, je le copie/colle aussi dans le sous-dossier « Documentation~ » pour que le Package Manager le trouve également.

GiT lit le README dans le dossier racine, le Package Manager l’exige dans le sous-dossier Documentation.

Bonne nouvelle : je voulais ajouter un changelog sans jamais vraiment prendre le temps de le faire. C’est le moment idéal ! Et puisque même Unity le suggère, je vais aussi suivre les conseils de « Keep a changelog ».

Voilà pour la nouvelle hiérarchie.

Import dans Unity — place au vrai travail

J’utilise à la fois Bitbucket et GitHub comme dépôts en ligne principaux, et comme j’ai commencé avec Bitbucket, j’ai l’habitude de SourceTree et de son interface graphique. J’ai essayé d’autres interfaces, sans jamais retrouver le même niveau de satisfaction à la fois comme « outil de travail » et comme outil « agréable à utiliser », donc je continue à l’utiliser (le fait que j’aie développé un temps sur Mac compte peut-être aussi, car il était plus stable et sans erreur sur Mac avant de l’être sur Windows).

Avec SourceTree, le git utilisé est intégré par défaut, et vous pouvez tout à fait continuer à l’utiliser si vous le souhaitez. Pour l’authentification, j’utilise des clés SSH privée/publique et le logiciel pageant, lui aussi inclus avec SourceTree, donc c’est assez simple si vous vous en tenez à cela.

Unity ne sait pas que vous utilisez pageant et n’est pas capable, par défaut, d’utiliser votre clé privée ni de vous demander de saisir la passphrase.

Il faut donc le lui indiquer, c’est-à-dire indiquer à Windows où il se trouve, à l’aide d’une variable d’environnement.

GIT_SSH

Définissez cette variable d’environnement avec le chemin de l’exécutable « /tools/putty/plink » de SourceTree. N’ajoutez pas de guillemets dans la variable, même si le chemin contient des espaces : GiT s’en occupe, et cela ajouterait des guillemets inutiles qui casseraient la ligne de commande. Par exemple, la mienne est définie ainsi :

C:\Users\FredericRP\AppData\Local\SourceTree\app-3.3.7\tools\putty\plink.exe

Attention : pageant doit déjà être chargé avec votre clé, car vous ne pourrez ni la définir ni saisir la passphrase depuis le Unity Package Manager (UPM). Cela ne devrait pas poser de problème si vous travaillez quotidiennement sur vos projets, puisque vous avez sûrement déjà pageant lancé avec votre ou vos clés.

Dès lors, vous pouvez ajouter un asset à partir de son dépôt git, comme git@github.com:FredericRP/Standard-Assets.git, et même préciser un asset situé dans un sous-dossier, comme /BucketGenerator, directement depuis l’UPM !

Cliquez sur « add » dans le Package Manager et saisissez l’URL ci-dessous.

git@github.com:FredericRP/Standard-Assets.git?path=/BucketGenerator

D’ailleurs, vous pouvez consulter les assets disponibles sur la page GitHub FredericRP Standard Assets.

Si vous avez un asset sans aucune dépendance, c’est presque terminé : la dernière étape consiste à créer un package en bonne et due forme.

Assemblies et package

C’est quelque chose que je voulais changer depuis le début : chaque asset ne devrait pas être recompilé à chaque fois que quelqu’un modifie un script dans son projet. Le dossier spécial Plugins le permet, mais si je veux mettre à jour un seul asset, c’est tout l’ensemble qui est recompilé. J’ai donc décidé de créer aussi une assembly definition pour chaque asset. En fait, c’est également obligatoire lorsque vous créez un package géré par Unity.

J’espère que cela n’augmente pas l’empreinte mémoire d’une manière ou d’une autre, mais je n’ai pas encore eu le temps de le vérifier : si vous avez des infos, partagez-les en commentaire !

Chaque assembly ajoute un petit fichier dans chaque sous-dossier Runtime et Editor, nommé d’après l’asset ; veillez à bien suivre ces règles également. Il vous suffit de cliquer sur « Create / Assembly Definition » dans le bon dossier (sous-dossier Runtime et/ou Editor de votre package), de nommer le fichier en conséquence, et c’est tout !

La dernière étape pour obtenir un package compatible consiste à créer un fichier nommé package.json dans le dossier de l’asset, conforme au modèle de package.json, et le tour est joué. Voici un exemple ci-dessous.

Vous devriez maintenant avoir un dossier comme celui-ci :

Import dans l’UPM

Une fois tout en place, j’ai essayé d’importer le package le plus simple : celui de l’Asset Bundle Tool (vous remarquerez la description remarquable).

Succès ! Oh, c’était presque trop facile, non ?

En effet.

Pour les packages sans dépendance, il n’y a plus aucun problème après cela. Mais la plupart de mes packages les plus évolués dépendent des plus simples, dommage.

---

Dépendances personnalisées

J’ai donc essayé d’ajouter des dépendances avec le même format SCP (c’est-à-dire une source de package comme git@github:FredericRP/etc), mais malheureusement, ce format n’est pas reconnu.

Après quelques recherches, j’ai découvert que les packages personnalisés ne peuvent avoir aucune dépendance. Il s’agirait d’une raison de sécurité, pour qu’un package ne puisse pas ajouter un package caché contenant un malware, comme cela peut arriver avec npm. Je le comprends, mais je veux quand même partager mes packages.

Une solution consiste à rendre vos propres scripts hébergés visibles depuis l’UPM, ce qui nécessite un scoped registry correctement configuré. Par exemple, le nom de mes packages commence par « com.fredericrp », c’est leur scope, et je pourrais utiliser GitHub pour publier les packages, puisqu’il peut servir de scoped registry.

La solution pour votre propre studio

L’UPM connaît le registre de packages Unity, mais aucun autre. Vous pouvez en ajouter un vous-même en ajoutant les lignes suivantes dans le fichier project manifest :

Le voici en texte pour que vous puissiez le copier/coller :

“scopedRegistries”: [
{
“name”: “FredericRP Standard Assets”,
“url”: “https://npm.pkg.github.com/@fredericrp“,
“scopes”: [ “com.fredericrp” ]
}
]

Une fois cette étape réalisée pour un projet, vous pouvez ajouter n’importe quel package de ce registre simplement avec son nom !

Je n’ai pas retenu cette solution, car elle demande trop d’étapes pour des utilisateurs lambda, mais je l’ai testée pour bien comprendre toutes les étapes.

Si vous voulez créer le registre de votre propre studio et y donner accès à vos collègues, je pense que c’est la meilleure solution !

Vous devrez :

• créer un access token (github / developer settings, avec les permissions read:packages, repo, write:packages)
• vous connecter avec npm (si vous n’avez pas de compte, créez-en un sur npmjs.org)
• créer un fichier “upmconfig.toml” contenant des identifiants valides.

Si vous voulez un contrôle précis sur vos packages ou ne souhaitez pas utiliser GitHub, vous pouvez aussi créer votre propre registre de packages avec Verdaccio, hébergé sur votre propre serveur. Une approche plus complète et plus aboutie est OpenUPM, qui fait un excellent travail !

Vous pouvez également ajouter la ligne suivante dans votre fichier package.json pour publier sur votre compte GitHub (en changeant le nom du compte, bien sûr) :

“publishConfig”: { “registry”: “https://npm.pkg.github.com/@fredericrp” }

Une fois tout cela fait, utilisez la commande standard npm publish pour envoyer et publier votre package, afin qu’il soit disponible pour les autres développeurs (ceux qui ont les permissions sur le dépôt).

Mais… est-ce que cela répond à mes besoins ?

Bon, c’est très bien pour un registre de packages privé. Mais moi, je veux partager des packages pour que tout le monde puisse y accéder facilement, et ça, ce n’est pas simple !

Un développeur a publié un core package qui ajoute un nouveau scoped registry lorsque le package « core » est importé, hébergé sur son serveur, ce qui permet d’importer facilement les autres packages. Je ne ferai pas ça, c’est ma règle n°4. Il a aussi utilisé NewtonSoftJson pour lire et écrire le fichier project manifest, ce qui enfreint également ma règle n°3.

À ce stade, je me suis dit qu’il y avait deux solutions :

a. utiliser l’API de l’Unity Asset Store pour y publier directement les packages.

b. trouver un moyen d’ajouter des dépendances depuis le dépôt d’une manière ou d’une autre.

Malheureusement, il n’existe pas d’API de l’asset store pour publier des packages, ou alors je ne l’ai pas trouvée. Je ne connais que les API pour récupérer les ventes. Je suis donc parti sur la solution (b) !

Si vous voulez juste la réponse et pas le cheminement, passez la partie suivante :)

Le retour des dépendances personnalisées

Au lieu d’utiliser la clé « dependencies » du fichier package.json, j’y ai ajouté une clé « custom-dependencies » :

Chaque dépendance contient l’URL GiT complète avec une version, par exemple :

git@github.com:FredericRP/Standard-Assets.git?path=/Singleton#1.0.0

Ensuite, j’ajoute un script nommé « DependencyUpdater » avec l’attribut [InitializeOnLoad], pour pouvoir exécuter une méthode dès que le package est importé par Unity.

Ce script fait les choses suivantes :

• demander à l’UPM la liste actuelle des packages (inutile de vérifier le statut en ligne, il vient de le faire puisque nous avons importé un package)
• lire le fichier package.json pour vérifier s’il y a des dépendances personnalisées
• les ajouter à la liste des packages du projet

Je filtre la liste des packages pour ne vérifier que les miens, donc ceux dont le nom commence par « com.fredericrp ».

Le fichier package.json se trouve sous packageInfo.resolvedPath dans cette liste (en fait, l’AssetDatabase peut aussi vous donner accès aux fichiers du package : il faut utiliser le nom du package avec le préfixe « /Packages/ », sans la version).

Grâce à une classe interne personnalisée, je peux utiliser JsonUtility pour lire ce fichier de package (c’est la règle n°3). Un problème que j’ai rencontré ici, cependant : un dictionnaire comme celui utilisé pour lister les dépendances dans un fichier de package standard ne peut pas être lu par le JsonUtility de Unity : il s’appuie sur la sérialisation, et les Dictionary n’en font pas partie (j’aurais pu utiliser la sérialisation de System à la place, mais l’étape suivante montrera que cela n’avait pas d’importance). C’est pourquoi j’ai fait de la valeur « dependencies » une liste de chaînes contenant à la fois le nom et la version.

Rappelez-vous que nous utilisons l’URL GiT complète avec le chemin du sous-dossier, et non le vrai nom de l’asset. Après cette lecture, le script ajoute les packages comme l’utilisateur l’a fait pour le premier, avec la méthode UnityEditor.PackageManager.Client.AddRequest. Aussi simple que ça.

Utiliser ce « custom dependency updater » signifie que chaque package (ayant des dépendances) doit contenir ce script, et que celui-ci devrait se supprimer après usage pour ne pas entrer en conflit avec les autres packages lors de leur import (ou n’exister que dans le namespace du package, quel gaspillage d’espace). Une autre solution serait de le publier comme package gratuit sur l’asset store et de le laisser gérer l’import de tous les packages, mais je ne suis pas sûr que Unity accepterait un asset qui contourne une limitation de sécurité qu’ils ont eux-mêmes mise en place.

C’était amusant à créer et ça m’a appris un peu plus sur la façon dont les packages sont gérés, donc vous pouvez le trouver dans son propre dépôt ! Mais ce n’est toujours pas la solution.

Un autre développeur a codé un outil assez proche de ce script (mais plus abouti) sous forme de package GitHub. Le concept est similaire : il faut ajouter ce package pour qu’il puisse résoudre les dépendances des autres packages, et il utilise les tags GitHub. Vous le trouverez sur sa page GitHub si vous voulez l’essayer.

Publication semi-automatique

Il me reste donc l’API de publication !

Attendez, j’ai bien dit qu’il n’y avait pas d’API, non ?

Quand vous êtes éditeur sur l’Unity Asset Store, vous avez accès à un portail qui permet de créer des packages, de définir leur description, leur titre, leurs captures d’écran, et de consulter les données de téléchargement et de ventes. Ils ont même ajouté une API pour cette partie (wow, les premiers packages que j’ai partagés datent de février 2011, quel âge ai-je déjà ?)

Vous avez évidemment un forum dédié aux éditeurs pour les questions spécifiques.

Le processus de création et le processus de mise à jour nécessitent de vous connecter au portail éditeur.

Depuis le portail, vous devez d’abord créer un nouveau package, ou un brouillon pour une nouvelle version de votre package, avant toute chose.

Après ces étapes, utilisez les Asset Store Tools, disponibles sur l’asset store, pour valider votre package et le soumettre.

Tout doit être fait manuellement, via le site web et les fenêtres de l’éditeur. Mais si vous regardez de près le site éditeur, vous remarquerez des appels JSON vers le site kharma.unity3d.com : ça ressemble à une API, non ?

D’autres développeurs s’y sont déjà intéressés ; l’un d’eux a d’ailleurs partagé un bout de code sur le forum. Et un autre l’a intégré, avec une petite évolution, dans son asset RockTomato, sous forme d’étape AssetStorePublish (bon, on dirait qu’ils se sont tous les deux penchés sur le même sujet en janvier).

Solution finale

Avant de soumettre le package Standard Assets à l’Unity Asset Store, j’avais déjà un projet de test servant à vérifier que tout était correct et à soumettre l’asset. Mais il n’est pas versionné, car il s’agit essentiellement d’un projet avec des submodules git et les Asset Store Tools importés, et presque rien de plus.

Voici le changement principal : au lieu d’utiliser ce projet uniquement pour soumettre le projet manuellement, je vais m’en servir pour soumettre chaque asset, avec un seul script, lancé quand je tague une version.

Comme je n’ai pas de planning annonçant un gros changement sur un asset, j’utilise toujours un seul dépôt, mais cela va aussi changer : un dépôt par asset, c’est le cas d’usage le plus simple, point final.

Alors creusons un peu ce processus. Encore une fois, si vous voulez juste la solution, passez cette partie.

Connexion et récupération des packages

La classe d’API créée par les développeurs mentionnés plus haut va un peu évoluer, mais l’essentiel est déjà là pour pouvoir se connecter et récupérer ses packages en tant qu’éditeur.

Mon objectif est de :

• pouvoir sélectionner tous les assets que je veux mettre à jour
• sauvegarder la configuration (comprendre : dossier de l’asset dans le projet, etc.)
• envoyer quand je le souhaite depuis un script externe (c’est-à-dire sans lancer Unity à chaque fois)

Commençons par créer une fenêtre d’éditeur qui permet de se connecter et d’afficher les packages récupérés.

Une fois connecté, Unity stocke une session dans ses prefs, ce qui permet de l’utiliser pour les appels d’API suivants sans se reconnecter : vous pouvez donc vous « auto-connecter ».

Et je ne veux pas devoir me connecter, ou m’auto-connecter, à chaque fois que je modifie la configuration d’un package : il faudrait un cache local ou quelque chose du genre, alors faisons-le ! Mais bien sûr, la mise à jour ou l’envoi ne peuvent pas se faire si vous n’êtes pas connecté.

Bien, une fois que c’est fait, testons l’envoi !

ÇA MARCHE !

Depuis ce même portail éditeur, vous pouvez définir des dépendances dans la section des packages.

À ce jour, il semble que les dépendances ne soient pas accessibles via les API, mais cela pourrait changer à l’avenir.

Le portail éditeur semble pour l’instant renvoyer directement vers l’ancien format de l’asset store, et non vers les URL V2 exigées pour les dépendances sur cette même page ; pensez donc à rechercher votre asset depuis l’asset store public lui-même.

Continuons le travail. Comme je le disais, je veux pouvoir sélectionner les packages qui seront envoyés depuis ce projet, et il se trouve que j’ai beaucoup de packages obsolètes dont je ne veux pas être distrait dans la liste ; je leur ajoute donc une propriété « visible ». J’ajoute aussi un indicateur de « statut » qui me dit si un package peut être envoyé (pour l’instant, il est vert quand le statut est « draft » sur le portail éditeur, et noir sinon).

Bien, mais pas top. Améliorons tout de suite cette fenêtre avec les icônes internes ! Pour les utiliser, il suffit d’utiliser la ligne de code suivante, et les noms peuvent être récupérés grâce à un petit outil que j’ai trouvé ici. C’est un excellent moyen d’améliorer le look and feel de vos fenêtres d’éditeur (si vous n’utilisez pas Odin, par exemple). Le second paramètre commence par une barre verticale « | » pour ne spécifier que le tooltip de l’icône.

EditorGUIUtility.IconContent(“console.warnicon”, “|Status: “);

Au passage, j’ai modifié la fenêtre pour qu’on ne puisse sélectionner un asset à envoyer que si son statut est correct.

Quand une API est appelée, il s’agit d’une requête web, donc ce n’est pas synchrone : vous pouvez modifier la configuration et la sauvegarder, mais il vaut mieux ne pas lancer d’autres appels si vous ne voulez pas d’ennuis. Pour l’éviter, et pour que l’utilisateur sache ce qui se passe, j’ai ajouté une help box qui indique quand une requête est en cours.

Dernière étape : pouvoir l’utiliser sans même lancer Unity. Heureusement, avec quelques arguments de plus qu’avant, on peut le lancer sans interface graphique et appeler une méthode directement via les arguments de ligne de commande.

Pour cette étape, j’ai un peu refactorisé mon code pour que tout ce qui concerne les packages se trouve dans la classe AssetStoreAPI. L’Editor Window utilise l’API et ne contient que la partie visuelle, et je crée une nouvelle classe, BatchSubmitterClient, qui sera celle utilisée en ligne de commande.

Pour que cela fonctionne, elle doit se trouver dans un dossier Editor, et la méthode doit être static. Comme nous appelons des API et que la réponse est asynchrone, on ne peut pas utiliser l’argument « -quit » au lancement de Unity en batch mode, sinon le processus se termine avant que le premier appel ne reçoive sa réponse. Mais n’oubliez pas de terminer le processus avec Application.Quit() si vous ne voulez pas que votre projet reste verrouillé et que Unity reste en mémoire. La ligne de commande ressemble à ceci, selon le chemin de votre projet :

Unity.exe -batchmode -projectPath “Drive:\Path\To\Project\Root” -executeMethod FredericRP.AssetStoreTools.BatchSubmitterClient.UploadPackages

Toutes les données en cache sont stockées dans les préférences de l’éditeur, elles sont donc partagées entre tous les projets. C’est pratique pour envoyer le même package avec plusieurs versions de Unity afin d’améliorer la vérification de compatibilité, et je ne vois pas de problème que cela pourrait poser pour l’instant, mais cela pourrait changer.

C’est tout pour le moment !

Bien sûr, l’outil est disponible gratuitement dans son propre dépôt BatchSubmitter ; utilisez l’URL suivante pour l’importer dans l’UPM !

git@github.com:FredericRP/BatchSubmitter.git

Les prochaines étapes consistent à pouvoir modifier la configuration via des arguments de ligne de commande ; mon temps est partagé entre mon travail, mes enfants et ce projet perso, donc je mettrai l’outil à jour dès que possible, mais je n’ai pas encore de date.

Autres problèmes

Pendant la mise à jour de mon dépôt GiT, je suis tombé sur quelques problèmes qui m’empêchaient d’importer les packages, sans aucune information sur la cause.

package non trouvé

Même s’il y a un fichier package.json dans le sous-dossier de l’asset, un fichier JSON invalide empêche Unity d’afficher le bon message dans la console. Cela fonctionne quand vous importez un package depuis le dossier racine d’un dépôt GiT, mais pas depuis un sous-dossier. Donc si une erreur « package not found » s’affiche dans la console, vérifiez que le fichier JSON de votre package est valide (pour cela, j’ai utilisé un dépôt de test avec l’asset placé dans le dossier racine).

Unity Hub toujours en mémoire

Quand vous modifiez des variables d’environnement, vous pouvez fermer Unity, le relancer et penser qu’il prend en compte la variable mise à jour. Erreur : comme il est lancé depuis le Unity Hub, qui reste en mémoire par défaut, il faut aussi fermer ce dernier depuis son icône dans la barre des tâches.

8 nouveaux packages

Ces huit nouveaux packages sont disponibles sur ma page GitHub comme avant, et seront bientôt publiés sur l’asset store en tant que packages indépendants : vous pouvez désormais choisir ce que vous voulez inclure dans votre projet. Je n’ai pas encore de roadmap pour les autres packages que je veux ajouter ici, alors pensez à suivre le dépôt ou ma page éditeur pour ne rien manquer.

Merci de m’avoir lu !

Page GitHub FredericRP Standard Assets