huayuehua15-netizen/unity-blender-mcp

Pipeline autonome Unity + Blender via MCP

Convention de chemins : Tous les scripts/, references/, assets/ sont relatifs au répertoire contenant ce SKILL.md. Lors du passage à un autre hôte ou répertoire de travail, résoudre d'abord le répertoire du SKILL.md en chemin absolu avant d'appeler. Exécutez toujours les scripts en ligne de commande avec --python-exit-code 1 : par défaut, Blender renvoie un code de sortie 0 même en cas d'erreur ; sans ce paramètre, un échec d'audit peut être considéré comme réussi.

Aperçu

Ce skill permet à l'IA de piloter de manière autonome Blender et Unity via MCP (Model Context Protocol) pour produire des actifs 3D prêts à l'emploi dans le moteur de jeu, avec une approche Asset-First : d'abord chercher et réutiliser, puis générer par IA, et enfin modéliser de zéro. Chaque actif est livré "prêt à l'import" dans le moteur.

Principe fondamental : Arbre de décision Asset-First

Face à toute demande de "modèle/actif X", suivre strictement cet ordre, interdiction de partir directement de zéro :

1. Sources intégrées MCP (les plus rapides, zéro téléchargement) : search_sketchfab_models / search_polyhaven_assets de Blender MCP (HDRI, textures PBR, modèles réalistes) ; import_model de Unity MCP (Sketchfab).
2. Bibliothèques CC0 de jeux : Kenney, Quaternius, KayKit, Poly Haven, Poly Pizza — styles cohérents, directement exploitables, zéro risque commercial.
3. Zones gratuites des grandes places de marché : Sketchfab (filtrer CC0/CC-BY et Downloadable), TurboSquid, CGTrader, Fab (Megascans), BlenderKit.
4. Sites chinois : 3d66, Mofu House, Aigui — vérifier licence et format un par un (beaucoup de fichiers .max que Blender n'ouvre pas, voir 03).
5. Personnages/animations : priorité à Mixamo (skinning auto gratuit + milliers d'animations), packs de personnages animés Quaternius.
6. Génération IA : Hyper3D Rodin / Hunyuan3D de Blender MCP, Tripo/Meshy de Unity MCP — un seul objet précis, pas de scène entière/terrain.
7. Modélisation Blender (dernier recours) : si rien trouvé, ou si besoin d'une structure fonctionnelle précise/d'actifs de marque personnalisés, utiliser bpy/workflow de modélisation.

Tout actif, quelle que soit sa source, doit passer par l'audit et le nettoyage Blender (étape 5) avant d'entrer dans Unity. Interdiction de glisser-déposer un FBX brut directement dans Unity.

Avant de commencer : Connexion MCP et découverte des outils (à faire à chaque session)

Les noms des outils MCP varient selon l'implémentation (côté Blender : souvent ahujasid/blender-mcp ; côté Unity : souvent CoplayDev/unity-mcp ou le package officiel Unity com.unity.ai.assistant). Ne pas supposer de nom fixe.

1. Lister d'abord les outils MCP réellement exposés par la session courante, les mapper avec le "tableau de correspondance des capacités standards" dans references/00-mcp-connection.md.
2. Vérifier l'état de connexion :
   • Blender : appeler un outil de type inspection de scène (ex. get_scene_info) pour confirmer que Blender est ouvert et le plugin connecté ;
   • Unity : appeler un outil d'état éditeur/console (ex. manage_editor / read_console) pour confirmer que le pont est opérationnel.
3. Outil manquant ou non connecté : suivre le tableau de dépannage du 00, ou dégrader en traitement par ligne de commande (blender --background --python, batchmode Unity) ; ne pas simuler un appel réussi.
4. À la première connexion, identifier le pipeline de rendu du projet (Built-in / URP / HDRP) et la version Unity — les shaders de matériaux et le packing des masques diffèrent.

Cycle de travail standard (à respecter pour chaque opération)

Inspecter l'état actuel (scene_info / console) → capture d'écran/relevé → petite exécution d'un changement unique
→ capture d'écran ou relevé de vérification → sauvegarde/note → passer à l'étape suivante

• Lire avant d'écrire : avant toute modification, obtenir les informations de la scène/objet ; dans Blender, sauvegarder avec bpy.ops.wm.save_as_mainfile avant de modifier.
• Petits blocs : execute_blender_code a un timeout (environ 180s), découper les tâches complexes en plusieurs blocs ; chaque bloc est autonome (il importe lui-même bpy, reselectionne les objets par nom, ne dépend pas des variables mémoire du bloc précédent).
• Résultat visible : après chaque import/positionnement/export dans Blender, vérifier avec get_viewport_screenshot ; dans Unity, vérifier avec read_console pour les erreurs, et confirmer le résultat via la hiérarchie/inspection de scène.
• En cas d'échec, ne pas forcer : après deux échecs d'une même opération, changer de méthode ou de canal, noter le phénomène, ne pas répéter le même appel.

Trois workflows

Workflow A : Récupérer un actif existant (le plus courant)

Lire references/04-asset-reuse-workflow.md, suivre les 9 étapes : Fiche de besoin → Recherche d'actif → Évaluation des candidats (incluant licence) → Téléchargement temporaire → Audit Blender → Nettoyage standardisation → Export FBX → Rendu QA visuel → Validation import Unity.

• Audit : scripts/blender_asset_audit.py (génère un rapport JSON : nombre de faces, matériaux, UV, transformations, os, animations ; décider de garder ou non selon le budget).
• Nettoyage + export : scripts/blender_prep_unity.py (applique les transformations, remet l'origine à zéro, recalcule les normales, unifie les noms, exporte FBX avec les bons paramètres Unity).
• Rendu QA : scripts/blender_asset_qa_render.py (après export, génère automatiquement une image de qualité avec éclairage standard et composition, pour vérifier visuellement les textures, la rugosité métallique, les normales, la forme ; --turntable N pour vues multiples ; les données auditées + validation visuelle sont toutes deux nécessaires pour qualifier).
• Licence : pour tout actif non CC0, enregistrer une ligne dans assets/asset-ledger.csv (type de licence, URL source, attribution requise).

Workflow B : Créer un actif de zéro

Lire references/05-model-from-scratch.md : image(s) de référence/dimensions → low-poly blocage → high-poly détails → UV → baking normales/PBR → auto-vérification du budget de faces et texel → suivre les étapes d'export/import du workflow A. D'abord déterminer si la génération IA peut remplacer ; les actifs générés par IA doivent également passer par l'audit et la retopologie.

Workflow C : Configuration Unity après import Blender

Lire references/06-blender-to-unity.md : paramètres d'import modèle/matériau/animation → LOD → collisions → mapping des canaux de textures matériaux (différent selon URP/HDRP) → création de Prefab → placement en scène/baking light → build.

• Pour l'import batch, copier assets/unity/Editor/AssetPostprocessor.cs dans Assets/Editor/ du projet Unity (avec porte de répertoire pour ne traiter que les dossiers d'import spécifiés, sans polluer tout le projet).

Scripts et actifs

Fichier	Utilité	Mode d'exécution
scripts/blender_asset_audit.py	Auditer la scène courante ou un fichier modèle donné, sortir un rapport JSON de santé	MCP : coller et exécuter le code ; ou blender --background --python scripts/blender_asset_audit.py -- chemin_modèle
scripts/blender_prep_unity.py	Nettoyer l'actif sélectionné et exporter un FBX standard Unity (avec baking d'animation optionnel)	MCP : coller le code puis appeler prep_and_export() ; ou ligne de commande -- chemin_sortie
scripts/blender_asset_qa_render.py	Rendu QA d'actif : cadrage auto, éclairage HDRI/trois points, AgX, fond neutre, image de qualité ; supporte --turntable N pour vues multiples	blender --background --python ... -- chemin_modèle sortie.png [--hdri chemin] [--tourne-disque 3] ; MCP : coller et rendre la scène courante
assets/unity/Editor/AssetPostprocessor.cs	Post-processing Unity à l'import : textures configurées sRGB/normal/mask selon suffixe, modèle mis à l'échelle/normales/mesh settings	Copier dans Assets/Editor/ du projet Unity
assets/asset-ledger.csv	Modèle de registre des licences d'actifs	Ajouter une ligne par actif non CC0

Index des documents de référence (charger à la demande)

• references/00-mcp-connection.md : Connexion MCP / découverte d'outils / règles de sécurité / dégradation en ligne de commande sans MCP
• references/01-blender-mcp-playbook.md : Table des outils Blender MCP + bibliothèque de snippets bpy courants (import/nettoyage/matériaux/LOD/export/capture d'écran)
• references/02-unity-mcp-playbook.md : Table des outils Unity MCP + opérations scène/objet/actif/matériau/script/build
• references/03-asset-libraries.md : Encyclopédie des bibliothèques d'actifs (licences/format/sélection/mots-clés de recherche/pièges des sites chinois comme 3d66)
• references/04-asset-reuse-workflow.md : Processus de réutilisation en 9 étapes et liste de vérification de validation
• references/05-model-from-scratch.md : Quand modéliser soi-même, pipeline de production d'actifs de jeu dans Blender, traitement des actifs générés par IA
• references/06-blender-to-unity.md : Pipeline standard Blender→Unity (axe/échelle/paramètres FBX/canaux de matériaux/LOD/collision/Humanoid)
• references/07-troubleshooting.md : Tableau symptôme→cause→correction (matériaux roses/échelle/normales/affaissement/absence de collision/T-pose/glissement de pied, etc.)

Règles de sécurité strictes

• Avant de modifier une scène Blender/Unity existante, faire une sauvegarde séparée ; l'import et le nettoyage se font toujours dans une scène Blender indépendante et un répertoire temporaire Assets/Imports/ dans Unity ; ce n'est qu'après validation qu'on déplace dans le répertoire final.
• Ne pas supprimer, ne pas écraser les fichiers sources de l'utilisateur ; conserver l'original téléchargé dans la zone temporaire, enregistrer les produits nettoyés à part.
• execute_blender_code et execute_code d'Unity peuvent exécuter du code arbitraire ; interdiction de faire des opérations non liées à la tâche courante ; pour les opérations dangereuses (suppression, renommage batch, écrasement d'export), lister d'abord les objets affectés avant d'exécuter.
• Tout actif à la licence incertaine (notamment NC, réservé à l'apprentissage, éléments gratuits de 3d66, éléments payants sur abonnement) ne doit jamais entrer dans un projet commercial ; préférer une source CC0 ou la modélisation.
• Nommer tous les matériaux/textures/modèles selon la convention (SM_/SK_/T_BC/N/RMA/M/M_/MI_), convertir les noms de fichiers et chemins de textures chinois en anglais avant l'export.

Définition de fini (DoD au niveau actif)

Chaque actif livré dans Unity doit satisfaire :

• Licence enregistrée (même CC0 : noter la source), utilisable en commercial sans blocage
• Rapport d'audit : nombre de faces conforme au budget, UV présentes, pas de problème de N-gon, transformations appliquées
• Échelle correcte dans la scène (personnage ~1,7m, proportions réalistes avec les objets environnants), orientation correcte
• Matériaux non roses, textures non perdues (textures incluses dans le package / dans le projet), canaux URP/HDRP corrects
• Collider approprié, personnage / pièce animée dotée d'un Avatar et animation fonctionnelle
• Prefab généré, LOD configuré selon les besoins, console sans erreur
• Image de qualité de vue clé générée par blender_asset_qa_render.py et validée visuellement (textures/normales/métal-rugosité/forme), avant remise à l'utilisateur pour confirmation