unity-technologies/gérer-atlas-de-sprites

Unity SpriteAtlas V2

Fournit des connaissances procédurales sûres pour l'éditeur pour scripter des atlas dans les projets Unity. V2 applique une séparation stricte entre la création dans l'éditeur et l'accès à l'exécution.

⚠️ Principe critique de V2 : SpriteAtlas est uniquement pour l'exécution. SpriteAtlasAsset est uniquement pour l'éditeur. Ne mélangez jamais les contextes. Utilisez toujours V2.

🚨 CRITIQUE : Vérifications requises et entrées utilisateur avant l'implémentation

EFFECTUEZ TOUJOURS ces vérifications et posez ces questions AVANT de générer du code :

Lisez les ressources fournies avant d'écrire du code (OBLIGATOIRE)

Ce skill fournit du code C# fonctionnel sous resources/, et le code d'atlas qui pose problème est presque toujours écrit sans l'avoir lu en premier. Ouvrez les fichiers pour le chemin que vous empruntez, puis écrivez.

Chemin emprunté	Lisez d'abord
Tout travail sur les atlas	resources/authoringvsruntime.cs, references/common-errors.md
Génération prebuild (par défaut)	resources/spriteatlasprebuildgenerator.cs, resources/enablespritepacking.cs, resources/savespriteatlasasset.cs
Option B, liaison tardive Addressables	resources/buildaddressablespostprocess.cs, resources/spriteatlaslatebinding.cs, resources/handlelatebinding.cs
Tout ce qui pourrait utiliser une API plus ancienne	resources/deprecatedmethods.cs, resources/dontscriptspriteatlasineditor.cs, resources/dontpackinruntimebuilds.cs

resources/ contient 38 fichiers au total, couvrant les conditionneurs personnalisés, les variantes, les paramètres de plateforme et l'accès à l'exécution. Parcourez le répertoire lorsque votre tâche n'est pas dans le tableau ci-dessus plutôt que d'inventer une approche. Utiliser l'API de mémoire au lieu de lire ces fichiers est la cause la plus fréquente d'un atlas qui s'importe proprement mais ne fait rien à l'exécution.

0. Vérifiez les scripts existants (PREMIÈRE ÉTAPE OBLIGATOIRE)

AVANT de générer du code, parcourez le projet pour trouver des scripts SpriteAtlas existants générés par ce skill.

Recherchez les fichiers contenant l'identifiant : // [UNITY-SKILL:SPRITEATLAS]

Si des scripts existants sont trouvés, demandez TOUJOURS à l'utilisateur avec ce format :

"J'ai trouvé des scripts SpriteAtlas existants dans votre projet :

Générateur Prebuild :

• Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs

Constructeur Addressables :

• Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs

Chargeur d'exécution :

• Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs

Que souhaitez-vous faire ?"

Présentez ensuite les options :

• Option A : Mettre à jour les scripts existants (Recommandé si les exigences ont changé)

  • Régénère les scripts aux chemins existants
  • Préserve les emplacements des fichiers
  • Met à jour vers la dernière version
  • ⚠️ Peut écraser les modifications personnalisées

• Option B : Créer de nouveaux scripts avec des noms différents

  • Génère à côté des scripts existants
  • Permet plusieurs configurations d'atlas
  • Les scripts originaux restent inchangés
  • Vous devrez spécifier de nouveaux noms/chemins

• Option C : Abandonner (conserver l'existant inchangé)

  • Aucune génération de code
  • Aucune modification du projet
  • Utilisez cette option si vous souhaitez conserver la configuration actuelle

Gestion du choix de l'utilisateur :

• Si A est choisi : Régénère aux chemins existants, incrémente la version à 2.0.1+
• Si B est choisi : Demandez de nouveaux noms de scripts (par exemple, "SpriteAtlasPrebuild_Custom.cs"), puis générez
• Si C est choisi : Arrêtez immédiatement, informez l'utilisateur qu'aucune modification n'a été effectuée

1. Mécanisme de livraison (OBLIGATOIRE)

Demandez : "Comment souhaitez-vous livrer les atlas de sprites ?"

Option A : Données intégrées (Chargement immédiat)

• Les atlas sont inclus dans le build et chargés immédiatement
• Définissez includeInBuild = true
• Adapté pour : Interface utilisateur principale, sprites de gameplay principaux, assets toujours nécessaires
• Avantages : Simple, aucun package supplémentaire, accès instantané
• Inconvénients : Augmente la taille initiale du build, ne peut pas être mis à jour sans nouveau build

Option B : Liaison tardive via Addressables (Chargement à la demande)

• Les atlas NE sont PAS inclus dans le build, chargés à la demande via Addressables
• Définissez includeInBuild = false
• Créez des entrées Addressables pour chaque atlas
• Ajoutez la configuration Addressables comme étape de préconstruction
• 🚨 OBLIGATOIRE : Construisez le contenu Addressables comme étape de build
• 🚨 OBLIGATOIRE : Créez un script de chargeur d'exécution à liaison tardive
• Adapté pour : Contenu DLC, fonctionnalités optionnelles, gros assets, contenu téléchargeable
• Avantages : Build initial plus petit, peut être mis à jour indépendamment, chargement à la demande
• Inconvénients : Nécessite le package Addressables, chargement asynchrone, dépendance réseau

Cas d'utilisation	Recommandé
Sprites d'interface utilisateur principaux toujours visibles	Option A : Intégré
Sprites de tutoriel ou d'intégration	Option A : Intégré
Sprites spécifiques à un niveau (100+ niveaux)	Option B : Addressables
Contenu DLC ou saisonnier	Option B : Addressables
Sprites d'interface utilisateur localisés (plusieurs langues)	Option B : Addressables
Skins de personnages ou cosmétiques	Option B : Addressables

2. Mode SpritePacker (OBLIGATOIRE)

Activez le mode Sprite Packer avant de créer des atlas, puis lisez le paramètre en retour et confirmez qu'il a pris effet. Utilisez le code dans resources/enablespritepacking.cs ; il définit EditorSettings.spritePackerMode et configure les paramètres de conditionnement de l'importateur.

C'est l'étape qui décide si l'atlas que vous produisez est réel. Disabled est la valeur zéro de SpritePackerMode, donc tout projet où personne ne l'a défini porte le conditionnement Disabled, et un atlas créé alors qu'il est Disabled s'importe toujours, apparaît toujours comme un asset, et semble toujours terminé, mais ne peut jamais être conditionné. Unity le dit dans l'Inspector : "Sprite Atlas packing is disabled". Rien d'autre dans le flux de travail n'échoue, donc un atlas livré de cette manière se lit comme un succès. Ne supposez pas qu'un projet est déjà configuré : lisez la valeur.

Ne traitez donc pas "Je l'ai défini" comme terminé. Après l'avoir défini, lisez EditorSettings.spritePackerMode en retour, confirmez qu'il n'est pas Disabled, et signalez la valeur que vous avez réellement lue. Si vous ne pouvez pas le lire, dites-le plutôt que de supposer que l'écriture a fonctionné.

NE modifiez PAS les fichiers meta DIRECTEMENT.

🚨 CRITIQUE : L'approche par défaut est la génération Prebuild

Utilisez TOUJOURS IPreprocessBuildWithReport pour générer ou mettre à jour automatiquement les SpriteAtlas pendant le pipeline de build. C'est l'approche PAR DÉFAUT et OBLIGATOIRE sauf si l'utilisateur demande EXPLICITEMENT une création manuelle.

❌ NE créez PAS de scripts d'élément de menu manuels

NE créez JAMAIS de scripts avec des attributs [MenuItem] pour la génération d'atlas, sauf demande explicite. L'approche prebuild élimine le besoin de clics manuels. Utilisez la création manuelle uniquement pour : les mises en page optimisées à la main, les arrangements de sprites spécifiques, ou les exigences de prévisualisation dans l'éditeur. Voir Avancé : Création manuelle.

🚨 CRITIQUE : Restriction de l'emplacement source des sprites

Ajoutez UNIQUEMENT des sprites du dossier Assets du projet. N'ajoutez JAMAIS de sprites provenant des assets intégrés d'Unity, des packages ou d'emplacements externes. Les assets intégrés d'Unity ne peuvent pas être conditionnés dans SpriteAtlas, et les assets de packages peuvent causer des problèmes d'import/dépendance.

Architecture critique de V2

Contexte	Composant	Objectif	Utilisation autorisée