huayuehua15-netizen/unity-gameplay-dev

Unity Gameplay-Entwicklungs-Skill (First-Person / Unity 6 / URP)

Pfadkonvention (zuerst lesen): Alle scripts/-, references/- und assets/-Verweise in dieser Datei sind relativ zum Verzeichnis, in dem sich diese SKILL.md befindet. Vor dem Ausführen von Skripten zuerst in dieses Verzeichnis wechseln. Die Installationsorte variieren je nach Host: Claude Code Plugin im Plugin-Verzeichnis; Cursor/Codex installieren via install.ps1 in <Projekt>/skills/game-dev/<Skill-Name>/. Wenn unsicher, zuerst mit glob den absoluten Pfad dieser SKILL.md finden und dann Skripte mit absolutem Pfad aufrufen. python scripts/xxx.py direkt im Projektstammverzeichnis führt zu file-not-found.

Übersicht

Dieses Skill verwandelt GDD-Spezifikationen und 3D-Assets in spielbare Gameplay-Funktionen: Erstellen/Ändern von Skripten, Anhängen von Komponenten, Konfigurieren von Animationen und UI, Überprüfen im Play-Modus, Ausführen von Tests und Erstellen von Builds – alles per MCP. Standard-Stack: Unity 6 (6000.x LTS, kompatibel mit 6000.3), URP, UGUI, neues Input System, Cinemachine 3 (optional), Singleplayer, kein Multiplayer.

Grenzen

• Aufgaben: Gameplay-Logik, Controller, Interaktion, UI, Inventar/Dialog/Speichern, KI, Audio, Tests, Builds und Performance-Analyse.
• Nicht: 3D-Asset-Erstellung/Import/Materialien (überlassen Sie dies dem unity-blender-mcp Skill); Multiplayer (Netcode); Handgeschriebene Shader (nur Empfehlungen für Effekte).
• Zielprojekt verwendet First-Person-Perspektive; Third-Person/Top-Down nutzen dieselbe Architektur (Zustandsmaschine, Input, Interaktion, UI), nur Controller und Kamera-Zweig unterscheiden sich – siehe references/02.
• 2D-Projekte: Architekturebene (Zustandsmaschine/Event-Bus/Speichern/Inventar/UI-Stack) kann übernommen werden, aber Character-Controller, Physik, Navigation und Performance-Budget müssen ausgetauscht werden, siehe references/11-2d-gameplay.md. Verwenden Sie nicht den 3D-CharacterController + NavMesh für 2D.

Voraussetzungen

• Unity 6000.x (6000.0 LTS bis Oktober 2026 unterstützt, danach Upgrade auf 6000.3 LTS; Code ist kompatibel mit beiden).
• Erforderliche Pakete: com.unity.inputsystem (neues Input System), com.unity.ugui (UGUI), com.unity.ai.navigation (NavMesh-Baking), com.unity.test-framework (Tests, Scaffold erzeugt sie automatisch mit --tests); optional: com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• Pakete per MCP manage_packages installieren, oder das Scaffold schreibt die manifest automatisch (Input System / UGUI / Test-Framework, Versionen gemäß Editor-Integrations- und Mainline-Rückfalltabelle auflösen); nach der Installation in Project Settings → Active Input Handling auf Both setzen (das Scaffold schreibt activeInputHandler: 2).
• Version prüfen: ProjectSettings/ProjectVersion.txt; bei unsicherer API unity_docs / unity_reflect verwenden, keine API aus dem Gedächtnis schreiben.

Standard-Workflow (Von GDD zu spielbaren Funktionen)

Ablauf A: Neues Projekt / Neue Engine von Grund auf

1. Version und Pipeline bestätigen: manage_editor liest die Editor-Version; Projekt URP oder Built-in (Materialien und Post-Processing unterscheiden sich).
2. Scaffold ausführen: python scripts/new_gameplay.py --out "<Projekt>/Assets/Game" --namespace <Spielname> – erzeugt Framework-Code, asmdefs, Test-Assemblys und fügt automatisch die Input System-Abhängigkeit hinzu; einmal Unity öffnen, damit die Pakete heruntergeladen werden, dann das Scaffold erneut ausführen, um die asmdef-GUIDs zurückzuschreiben.
   • ⚠️ Erste Kompilierung mit Fehlern wie CS0234/CS0246 (UnityEngine.InputSystem nicht gefunden) ist erwartet, nicht das Scaffold ist kaputt: Ein neues Projekt hat die Pakete noch nicht heruntergeladen, daher fehlen die InputSystem-asmdef-GUIDs. Einmal Unity öffnen (Paket-Download) → Scaffold erneut ausführen → GUIDs zurückgeschrieben → dann Kompilierung fehlerfrei.
   • Getestet in Unity 6000.0.84f1: Nach erneuter Ausführung Kompilierung fehlerfrei, InventoryTests 3/3 bestanden.
3. Szenen-Einstiegsobjekte hinzufügen: Start-Szene gemäß references/01 aufbauen (GameManager, AudioManager, UIManager, EventSystem, Canvas) mit manage_gameobject / manage_components.
4. Funktionen nach Reihenfolge implementieren: Input → First-Person-Controller → Interaktion → HUD → spezifische Gameplay-Systeme → KI → Audio/VFX (Reihenfolge siehe unten „Funktionsentwicklungsreihenfolge“).
5. Funktion für Funktion verifizieren: Nach jeder Funktion manuell im Play-Modus testen + EditMode/PlayMode-Tests schreiben – siehe references/00 für den Verifizierungszyklus.
6. Navigation/Baking/Build: NavMesh-Baking, Szene in Build einbeziehen, Build-Checkliste – siehe references/08, references/09.

Ablauf B: Einzelne Funktion entwickeln (häufigster Fall)

GDD-Seite für die entsprechende Komponente lesen (Charakter/Interaktion/System/Dialog/Animations-Spezifikation) → Liste der zu ändernden Skripte und Komponenten erstellen → Vorlage auswählen oder neu erstellen → Implementierung im MCP-Editierzyklus → Play-Validierung → Tests ergänzen → „Definition of Done“ aktualisieren.

Ablauf C: Fehlersuche und Optimierung

Bei Kompilierungs-/Laufzeitfehlern references/10 konsultieren; bei Rucklern/Performance-Problemen den Profiler-Workflow aus references/08 durchführen; bei MCP-Fehlern den Fallback-Plan aus references/00 anwenden.

MCP-Editierzyklus (bei jeder Code-Änderung beachten)

1. refresh_unity zuerst zur Synchronisation der Festplatte ausführen; read_console verwenden, um fehlerfreien Ausgangszustand zu bestätigen.
2. Skript erstellen: create_script; Skript ändern: bevorzugt script_apply_edits (strukturierte Methoden-Editierung), nur kleine Änderungen mit apply_text_edits; nach der Änderung validate_script aufrufen.
3. refresh_unity ausführen (löst Kompilierung aus) → read_console für Kompilierungsergebnisse (CS-Fehler sofort beheben, nicht mit Fehlern fortfahren).
4. Komponenten anhängen/Referenzen setzen: manage_components / manage_gameobject; Animationen mit manage_animation; UI mit manage_gameobject (nur UI Toolkit mit manage_ui).
5. Play-Modus-Validierung: manage_editor zum Wechseln in den Play-Modus, read_console für Laufzeitausnahmen; Kameraperspektive/-Gefühl mit find_gameobjects zum Auslesen des Transform-Status prüfen, bei Bedarf execute_code für Game View-Screenshot.
6. Mehrere nicht-konfliktäre Operationen in batch_execute zusammenfassen; vor Abschluss jeder Funktion manage_scene zum Speichern der Szene aufrufen.

Funktionsentwicklungsreihenfolge (nach dem Scaffold)

1. Input InputReader (vom Scaffold generiert) → Im Player in der Szene platzieren, WASD/Maus funktionieren
2. First-Person PlayerLook + FirstPersonController (Gehen, Rennen, Springen, Ducken, Landen)
   - 2D-Projekte verwenden stattdessen `PlatformerController2D` (wird automatisch mit `--dimension 2d` generiert; 3D-spezifische Dateien werden nicht generiert)
3. Interaktion Interactor + Tür/Aufhebbare Objekte (Fadenkreuz-UI muss funktionieren)
4. HUD + Menü-Panel-Stack (UIManager, ESC zum Pausieren)
5. Gameplay-Systeme: Health/Inventar/Dialog (je nach GDD auswählen)
6. Speichern SaveSystem (vorhandene Systeme mit ISaveable verbinden)
7. Gegner-KI: NavMesh-Baking + EnemyAI + Wahrnehmung
8. Audio AudioManager + Mixer; VFX (Partikel/Mündungsfeuer/Treffer)
9. Performance Profiler zur Frame-Analyse; Build erstellen (references/08, 09)

Scaffold und Vorlagen

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests: Keine Test-Assemblys generieren
#   --editor-data "Editor/Data-Pfad": Input System-Version auflösen (wenn nicht angegeben, wird die Rückfalltabelle verwendet)

Vorlagenliste (assets/templates/). Hinweis: Vorlagen enthalten Platzhalter für Namespace {{NS}}, vor manuellem Kopieren ersetzen, oder besser new_gameplay.py ausführen, das die Ersetzung automatisch vornimmt – sonst kann nicht kompiliert werden:

Modul	Datei	Zweck
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	Singleton, Zustandsmaschine, Event-Bus, Spielablauf (Menü/Spiel/Pause/Laden)
Input	InputReader	Code-basierte Kapselung des neuen Input Systems, Tastatur/Maus + Gamepad
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D: CharacterController-Bewegung, Mausperspektive, Rennen/Springen/Ducken. 2D: Rigidbody2D-Plattform-Jumping (mit Coyote-Time / Jump-Buffer / variable Sprunghöhe)
Interaktion	InteractableBase / Interactor / PickupItem	Fadenkreuz-Interaktion, Aufhebbare Objekte (Beispiel)
Systeme	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	Leben, Inventar, JSON-Speicher, linearer Dialog, Objekt-Pool, Audio
KI	EnemyAI / EnemyPerception	NavMesh-Patrouille/Verfolgung/Angriff Zustandsmaschine + Kegel-Wahrnehmung
UI	UIPanel / UIManager / HUDController	Panel-Stack, HUD mit Lebensbalken/Hinweisen/Untertiteln
Tests	InventoryTests (+ asmdef)	Beispiel für Inventar-Logik-Tests, ausführbar mit run_tests

Referenzdokument-Index (bei Bedarf laden)

• references/00-mcp-code-workflow.md: MCP-47-Tools abgebildet auf Gameplay-Aufgaben, Editierzyklus, Play-Validierung, Tests, Fallback ohne MCP
• references/01-architecture.md: Verzeichnisstruktur, asmdef, Namenskonventionen, datengesteuertes Design, Grenzen von Referenzen/Events/Singletons, ScriptableObject
• references/02-input-and-fp-controller.md: Implementierung des Input-Systems, Player-Prefab-Hierarchie, Parametertabelle für First-Person-Bewegung und -Kamera, Third-Person/Top-Down-Zweig
• references/03-interaction-animation.md: Interaktionsebene, Animator-Zustandsmaschine/Blend-Tree/Root-Motion, Animations-Events, Humanoid-Anbindung
• references/04-ui-ugui.md: Canvas/EventSystem-Aufbau, Panel-Stack, HUD, Pause, Eingabeumschaltung
• references/05-gameplay-systems.md: Verwendung und Erweiterungsrichtlinien für Health/Inventar/Dialog/Speichern/Object-Pooling, Datendefinitionen
• references/06-ai-navigation.md: NavMesh-Baking, Gegner-Konfiguration, Patrouillenpunkte, Wahrnehmungs-Parameter, Zustandserweiterung
• references/07-audio-vfx.md: AudioMixer-Gruppen, Audio-Pool, Musik-Überblendung, Partikel/VFX Graph-Auswahl
• references/08-performance.md: 60fps-Budget, Profiler/Frame-Debugger-Workflow, häufige Engpässe
• references/09-build-release.md: Build-Einstellungen, Szenen-Liste, Steam/Deck-Prüfung, Speicher-Kompatibilität
• references/10-troubleshooting.md: Häufige Fehler bei Kompilierung/Null-Referenzen/Ausführungsreihenfolge/Input/Navigation/UI
• references/11-2d-gameplay.md: Vor der Arbeit an 2D-Projekten zuerst lesen. 2D-Paket-Installation, Sprite-Import, Physics2D und Layer-Matrix, 2D-Plattform-Jumping (Coyote-Time/Jump-Buffer), Tilemap und Composite-Kollision, Pixel-Perfect-Kamera, 2D-Budget basierend auf Overdraw und Batches (Dreiecks-Budget-Tabellen sind für 2D irrelevant).

Hinweis für 2D-Projekte: Die C#-Vorlagen dieses Skills sind standardmäßig auf 3D First-Person ausgelegt (CharacterController, NavMesh). Für 2D die dimensionsunabhängigen Teile wiederverwenden (EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager), während Controller, Navigation, Physik und Performance-Budget gemäß references/11 neu geschrieben werden müssen.

Eiserne Regeln

• Werte aus GDD: Bewegungsgeschwindigkeit, Sprunghöhe, Schaden, Treffer-Frames, Sichtweite müssen im Inspector exponiert sein und mit der GDD-Seite übereinstimmen; wenn der GDD-Wert fehlt, mit 【Zu bestätigen】 markieren, keine Werte erfinden.
• Jeder Schritt muss verifizierbar sein: Nach Code-Änderungen Kompilierung fehlerfrei, Play-Modus-Test bestanden; bei gefühlssensitiven Aspekten (Bewegung/Kamera/Interaktion) müssen Transform/Status-Beweise aufgezeichnet werden, nicht nur „sollte funktionieren“ sagen.
• Keine vorgetäuschte Kompilierung: Wenn validate_script oder read_console nicht bestanden ist, gilt die Aufgabe als nicht abgeschlossen; wenn eine Verifizierung in dieser Umgebung nicht möglich ist, dies klar angeben, keine Ergebnisse erfinden.
• Daten und Logik trennen: Einstellbare Werte als SerializeField/ScriptableObject; Präsentationsschicht abonniert Events, nicht in Systemklassen schreiben.
• Namenskonventionen: Klassen PascalCase; Dateiname mit Hauptklassenname übereinstimmend; Szenen/ Prefabs Level_01_, PF_Player; Konstanten kein Chinesisch; CS-Warnungen in der Console ebenfalls beheben.
• Kleine Schritte, häufige Commits: Eine Funktion pro Commit; vor Änderungen Szene speichern/sichern; bei riskanten Operationen (Löschen, Massen-Änderungen an Komponenten) zuerst die betroffenen Objekte auflisten.

Definition of Done (DoD)

• Implementierte Logik stimmt mit der GDD-Seite überein, Werte nachvollziehbar (Branchen-Standardwerte sind markiert)
• Kompilierung fehlerfrei, keine Warnungen (Screenshot/Log von read_console als Beleg)
• Play-Modus-Test bestanden: Eingabe, Zustandswechsel, Interaktion, Feedback reproduzierbar
• Unit-testbare Logik hat Tests (run_tests grün)
• Zugehörige Referenzen/Komponenten/Hierarchie vollständig konfiguriert (Prefab kann in leere Szene gezogen werden und funktioniert, ohne manuelle temporäre Verkabelung)
• Speicher-Neufelder mit Versionsnummer behandelt; neue Szenen in Build eingebunden
• Performance ohne neue Engpässe (Ziel 60fps, mobile/Deck siehe 08)