taconotsandwich/unity-agentic-tools

Unity Agentic Tools

Utiliza esta skill para la configuración de la CLI de Unity Agentic Tools, descubrimiento de comandos, ejecución de comandos, flujos de trabajo con el puente del Editor en vivo y automatización de proyectos a alto nivel.

CRÍTICO: Usa el ejecutor de comandos CLI para las operaciones de Unity. No manipules manualmente archivos serializados de Unity (.unity, .prefab, .asset, .mat, .anim, .controller, .meta, ProjectSettings/) a menos que el usuario solicite explícitamente trabajo con archivos en bruto.

Superficie de Comandos

Comando	Qué hace
list [query]	Descubre alias integrados, comandos de proyecto atribuidos y APIs estáticas en bruto opcionales. --brief omite el detalle por argumento; --raw añade estáticas en bruto
run <target> [args...]	Ejecuta un alias de comando o un método/propiedad estática pública de C# a través del puente de Unity
stream [topic]	Observa eventos del puente en tiempo real a través de WebSocket
install	Instala el paquete del puente de Unity
uninstall	Elimina el paquete del puente de Unity
cleanup	Elimina el estado obsoleto del puente o cachés de .unity-agentic reconstruibles
status	Comprueba la capacidad de alcance del ejecutor de comandos y del puente, además de un bloque de readiness que indica con qué está ocupado el Editor

Los comandos emiten JSON compacto de una sola línea por defecto; pasa --pretty para una salida indentada. Prefiere list <query> --brief para el descubrimiento.

Por defecto, install escribe la URL del paquete de GitHub. Para desarrollo local del paquete del puente, usa install --local [path]; las dependencias file: existentes se conservan a menos que se pase install --remote.

Ruta por Defecto

1. unity-agentic-tools status -p <project>
2. unity-agentic-tools list <query> --brief -p <project>
3. Inspecciona el estado actual con query.*, scene.hierarchy, ui.snapshot o capturas de pantalla.
4. unity-agentic-tools run <target> ... -p <project>
5. Verifica con la consulta coincidente, captura de pantalla, pruebas o flujo de consola.

Ejemplos

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>

Pasa un argumento estructurado de forma posicional entre comillas simples — la CLI codifica el array JSON externo por sí misma, por lo que no se necesita escape. Reserva --args '<json array>' para argumentos que comiencen con -. Consulta reference/troubleshooting.md "JSON Args".

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

Las API estáticas públicas en bruto se pueden llamar directamente cuando no existe un alias o un envoltorio [AgenticCommand].

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

Comandos de Proyecto

No agregues un nuevo comando CLI para cada operación de Unity. Expón el comportamiento específico del proyecto añadiendo [AgenticCommand] a métodos/propiedades estáticas públicas en C# del Editor de Unity:

using UnityAgenticTools.Commands;

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

Luego usa:

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

Referencias

• reference/live-editor-workflows.md: configuración del Editor en vivo, mutación, UI y flujos de trabajo por lotes
• reference/command-reference.md: referencia de alias generada con indicaciones de argumentos (<requerido> [opcional])
• reference/troubleshooting.md: puente, tiempos de espera, referencias, argumentos JSON y verificación

Solución de Problemas

El detalle completo está en reference/troubleshooting.md. Pistas rápidas:

• El puente no se conecta: consulta "Puente No Alcanzable" (instalar, abrir Unity, esperar a la compilación, estado, limpieza). reachable: true con is_stable: false significa ocupado, no roto.
• Las compilaciones largas agotan el tiempo: run tiene un valor por defecto de 60s; consulta "Comandos de Larga Duración" (--timeout 1200000, --no-wait).
• El modo de reproducción se ve mal justo después de play.enter: la respuesta informa del estado actual, no del solicitado. Consulta play.state; consulta "Transiciones del Modo de Reproducción" en reference/live-editor-workflows.md.
• Las lecturas son lentas durante una transición: es esperado. Las lecturas esperan una recarga de dominio hasta 30s en lugar de fallar; consulta "Recargas de dominio" en "Comandos de Larga Duración".
• Referencias @hN/@uN desactualizadas: vuelve a ejecutar scene.hierarchy o ui.snapshot; consulta "Referencias Desactualizadas".
• Necesitas registros de consola: unity-agentic-tools stream console --duration 5000 -p <project>.
• Necesitas APIs en bruto: unity-agentic-tools list <type-or-namespace> --raw -p <project>.