Nous avions déjà abordé les conventions de nommage propre au C#, qui sont aussi bien valables pour les scripts C# généraliste que dans le cadre propre à Unity.
Aujourd’hui, nous abordons les bonnes habitudes à prendre pour organiser un projet Unity 3D et nommer ses assets.
Ils sont basés sur ce que j’ai pu voir en terme de standard, ce que j’ai pu lire, et bien sûr une bonne dose de bon sens. Et encore une fois, l’idée n’est pas de se forcer à suivre des règles avec lesquelles on ne serait pas d’accord (parce qu’on a d’autres habitudes, qui peuvent être tout aussi bonnes).
L’idée, c’est de piocher là-dedans ce qui vous semble le mieux vous convenir, et surtout de vous harmoniser avec vos conventions de nommage au sein de votre équipe !
Dans cet article
Répertoire Assets : noms de répertoires et noms de fichiers particuliers
Dans votre projet Unity, le repertoire Assets/ présente une particularité : Unity tente d’importer ce qui se trouve dedans et met en cache l’importation de chacun de ces éléments (jusqu’à une éventuelle modification, ou en allant dans le menu Assets > Refresh).
Le dossier Assets/ peut être exploré par votre système d’exploitation, et vous pouvez tout à fait y ajouter des fichiers. Cependant, évitez de renommer ou supprimer des fichiers directement depuis votre OS, faites-le plutôt depuis un panneau « Project » d’Unity.
Certains noms de répertoires ont un comportement particulier et sont dédiées à certaines fonctions.
Répertoire multiples (plusieurs répertoires et sous-répertoires de ce type peuvent exister dans les dossiers et sous-dossiers de aassets)
- Editor/ contient les scripts de l’éditeur utilisés pendant le développement, qui ne sont pas compilés dans la build. Il aura toujours ce même comportement.
- Resources/ contient des Assets qui peuvent être appelées par les scripts directement, via la méthode Resources.Load(). Attention, pour ne pas avoir d’erreur avec cette méthode, les asets situés dans les différents répertoires Resources/ du projet doivent avoir des noms uniques.
Répertoires uniques (un seul de chaque, et situé directement dans le répertoire Assets/) :
- Editor Default Resources/ contient des ressources (fonctionnement similaire aux Resources ci-dessus), mais pour l’éditeur uniquement (via la méthode EditorGUIUtility.Load()).
- Gizmos/ contient les éléments placés dans les différentes vues de l’éditeur, par exemple ajouter des icônes dans la vue de la scène.
- Plugins/ est un répertoire dédié pour l’import de certaines librairies et plugin. Généralement, ce répertoire sera créé automatiquement par un package que vous importerez dans votre porjet.
- Standard Assets/ est dédié à certain packages particuliers disponibles dans Unity (utilisés généralement pour du prototypage rapide).
- StreamingAssets/ dédié aux fichiers qui doivent être placés dans certains répertoires selon les systèmes d’exploitation, par exemple des vidéos qui doivent être lues par une fonction dédiée de l’appareil (notamment pour le développement mobile).
En outre, il est possible de cacher des fichiers et répertoires du répertoire Assets/ pour qu’Unity ne les importe pas (et ils sont invisibles dans la fenêtre « Projet »). Ça peut être utile par exemple pour ranger certains fichiers sources dans le répertoire de votre projet, et par exemple ça permet aux fichiers de configuration de votre système de contrôle de code (type .git) d’être ignorés par Unity.
- Les répertoires cachés dans l’OS
- Les fichiers et répertoires commençant par « . » ou terminant par « ~«
- Les fichiers et répertoires appelés cvs
- Les fichiers avec l’extension .tmp
Organisation des assets en dossiers et sous-dossiers
Voici une proposition d’arborescence pour Unity. Les noms de répertoire sont en anglais, en CamelCase, et descriptifs.
Assets +---_Scenes # Les scènes de base d'Unity* +---Art | +---Materials # | +---Models # Modèles au format FBX (+ sources BLEND) | +---Prefabs # Fichiers prefabs | +---Textures # Textures communes, hors modèles | \---UI # Les éléments de l'UI (sprites, etc.) +---Audio | +---Music | \---Sound # Bruitages, voix, etc. +---Docs~ # Wiki, concept art, marketing (avec ~ pour bloquer l'importation par Unity) +---Resources # Fichiers de configuration, localisation, etc. +---Source | +---Input # Fichiers de configuration des Input | +---Scripts # Scripts au format C# | \---Shaders # Fichiers de shaders et shader graphs
*Ce répertoire _Scenes est précédé par un _ pour être tout le temps en haut de la liste des assets, puisque c’est la brique de construction de base d’Unity. Alternativement, il peut être appelé _Levels ou _Maps selon votre goût.
Dans les répertoire concernés (Models, Prefabs, Animation, Textures), utilisez des sous-répertoires descriptifs pour classer vos fichiers :
Assets +---Art | +---Materials | +---Models | | +---Characters | | +---Effects | | +---Environments | | | +---Background | | | +---Props | | | \---Terrain | | +---Vehicles | | \---Weapons | +---Prefabs | +---Textures | \---UI
Vous pouvez placer dans ce dossier Assets le fichier ainsi que ses dépendances, voire ses sources.
Ainsi, dans « Props », nous aurons un fichier Bookcase_01, et un répertoire au nom de l’objet contenant ses textures, son modèle, ses animations…
Vous pouvez placer un répertoire .Source/ ou Source~/ contenant les fichiers de base (le fichier .blend, le fichier .psd des textures…)
Convention de nommage des assets dans Unity
Pour les scripts, la convention de nommage des fichiers est celles des classes qu’ils contiennent. L’article sur les conventions de nommage C# vous propose une convention sur les noms des classes dans Unity. CameraManager, PlayerController, etc.
Pour les noms autres assets, utilisez le PascalCase pour les différents éléments d’un nom, et des underscore pour ajouter des préfixes et des suffixes. Privilégiez des noms courts, mais descriptifs pour chaque élément. Par ex on préfère avoir un modèle de vélo sportif nommé BikeSports dans Models/Vehicles/Bikes qu’un fichier nommé ModelVehicleBikeSports.
Ne reprenez pas systématiquement le type d’objet dans le nom de votre asset. Les répertoires de votre projet et la recherche de la fenêtre projet sont là pour vous éviter d’avoir à le faire.
Ainsi on aura Walk mais pas WalkAnim, ou World01Level08 et non pas SceneW01L08, ou encore Bear au lieu de BearModel.
Utilisation de préfixes
Plusieurs convention de nommage proposent d’utiliser des préfixes pour les noms de fichier. Ça ne fait pas l’unanimité et ce n’est pas nécessairement utile dans Unity puisqu’on peut directement filtrer certains types dans la fenêtre projet :
En plus, le préfixe a un inconvénient : il « recouvre » l’ordre alphabétique. Ça n’est pas un problème si les fichiers sont bien rangés dans des répertoires, mais ça peut être gênant dans certains cas (si on perd l’arborescence, quand on est face à un résultat de recherche, etc.)
Des exemples où un préfixe peut être utile, c’est pour faire facilement la distinction entre les préfabs des modèles importés (puisqu’ils ont une icône très similaire), ou les animations et leurs contrôleurs.
Une autre convention de nommage des préfabs est juste de le nommer selon l’asset qu’il contient, et le placer dans le répertoire Préfabs. Définissez dès le début votre règle pour les préfabs et respectez-le.
Exemples de préfixes :
| Préfixe | Utilisation |
|---|---|
| A_ | Animation |
| AC_ | Contrôleur d’animation (Animator) |
| PFB_ | Prefab |
Utilisation des suffixes (pour les textures)
Pour les textures en revanche, les suffixes se montrent très utiles, car on a souvent plein de composants pour une même textures. Ils permettent de distinguer l’usage de chacune d’entre elles, notamment quand elles sont importées sur des shaders.
Cette liste est directement reprise de l’article de High Priority (voir sources de cet article). Chaque map utilise un suffixe d’une seule lettre, hormis pour les maps composées de plusieurs autres map, dont le suffixe combine les lettres des suffixes des types de map qui les composent.
| Suffixe | Description |
|---|---|
| _C | Color map (diffuse ou albedo) |
| _T | Transparency : masque de transparence |
| _M | Masque pour la composante Metallic |
| _R | Masque pour la composante Roughness |
| _S | Masque pour la composante Smoothness (Rougness) |
| _N | Normal map (relief d’une texture) |
| _A | Masque d’Ambient Occlusion |
| _E | Masque d’Emissive |
| _H | Masque Height map |
| _D | Displacement map (généralement un Height Map en version floue pour éviter les artefacts) |
| _MRA (Masque combiné) | Masque qui contient les masques combinés [R=Metallic, G=Roughness, B=AO, 4e canal = Emissive, Height ou autre] |
| _MADS (Masque HDRP de Unity HDRP) | Combinaison de masques pour le système HDPR d’Unity : [R=Metallic, G=AO, B=Detail Map, 4e canal = Smoothness] |
| _I | Texture de type « masque Color ID » |
| _U | Masque de Subsurface (_U comme Under) |
Sources
Pour cet article, je me suis basé sur la lecture des articles suivants, dont je vous conseille également la consultation :
- 5 essentials to Naming Convention (High Priority)
- The Ramen Unity Style Guide (GitHub – stillwater)
- Top 10 Unity naming conventions (sur Reddit)