Ferramentas Agentes Unity

O que Ferramentas Agentes Unity faz?

Use esta skill para configuração da CLI de Ferramentas Agentes Unity, descoberta e execução de comandos, fluxos de trabalho da bridge do Editor ao vivo e automação de projetos de alto nível.

CRÍTICO: Use o executor de comandos CLI para operações Unity. Não modifique manualmente arquivos serializados do Unity (.unity, .prefab, .asset, .mat, .anim, .controller, .meta, ProjectSettings/) a menos que o usuário peça explicitamente para trabalhar com arquivos brutos.

Superfície de Comandos

Comando	O que faz
list [query]	Descobre aliases embutidos, comandos de projeto atribuídos e APIs estáticas brutas opcionais. --brief omite detalhes por argumento; --raw adiciona estáticos brutos
run <target> [args...]	Executa um alias de comando ou método/propriedade pública estática C# através da bridge Unity
stream [topic]	Observa eventos da bridge em tempo real via WebSocket
install	Instala o pacote bridge Unity
uninstall	Remove o pacote bridge Unity
cleanup	Remove estado obsoleto da bridge ou caches .unity-agentic que podem ser reconstruídos
status	Verifica o executor de comandos e a acessibilidade da bridge, além de um bloco readiness informando com o que o Editor está ocupado

Comandos emitem JSON compacto de linha única por padrão; use --pretty para saída indentada. Prefira list <query> --brief para descoberta.

Por padrão, install escreve a URL do pacote GitHub. Para desenvolvimento local do pacote bridge, use install --local [path]; dependências file: existentes são preservadas a menos que install --remote seja passado.

Rota Padrão

1. unity-agentic-tools status -p <projeto>
2. unity-agentic-tools list <consulta> --brief -p <projeto>
3. Inspecione o estado atual com query.*, scene.hierarchy, ui.snapshot ou capturas de tela.
4. unity-agentic-tools run <alvo> ... -p <projeto>
5. Verifique com a consulta correspondente, snapshot, captura de tela, testes ou stream do console.

Exemplos

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

Passe um argumento estruturado posicionalmente entre aspas simples — o CLI codifica o array JSON externo por si só, então nenhum escape é necessário. Reserve --args '<array json>' para argumentos que começam com -. Consulte reference/troubleshooting.md "JSON Args".

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

APIs públicas estáticas brutas podem ser chamadas diretamente quando não há alias ou wrapper [AgenticCommand] existente.

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

Comandos do Projeto

Não adicione um novo comando CLI para cada operação Unity. Exponha comportamento específico do projeto adicionando [AgenticCommand] a métodos/propriedades públicas estáticas em Unity Editor C#:

using UnityAgenticTools.Commands;

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

Então use:

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

Referências

• reference/live-editor-workflows.md: configuração do Editor ao vivo, mutação, UI e fluxos de trabalho em lote
• reference/command-reference.md: referência de alias gerada com dicas de argumentos (<obrigatório> [opcional])
• reference/troubleshooting.md: bridge, timeouts, refs, argumentos JSON e verificação

Solução de Problemas

Detalhes completos estão em reference/troubleshooting.md. Dicas rápidas:

• Bridge não conecta: veja "Bridge Não Alcançável" (instalar, abrir Unity, aguardar compilação, status, limpeza). reachable: true com is_stable: false significa ocupado, não quebrado.
• Builds longas excedem tempo limite: run padrão é 60s; veja "Comandos de Longa Duração" (--timeout 1200000, --no-wait).
• Modo Play parece errado logo após play.enter: a resposta relata o estado atual, não o solicitado. Consulte play.state; veja "Transições do Modo Play" em reference/live-editor-workflows.md.
• Leituras lentas durante uma transição: esperado. Leituras aguardam uma recarga de domínio por até 30s em vez de falhar; veja "Recargas de domínio" em "Comandos de Longa Duração".
• Refs @hN/@uN obsoletas: execute scene.hierarchy ou ui.snapshot novamente; veja "Refs Obsoletas".
• Precisa de logs do console: unity-agentic-tools stream console --duration 5000 -p <projeto>.
• Precisa de APIs brutas: unity-agentic-tools list <tipo-ou-namespace> --raw -p <projeto>.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Identificador da skill"
    },
    "description": {
      "type": "string",
      "description": "Descrição curta"
    },
    "aiSummary": {
      "type": "string",
      "description": "Resumo detalhado para IA"
    },
    "skillMarkdown": {
      "type": "string",
      "description": "Conteúdo da SKILL.md"
    }
  },
  "required": ["name", "description", "aiSummary", "skillMarkdown"]
}