Mit KI Cocos-Szenendokumentation erstellen: Damit Code-Assistenten Ihr Spiel wirklich verstehen

Wenn Sie Claude bitten, eine neue Komponente zu schreiben, referenziert der generierte Code Knotennamen, die gar nicht existieren. Wenn Sie Cursor um eine Funktion bitten, weiß es nicht, dass Sie bereits ein fertiges Prefab wiederverwenden können. Jedes Mal, wenn Sie die Projektstruktur erklärt haben, müssen Sie es zwei Tage später von vorn erklären.

Bei KI-gestützter Spieleentwicklung ist das Alltag. Bei normalen Web-Projekten arbeitet KI recht flüssig – bei Cocos Creator stimmt oft etwas nicht. Nicht, weil die KI dumm ist, sondern weil sie Ihre Szenenhierarchie, Knotenstruktur und Komponentenkonfiguration schlicht nicht sieht.

Dahinter steht ein grundlegendes Problem: KI und Game-Engine sind zwei getrennte Werkzeuge. KI kann nur Code-Dateien lesen, aber das Wesentliche in Cocos liegt in Szenendateien – die JSON-Struktur von .scene und .prefab lässt sich nicht direkt sinnvoll erschließen.

In diesem Artikel teile ich eine praktische Lösung: CLAUDE.md plus Szenendokumentation, damit KI Ihr Spielprojekt wirklich versteht. Außerdem gibt es kopierbare Prompt-Vorlagen, mit denen Sie Ihre eigene Szenendokumentation erzeugen können.

1. Warum KI Ihr Spielprojekt nicht versteht

1.1 Die „Isolation“ zwischen KI und Engine

Ein Blogbeitrag von Summer Engine erklärt es treffend: KI und Engine sind getrennte Tools. KI hat keinerlei Wahrnehmung von Szenenhierarchie, vorhandenen Skripten oder Projektstruktur. Wenn Sie Code schreiben lassen, inferiert sie nur aus dem gegebenen Kontext – und der reicht meist nicht.

Das unterscheidet sich von Web-Entwicklung. Bei Web-Projekten liegt die Struktur weitgehend in Dateien; KI versteht sie nach einem Durchlauf. Bei Spielen? Viel Wissen steckt im Editor – Szenenhierarchie, Knotenpositionen, Komponentenparameter. Das drückt sich in Code-Dateien nicht aus.

1.2 Besonderheiten von Cocos-Creator-Projekten

Szenen (Scene) in Cocos Creator sind logische Organisationsstrukturen, keine Code-Dateien. Öffnen Sie eine .scene-Datei, sehen Sie JSON – KI parst das nicht sinnvoll. Die Knotenhierarchie (Hierarchy) entsteht per Drag-and-Drop im Editor; Prefabs sind Ressourcendateien mit eigener Logik.

Das führt zu einer unangenehmen Situation: Sie bitten die KI, „ScoreLabel unter GameRoot zu ändern“ – sie weiß nicht, was GameRoot ist und wo ScoreLabel hängt. Sie müssen die gesamte Szenenstruktur manuell beschreiben. Ermüdend.

1.3 Grenzen bestehender Ansätze

CLAUDE.md ist ein Ansatz, erfordert aber manuelles Schreiben und hohen Pflegeaufwand. Jede Szenenänderung muss nachgezogen werden, sonst veraltet der Kontext. MCP-Server sind leistungsfähiger, aber anspruchsvoller: WebSocket-Dienst, Port, Berechtigungen. Unity hat Tools wie Bezi mit Echtzeit-Indexierung für Skripte, Assets und Szenen – für Cocos gibt es noch nichts Vergleichbares.

Die realistischste Lösung bleibt Dokumentation: Was KI nicht sieht, schreiben Sie auf, damit sie es lesen kann.

2. CLAUDE.md: Damit KI sich Ihr Projekt merkt

2.1 Was ist CLAUDE.md?

CLAUDE.md ist die projektweite Kontextdatei für Claude Code im Projektroot. Entsprechendes gibt es für Cursor (.cursorrules) und GitHub Copilot (.github/copilot-instructions.md). Zweck: der KI Kontext liefern, den sie aus Code nicht ableiten kann.

Bei einer Komponente ScoreManager erkennt KI aus Code deren Funktion – aber nicht, an welchem Knoten sie hängt und mit welchen Knoten sie interagiert. Genau das gehört in CLAUDE.md.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

2.2 Was in CLAUDE.md für Spielprojekte gehört

Der Blog von Mr. Phil Games empfiehlt diese Kategorien:

Grundlegende Projektinfos: Engine-Version, Zielplattform, Spieltyp. So weiß die KI, ob Cocos 3.8 oder 2.x zum Einsatz kommt und ob WeChat-Mini-Game oder App das Ziel ist.

Szenenstruktur-Überblick: Was Boot-Szene, Game-Szene und Ergebnisseite leisten. Erst dann versteht die KI „Ressourcen in der Boot-Szene laden“.

Namenskonventionen für Kernknoten: Top-Level-Knoten wie Canvas, GameRoot, UIRoot. Die KI nutzt diese Namen beim Codegenerieren.

Komponentenliste: Implementierte Kernkomponenten und ihre Aufgaben. Verhindert, dass die KI das Rad neu erfindet.

2.3 Beispiel CLAUDE.md für ein Cocos-Creator-Projekt

Aus einem Casual-Mini-Game-Projekt – als Referenz:

# Projektkontext – Mini-Game-Demo

## Grundinformationen
- Engine: Cocos Creator 3.8
- Typ: Casual-Mini-Game
- Plattform: WeChat-Mini-Game

## Szenenstruktur
- Boot.scene: Start- und Ladeszene, GameManager angehängt
- Game.scene: Hauptspielszene mit GameRoot + UIRoot
- Result.scene: Ergebnisseite mit Punkteanzeige und Buttons

## Kernknoten
- Canvas: UI-Root-Knoten
- GameRoot: Spielinhalt, GameLogic-Komponente
- UIRoot: UI-Ebene mit ScoreLabel, PauseButton

## Implementierte Komponenten
- GameManager: Spiel-Lebenszyklus
- ScoreManager: Punkteberechnung und -speicherung
- AudioManager: Soundwiedergabe

## Code-Konventionen
- Alle UI-Knoten unter Canvas
- Spiellogik-Knoten unter GameRoot
- Manager-Klassen enden mit Manager

Mit dieser Datei fragt die KI nicht mehr „Was ist GameManager?“ oder „Wo ist GameRoot?“.

3. Szenendokumentation: Praxis der automatischen Erstellung

3.1 Warum Szenendokumentation nötig ist

CLAUDE.md ist Projektüberblick – zu grob. Pro Szene braucht es Knotenhierarchie und Komponentenkonfiguration. Die KI soll wissen: welche Knoten existieren und welche Komponenten wo hängen.

Ein Fehler aus der Praxis: KI soll Pause implementieren und sucht den Knoten PauseButton. Tatsächlich liegt er unter UIRoot/PauseLayer/PauseButton – zwei Ebenen tiefer. Die KI wusste es nicht, ich habe es vergessen zu sagen – Laufzeitfehler.

Szenendokumentation verhindert das: Struktur pro Szene klar beschrieben, KI findet Knoten beim Codegen.

3.2 Szenendokumentation per Prompt automatisch erzeugen

Manuell schreiben ist mühsam – ich nutze KI zur Generierung. Prompt-Vorlage zum Kopieren:

Ich habe ein Cocos-Creator-3.8-Spielprojekt. Bitte erstelle Szenendokumentation.

Projektinfos:
- Spieltyp: Casual-Mini-Game
- Engine-Version: Cocos Creator 3.8

Bitte auf Basis folgender Angaben dokumentieren:
1. Szenenname: {scene_name}
2. Szenenzweck: {scene_purpose}
3. Haupt-Knotenhierarchie (bitte beschreiben):
   - {node_structure}

Ausgabeformat:
- Szenenüberblick (ein Satz zum Zweck)
- Knotenbaum (Baumstruktur mit Komponenten)
- Komponentenverantwortlichkeiten
- Hinweise zur Code-Referenz (typische Fallstricke)

Ersetzen Sie {scene_name}, {scene_purpose} und {node_structure} durch Ihre Werte.

3.3 Praxisbeispiel: Dokumentation für Game.scene

Mit diesem Prompt entstand folgende Dokumentation für Game.scene. Eingabe:

1. Szenenname: Game.scene
2. Szenenzweck: Hauptspielszene mit Spiellogik- und UI-Ebene
3. Haupt-Knotenhierarchie:
   - Canvas (UI-Root)
     - UIRoot (UI-Container)
       - ScoreLabel (Punkteanzeige, Label-Komponente)
       - PauseButton (Pause-Button, Button-Komponente)
   - GameRoot (Spiellogik)
     - PlayerNode (Spieler, PlayerController)
     - EnemyRoot (Gegner-Container)

KI-Ausgabe:

# Game.scene – Szenendokumentation

## Szenenüberblick
Hauptspielszene für Kernlogik und UI.

## Knotenbaum
Canvas (UI-Root)
├── UIRoot (UI-Container)
│   ├── ScoreLabel [Label] – Punkteanzeige
│   └── PauseButton [Button] – Pause-Button
└── GameRoot (Spiellogik)
    ├── PlayerNode [PlayerController] – Spielerfigur
    └── EnemyRoot – Gegner-Container

## Komponentenverantwortlichkeiten
| Komponente | Knoten | Aufgabe |
|------|---------|------|
| PlayerController | PlayerNode | Eingabe und Bewegung |
| Label | ScoreLabel | Punkte-Text |
| Button | PauseButton | Pause-Interaktion |

## Hinweise zur Code-Referenz
1. UI-Knoten ab Canvas suchen: `this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel liegt unter UIRoot, nicht direkt unter Canvas
3. PlayerNode unter GameRoot, gleichrangig zu Canvas

Die Datei liegt unter docs/; in CLAUDE.md ein Verweis: Detaillierte Szenenstruktur siehe docs/Game.scene.md.

3.4 Aktualisierung und Pflege

Dokumentation ist kein Einmaljob. Ändert sich die Szenenstruktur, muss die Doku folgen. Mein Vorgehen:

Nach Szenenänderungen die Doku mitaktualisieren – etwa 5 Minuten, weniger Aufwand als der KI alles neu zu erklären.

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Manche Teams binden Generierung in CI/CD ein. Für kleine Teams ist manuelle Pflege oft praktikabler – Szenen ändern sich selten drastisch.

4. MCP-Server: KI direkt mit der Engine verbinden

4.1 Was ist ein MCP-Server?

MCP (Model Context Protocol) ist ein Protokoll, über das KI per JSON-RPC mit externen Tools kommuniziert. Skywork AI bietet einen Cocos-Creator-MCP-Server – KI spricht direkt mit dem Editor.

Kurz: Die KI muss die Szenenstruktur nicht manuell erfragt bekommen – sie kann beim Editor nachfragen.

4.2 Was der MCP-Server leistet

Laut Skywork AI unterstützt der Cocos-MCP-Server:

• Szeneninformationen per Tool-Aufruf
• Knoten direkt im Editor anlegen
• Prefab-Inhalte lesen
• Komponentenkonfiguration abfragen

Stärker als CLAUDE.md, weil die Informationen live sind. Ändern Sie die Szene, weiß die KI es sofort – ohne Doku-Sync.

4.3 Hürden und Grenzen

MCP ist nicht ohne Aufwand:

Komplexe Konfiguration: WebSocket-Dienst, Ports, Berechtigungen – kann Stunden kosten.

Begrenzte KI-Unterstützung: Derzeit vor allem Claude Code mit MCP; Cursor und Copilot noch nicht.

Wenig Dokumentation: Community und Docs zum Cocos-MCP-Server sind dünn.

Für Einzelentwickler, die schnell starten wollen, passt CLAUDE.md plus Szenendokumentation besser. MCP lohnt sich für Teams mit Entwicklungskapazität auf lange Sicht.

4.4 MCP und CLAUDE.md gemeinsam nutzen

Beides ergänzt sich, ersetzt sich nicht:

• CLAUDE.md: statischer Kontext – Überblick, Namenskonventionen, Designideen
• MCP: dynamische Interaktion – Live-Szeneninfo, Knoten anlegen

Mit MCP bleibt CLAUDE.md sinnvoll. MCP beantwortet „was ist jetzt da“, nicht „warum so designed“ oder „welche Namensregeln gelten“. Das steht weiter in CLAUDE.md.

5. Praxis-Fazit und Handlungsempfehlungen

5.1 Minimal tragfähige Lösung (heute starten)

Wenn die KI Ihr Projekt verstehen soll, ohne aufwendige Konfiguration – drei Schritte:

Schritt 1: CLAUDE.md mit Grundinfos – Engine, Spieltyp, Szenenüberblick.

Schritt 2: Prompt aus Kapitel 3 für drei Kernszene – Boot, Game, Result.

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Schritt 3: Szenendokumente unter docs/, Verweis in CLAUDE.md.

In etwa einer halben Stunde erledigt. Danach reicht es, der KI die Dokumente zu geben.

5.2 Fortgeschritten (Teams mit Entwicklungskapazität)

Mit mehr Aufwand:

Cocos-MCP-Server einrichten: Open-Source von Skywork AI, Dokumentation brauchbar. Danach Live-Szeneninfo für die KI.

Szenen-Export-Skript: Cocos-Erweiterung, die Struktur als JSON oder Markdown exportiert – genauer als manuelle Beschreibung.

Automatische Updates: Export in den Build-Prozess, CLAUDE.md bei jedem Build aktualisieren.

Mehr Entwicklungsaufwand – für mittlere und größere Teams sinnvoll.

5.3 Langfristiges Ziel

Ideal: KI versteht Spielprojekte wie Web-Projekte. Editor und KI tief integriert, Dokumentation als Branchestandard.

Unity hat Bezi; Cocos wird vermutlich nachziehen. Bis dahin ist Dokumentation der zuverlässigste Weg.

Fazit

Bei KI-gestützter Spieleentwicklung blockiert eine Grundschwelle: KI sieht Editor-Inhalte nicht. Szenenhierarchie, Knotenstruktur, Komponenten – alles unsichtbar. Lösung: dokumentieren, was KI nicht sieht.

CLAUDE.md ist projektweiter Kontext, Szenendokumentation die feine Granularität. Zusammen findet die KI Knoten zuverlässig und versteht Komponentenaufgaben. Mit Entwicklungskapazität: MCP-Server für Echtzeit-Szeneninfo.

Probieren Sie es heute: CLAUDE.md anlegen, mit dem Prompt aus diesem Artikel die erste Szenendokumentation erzeugen. Andere Erfahrungen? Gerne in den Kommentaren teilen.