taconotsandwich/unity-agentic-tools

Unity Agentic Tools

Nutze dieses Skill für die Einrichtung der Unity Agentic Tools CLI, die Befehlsermittlung, die Befehlsausführung, Live-Editor-Bridge-Workflows und die High-Level-Projektautomatisierung.

KRITISCH: Verwende den CLI-Befehlsausführer für Unity-Operationen. Mutiere keine Unity-Serialisierungsdateien (.unity, .prefab, .asset, .mat, .anim, .controller, .meta, ProjectSettings/) manuell, es sei denn, der Benutzer bittet explizit um direkte Dateiarbeit.

Befehlsübersicht

Befehl	Funktion
list [query]	Entdeckt integrierte Aliase, attributierte Projektbefehle und optionale rohe statische APIs. --brief lässt Detailinformationen pro Argument weg; --raw fügt rohe statische hinzu
run <target> [args...]	Führt einen Befehlsalias oder eine rohe öffentliche statische C#-Methode/Eigenschaft über die Unity-Bridge aus
stream [topic]	Verfolgt Echtzeit-Bridge-Ereignisse per WebSocket
install	Installiert das Unity-Bridge-Paket
uninstall	Entfernt das Unity-Bridge-Paket
cleanup	Entfernt veraltete Bridge-Zustände oder neu erstellbare .unity-agentic-Caches
status	Prüft die Erreichbarkeit des Befehlsausführers und der Bridge sowie einen readiness-Block, der angibt, womit der Editor beschäftigt ist

Befehle geben standardmäßig kompakte einzeilige JSON aus; verwende --pretty für formatierte Ausgabe. Bevorzuge list <query> --brief zur Erkennung.

Standardmäßig schreibt install die GitHub-Paket-URL. Für die lokale Bridge-Paketentwicklung verwende install --local [path]; bestehende file:-Abhängigkeiten bleiben erhalten, es sei denn, install --remote wird übergeben.

Standardvorgehen

1. unity-agentic-tools status -p <project>
2. unity-agentic-tools list <query> --brief -p <project>
3. Überprüfe den aktuellen Zustand mit query.*, scene.hierarchy, ui.snapshot oder Screenshots.
4. unity-agentic-tools run <target> ... -p <project>
5. Verifiziere mit der passenden Abfrage, Momentaufnahme, Screenshot, Tests oder Konsolen-Stream.

Beispiele

unity-agentic-tools list scene --brief -p <project>
unity-agentic-tools run project.refresh -p <project>
unity-agentic-tools run query.scene Assets/Scenes/Main.unity -p <project>
unity-agentic-tools run create.gameobject Assets/Scenes/Main.unity EnemyRoot Gameplay -p <project>
unity-agentic-tools run update.transform Assets/Scenes/Main.unity Player 1,2,3 0,90,0 1,1,1 -p <project>
unity-agentic-tools stream console --type Error -p <project>
unity-agentic-tools cleanup --cache -p <project>

Übergib ein strukturiertes Argument positionell in einfachen Anführungszeichen – die CLI kodiert das äußere JSON-Array selbst, sodass kein Escaping nötig ist. Verwende --args '<json-array>' für Argumente, die mit - beginnen. Siehe reference/troubleshooting.md unter „JSON Args".

unity-agentic-tools run update.batch Assets/Scenes/Main.unity '[{"gameObjectPath":"Player","propertyPath":"m_Name","value":"Hero"}]' -p <project>

Rohe öffentliche statische APIs können direkt aufgerufen werden, wenn kein Alias oder [AgenticCommand]-Wrapper existiert.

unity-agentic-tools run UnityEditor.AssetDatabase.Refresh -p <project>
unity-agentic-tools run UnityEditor.EditorApplication.ExecuteMenuItem "File/Save" -p <project>

Projektbefehle

Füge keinen neuen CLI-Befehl für jede Unity-Operation hinzu. Mache projektspezifisches Verhalten verfügbar, indem du [AgenticCommand] zu öffentlichen statischen Methoden/Eigenschaften im Unity-Editor-C# hinzufügst:

using UnityAgenticTools.Commands;

public static class BuildCommands
{
    [AgenticCommand("build.addressables", "Addressables-Inhalt erstellen.")]
    public static object BuildAddressables(string profile)
    {
        return new { success = true, profile };
    }
}

Dann verwende:

unity-agentic-tools list build --brief -p <project>
unity-agentic-tools run build.addressables Production -p <project>

Referenzen

• reference/live-editor-workflows.md: Live-Editor-Setup, Mutationen, UI und Batch-Workflows
• reference/command-reference.md: Generierte Alias-Referenz mit Argumenthinweisen (<erforderlich> [optional])
• reference/troubleshooting.md: Bridge, Zeitüberschreitungen, Referenzen, JSON-Argumente und Verifikation

Fehlerbehebung

Ausführliche Details findest du in reference/troubleshooting.md. Kurze Hinweise:

• Bridge verbindet nicht: Siehe „Bridge nicht erreichbar" (installieren, Unity öffnen, auf Kompilierung warten, Status, Bereinigung). reachable: true mit is_stable: false bedeutet beschäftigt, nicht defekt.
• Lange Builds haben Zeitüberschreitung: run hat standardmäßig 60s; siehe „Langlaufende Befehle" (--timeout 1200000, --no-wait).
• Play-Modus sieht direkt nach play.enter falsch aus: Die Antwort meldet den aktuellen Zustand, nicht den angeforderten. Frage play.state ab; siehe „Play-Modus-Übergänge" in reference/live-editor-workflows.md.
• Lesevorgänge sind während eines Übergangs langsam: Erwartet. Lesevorgänge warten bis zu 30s auf einen Domain-Neulad, anstatt zu scheitern; siehe „Domain-Neuladungen" unter „Langlaufende Befehle".
• Veraltete @hN/@uN-Referenzen: Führe scene.hierarchy oder ui.snapshot erneut aus; siehe „Veraltete Referenzen".
• Konsolenprotokolle benötigt: unity-agentic-tools stream console --duration 5000 -p <project>.
• Rohe APIs benötigt: unity-agentic-tools list <type-or-namespace> --raw -p <project>.