huayuehua15-netizen/unity-blender-mcp

Unity + Blender MCP Autonome Pipeline

Pfadvereinbarung: Alle scripts/, references/, assets/ in dieser Datei sind relativ zum Verzeichnis, in dem diese SKILL.md liegt. Beim Wechsel auf einen anderen Host oder ein anderes Arbeitsverzeichnis muss das SKILL.md-Verzeichnis zuerst in einen absoluten Pfad aufgelöst werden. Bei Skriptaufrufen über die Kommandozeile immer --python-exit-code 1 angeben: Blender gibt standardmäßig auch bei Fehlern Exit-Code 0 zurück; ohne diesen Parameter wird selbst ein fehlgeschlagener Audit als Erfolg gemeldet.

Überblick

Dieses Skill befähigt eine KI, über MCP (Model Context Protocol) eigenständig Blender und Unity zu bedienen und 3D-Game-Assets nach dem Asset-First-Prinzip zu produzieren: Suche zuerst nach vorhandenen Assets, dann KI-generierte, und erst als letztes eigenständiges Modellieren. Jedes Asset wird als „Engine-ready“-Endprodukt ausgeliefert.

Kernprinzip: Asset-First-Entscheidungsbaum

Bei jeder Anfrage nach einem „XX-Modell/-Asset“ muss strikt die folgende Reihenfolge eingehalten werden – niemals sofort von Grund auf modellieren:

1. MCP-interne Quellen (schnellster Weg, kein Download/Transport): Blender-MCP search_sketchfab_models / search_polyhaven_assets (HDRI, PBR-Texturen, realistische Modelle); Unity-MCP import_model (Sketchfab).
2. CC0-Game-Asset-Seiten: Kenney, Quaternius, KayKit, Poly Haven, Poly Pizza – einheitlicher Stil, direkt für die Engine, kommerziell ohne Risiko.
3. Kostenlose Bereiche großer Marktplätze: Sketchfab (auf CC0/CC-BY mit Download-Möglichkeit einschränken), TurboSquid, CGTrader, Fab (Megascans), BlenderKit.
4. Chinesische Seiten: 3d66, Modellhaus, Aigei etc. – jedes Asset einzeln auf Lizenz und Format prüfen (viele .max-Dateien lassen sich nicht in Blender öffnen, siehe 03).
5. Charaktere/Animationen: Skelett und Animationen zuerst bei Mixamo (kostenloses Auto-Rigging + tausende Aktionen), Quaternius (Charakter-Pakete mit Animationen).
6. KI-Generierung: Hyper3D Rodin / Hunyuan3D über Blender-MCP, Tripo/Meshy über Unity-MCP – nur für eindeutig einzelne Objekte, nicht für ganze Szenen/Gelände.
7. Selbst modellieren in Blender (letztes Mittel): Wenn nichts gefunden wird oder präzise funktionale Strukturen/kundenspezifische Assets erforderlich sind.

Assets aus jeder Quelle müssen vor dem Import in Unity einmalig in Blender auditiert und gesäubert werden (Schritt 5). Es ist verboten, rohe FBX-Downloads direkt in Unity zu ziehen.

Vor Arbeitsbeginn: MCP-Verbindung und Werkzeugentdeckung (bei jeder Sitzung Pflicht)

Die MCP-Werkzeugnamen variieren je nach Implementierung (auf Blender-Seite z.B. ahujasid/blender-mcp; auf Unity-Seite z.B. CoplayDev/unity-mcp oder das offizielle com.unity.ai.assistant von Unity). Gehen Sie nie von einem festen Werkzeugnamen aus.

1. Prüfen Sie, welche MCP-Werkzeuge in der aktuellen Sitzung tatsächlich verfügbar sind, und bilden Sie diese auf die „Standard-Fähigkeiten-Tabelle“ in references/00-mcp-connection.md ab.
2. Verbindungsstatus prüfen:
   • Blender: Ein Szenenprüfwerkzeug (z.B. get_scene_info) aufrufen, um zu bestätigen, dass Blender geöffnet und das Plugin verbunden ist.
   • Unity: Editor-Status/Konsolenwerkzeuge (z.B. manage_editor / read_console) aufrufen, um zu bestätigen, dass die Brücke läuft.
3. Fehlende oder nicht verbundene Werkzeuge: Gemäß der Fehlersuche in 00 vorgehen oder auf Kommandozeilen-Batch-Verarbeitung ausweichen (blender --background --python, Unity Batchmode). Nicht so tun, als ob der Aufruf erfolgreich war.
4. Beim ersten Anschluß die Render-Pipeline des Projekts (Built-in / URP / HDRP) und die Unity-Version ermitteln – Material-Shader und Maskenpakete unterscheiden sich.

Standard-Arbeitszyklus (für jede Operation)

Ist-Zustand prüfen (scene_info / Konsole) → Screenshot/Werte als Beleg → kleine einzelne Änderung durchführen
→ Screenshot oder Werte zur Verifikation → Speichern/Protokollieren → Nächsten Schritt.

• Erst lesen, dann schreiben: Vor jeder Änderung Szenen-/Objektinformationen abrufen; in Blender vor Änderungen mit bpy.ops.wm.save_as_mainfile ein Backup erstellen.
• Kleine Blöcke ausführen: execute_blender_code in Blender-MCP hat ein Timeout (ca. 180s); komplexe Aufgaben in mehrere Codeblöcke aufteilen. Jeder Block muss in sich abgeschlossen sein (eigenständig import bpy, Objekte erneut per Namen auswählen, nicht von Variablen des vorherigen Blocks abhängig).
• Ergebnisse müssen sichtbar sein: Nach jedem Import/Platzieren/Export in Blender mit get_viewport_screenshot prüfen; in Unity nach jedem Schritt die Konsole mit read_console auf Fehler prüfen und das Ergebnis mit Hierarchie-/Szenenabfragen bestätigen.
• Bei Fehlern nicht durchprügeln: Wenn zwei aufeinanderfolgende Operationen des gleichen Typs fehlschlagen, Methode oder Kanal wechseln, das Phänomen protokollieren, nicht denselben Aufruf wiederholt versuchen.

Drei Workflows

Workflow A: Ein vorhandenes Asset beschaffen (am häufigsten)

references/04-asset-reuse-workflow.md lesen, die 9 Schritte befolgen: Anforderungsliste → Asset-Suche → Kandidatenbewertung (inkl. Lizenz) → Herunterladen/Zwischenspeichern → Blender-Audit → Säubern/Standardisieren → FBX-Export → Qualitätskontrolle (Render/Sichtprüfung) → Unity-Import und Abnahme.

• Audit: scripts/blender_asset_audit.py (erzeugt JSON-Bericht zu Polygonanzahl/Materialien/UVs/Transformationen/Skelett/Animationen; Entscheidung anhand Budget.)
• Säubern + Export: scripts/blender_prep_unity.py (Transformationen anwenden, Ursprung zurücksetzen, Normalen neu berechnen, einheitliche Benennung, FBX-Export mit korrekten Unity-Parametern).
• Qualitätskontrolle (Render): scripts/blender_asset_qa_render.py (erzeugt nach dem Export automatisch ein Qualitätsbild mit Standardbeleuchtung/Kameraeinstellungen zur Sichtprüfung von Texturen, Metallizität/Rauheit, Normalen und Form; --turntable N für mehrere Perspektiven. Erst nach bestandener Datenprüfung und Augenschein gilt das Asset als bestanden.)
• Lizenz: Für jedes nicht-CC0-Asset ein Eintrag in assets/asset-ledger.csv (Lizenztyp, Quell-URL, eventuelle Namensnennung).

Workflow B: Ein Asset von Grund auf erstellen

references/05-model-from-scratch.md lesen: Referenzbilder/Maße → Low-Poly-Grundform → High-Poly-Details → UVs → Normal-/PBR-Baking → Selbstkontrolle (Polygonanzahl/Texel-Dichte) → Export/Import-Schritte aus Workflow A. Zuerst prüfen, ob KI-Generierung ausreicht; auch KI-generierte Assets müssen auditiert und ggf. neu-topologisiert werden.

Workflow C: Blender → Unity-Engine-Einstellungen

references/06-blender-to-unity.md lesen: Model-/Material-/Animation-Importeinstellungen → LOD → Kollider → Material-/Textur-Kanal-Mapping (URP/HDRP unterschiedlich) → Prefab-Erstellung → Szene platzieren/Licht-Baking → Build.

• Beim Massenimport die Datei assets/unity/Editor/AssetPostprocessor.cs in das Assets/Editor/-Verzeichnis des Unity-Projekts kopieren (mit Verzeichnis-Gate, das nur das angegebene Importverzeichnis bearbeitet – keine Verschmutzung des gesamten Projekts).

Skripte und Assets

Datei	Zweck	Aufrufart
scripts/blender_asset_audit.py	Auditiert die aktuelle Szene oder eine bestimmte Modelldatei, gibt JSON-Bericht aus	MCP: Code einfügen und ausführen; oder blender --background --python scripts/blender_asset_audit.py -- Modellpfad
scripts/blender_prep_unity.py	Säubert das ausgewählte Asset und exportiert Unity-konformes FBX (optional mit Animations-Baking)	MCP: Code einfügen und prep_and_export() aufrufen; oder Kommandozeile -- Ausgabepfad
scripts/blender_asset_qa_render.py	Qualitätskontrolle: automatisch Bild mit passendem Bildausschnitt, HDRI/Dreipunkt-Beleuchtung, AgX, neutralem Hintergrund; --turntable N für mehrere Perspektiven	blender --background --python ... -- Modellpfad Ausgabe.png [--hdri Pfad] [--turntable 3]; MCP: aktuelle Szene rendern
assets/unity/Editor/AssetPostprocessor.cs	Unity-seitiger Import-Postprozessor: Texturen per Suffix auf sRGB/Normal/Mask setzen, Modelle einheitlich skalieren/Normalen/Gitter konfigurieren	In Assets/Editor/ des Unity-Projekts kopieren
assets/asset-ledger.csv	Vorlage für Asset-Lizenz-Tabelle	Pro nicht-CC0-Asset eine Zeile eintragen

Referenzdokumente (bei Bedarf laden)

• references/00-mcp-connection.md: MCP-Verbindung/Werkzeugentdeckung/Sicherheitsregeln/Kommandozeilen-Fallback ohne MCP
• references/01-blender-mcp-playbook.md: Blender-MCP-Werkzeugtabelle + bpy-Code-Snippet-Bibliothek (Import/Säubern/Materialien/LOD/Export/Screenshot)
• references/02-unity-mcp-playbook.md: Unity-MCP-Werkzeugtabelle + Szenen-/Objekt-/Asset-/Material-/Skript-/Build-Operationen
• references/03-asset-libraries.md: Asset-Bibliotheken-Übersicht (Lizenz/Format/Recherche/Suchbegriffe/Fallstricke chinesischer Seiten wie 3d66)
• references/04-asset-reuse-workflow.md: 9-Schritte-Workflow zur Asset-Wiederverwendung und Abnahmeliste
• references/05-model-from-scratch.md: Wann selbst modellieren, Blender-Game-Asset-Pipeline, Umgang mit KI-generierten Modellen
• references/06-blender-to-unity.md: Blender-zu-Unity-Standard-Pipeline (Achsen/Maßstab/FBX-Parameter/Material-Kanäle/LOD/Kollider/Humanoid)
• references/07-troubleshooting.md: Symptom → Ursache → Lösung (pinke Materialien/Skalierung/Normalen/umgefallene Modelle/fehlende Kollider/T-Pose/rutschende Füße usw.)

Sicherheitsregeln

• Vor Änderungen an bestehenden Blender-/Unity-Szenen immer ein Backup anlegen; Import und Säuberung ausschließlich in eigenständigen Blender-Szenen und im temporären Assets/Imports/-Verzeichnis des Unity-Projekts durchführen, nach erfolgreicher Abnahme in das endgültige Verzeichnis verschieben.
• Keine Benutzer-Quelldateien löschen oder überschreiben; heruntergeladene Originale im Zwischenspeicher belassen, gereinigte Exporte separat speichern.
• execute_blender_code und Unitys execute_code können beliebigen Code ausführen – keine vom aktuellen Task unabhängigen Operationen erlauben; gefährliche Aktionen (Löschen, Massenumbenennung, Überschreiben) erst nach Auflistung der betroffenen Objekte durchführen.
• Bei unklaren Lizenzen (insbesondere NC, nur zu Lernzwecken, kostenlose 3d66-Modelle, zahlende Mitgliedschaft) niemals in kommerziellen Projekten verwenden; lieber auf CC0-Quellen oder Eigenbau ausweichen.
• Alle Material-/Texturen-/Modell-Namen gemäß Namenskonvention (SM_/SK_/T_BC/N/RMA/M/M_/MI_), chinesische Dateinamen und Texturpfade vor dem Export vollständig in Englisch umwandeln.

Definition of Done (Asset-Ebene)

Jedes an Unity ausgelieferte Asset muss erfüllen:

• Lizenz ist dokumentiert (auch bei CC0 Quelle vermerken), kommerzielle Nutzung ohne Einschränkungen möglich
• Auditbericht: Polygonanzahl im Budget, UVs vorhanden, keine N-Gon-Probleme, Transformationen angewendet
• Korrekte Skalierung in der Szene (Mensch ca. 1,7 m, proportionale Größe zu umgebenden Objekten), korrekte Ausrichtung
• Materialien nicht pink, Texturen nicht verlorengegangen (Texturen im Paket/im Projekt), URP/HDRP-Kanäle korrekt
• Passende Kollider, für Charaktere/Animationsobjekte Avatar zugewiesen und Animationen funktionieren
• Prefab erstellt, LODs gemäß Anforderung konfiguriert, keine Fehler in der Konsole
• Qualitätsbild aus Schlüsselperspektive wurde von blender_asset_qa_render.py erstellt und durch Augenschein bestätigt (Texturen/Normalen/Metallizität/Rauheit/Form), bevor es dem Benutzer zur Bestätigung vorgelegt wird