O pacote Unity Pipeline e a CLI do Unity : Guia de instalação e passo a passo
Principais conclusões
- O pacote Unity Pipeline é executado dentro do Unity Editor e expõe comandos por meio de uma API HTTP e JSON.
- O Unity CLI é um cliente independente que permite que terminais, agentes e scripts de automação executem esses comandos.
- Comandos integrados e personalizados oferecem suporte a fluxos de trabalho repetíveis, como configuração de projetos, recompilação, testes e controle de tempo de execução.
- O mesmo contrato de comando pode alimentar a CLI do Unity , fluxos de trabalho de agentes e interfaces personalizadas.
Visão geral
O Unity CLI é gratuito e está em versão beta. Combine-o com o pacote Unity Pipeline para controlar seu Editor a partir do terminal para CI, scripts e agentes de IA.
O pacote Unity Pipeline adiciona um servidor leve dentro do seu Unity Editor, permitindo que ele se comunique diretamente com seu terminal ou outras ferramentas por meio de protocolos web padrão. Você pode acionar comandos como verificações de status, compilações ou execuções de teste externamente. Como essas operações são gerenciadas de forma assíncrona, elas permanecem ativas mesmo quando o Editor é recarregado após uma alteração no script. Essa configuração torna sua automação consistente, previsível e fácil de programar.
Componentes
- Unity CLI: O Unity CLI é um binário independente instalado separadamente do Editor, que se conecta a um Editor em execução e o controla a partir do terminal. O pacote Pipeline requer o Unity 6.0 ou posterior.
- Pacote Unity Pipeline : este pacote é instalado em um projeto (com.unity.pipeline) através da CLI. O pacote é executado dentro do Editor e inicia automaticamente um servidor local quando o Editor é carregado.
- Comandos : Cada comando é uma função no projeto, etiquetada para que o Unity a registre automaticamente. Os comandos integrados abrangem o modo de reprodução, o status, a recompilação e a execução de testes, com a opção de adicionar seus próprios comandos.
- Avaliação: Isso executa C# diretamente dentro de uma instância ativa do Unity (o Editor ou uma versão em execução) para ações pontuais. Ele executa código C# arbitrário e é protegido por um token de segurança; trate-o como execução remota de código e limite-o ao desenvolvimento local.
Arquitetura
- Clientes : O chamador, como um terminal , um agente , uma configuração de CI/CD ou uma interface de usuário personalizada.
- Unity CLI: O cliente principal transforma comandos em chamadas de API ; uma interface de usuário personalizada também pode se comunicar diretamente pelo protocolo.
- Protocolo: HTTP + JSON e o contrato entre o cliente e a Unity
- Qualquer cliente capaz de fazer uma requisição HTTP pode controlar o Unity, em qualquer linguagem. Por padrão, o servidor se vincula ao localhost, portanto os clientes são executados na mesma máquina que o Editor; os chamadores remotos acessam o servidor por meio de qualquer caminho de rede que você expuser.
- Pacote Unity Pipeline : Instalado no projeto, inicia automaticamente com o Editor.
- O pacote Pipeline hospeda dois servidores: o servidor Editor (modo Play, status, recompilação, execução de testes, configuração do projeto) e o servidor Runtime (edições ao vivo em uma compilação em andamento por meio do Runtime Pipeline Manager).
Configuração
Passo 1: Instale a CLI do Unity
O Unity CLI é um binário independente (experimental). Instale-o usando o script ou através do Gerenciador de Pacotes e, em seguida, verifique. Para obter instruções completas, consulte a documentação da CLI do Unity .
# macOS / Linux — install script
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
# macOS / Linux — Homebrew (keeps it current)
brew install --cask unity-cli
# Windows — PowerShell install script
$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
unity --version # verify it's on your PATHEtapa 2: Iniciar sessão
Controlar um editor requer uma sessão autenticada:
unity auth login # opens a browser sign-in flow
unity auth status # confirm you're signed inEtapa 3: Adicione o pacote Unity Pipeline ao projeto.
O pacote Unity Pipeline é executado dentro do Editor e se conecta à CLI do Unity . Se você for instalar pelo terminal, certifique-se de estar na raiz do projeto Unity no qual deseja instalar. Execute o comando `unity pipeline install` , que por padrão terá como alvo o diretório atual ou o Editor em execução. Você também pode adicionar com.unity.pipeline através do Gerenciador de Pacotes. Consulte a documentação do pacote Unity Pipeline.
unity pipeline installApós a instalação, o Editor inicia o servidor automaticamente. Verifique o novo menu Pipeline para confirmar.
Passo 4: Conecte e liste os comandos.
Com o pacote instalado, conecte-se a um Editor em execução e liste o que pode ser programado:
unity command # list this project's commandsA lista inclui as funções integradas (modo de reprodução, status, recompilar, executar testes), além de quaisquer comandos personalizados. Eles funcionam com qualquer agente sem necessidade de configuração adicional.
Controle o editor a partir do terminal.
Entre no modo de jogo, execute testes, liste os alvos de compilação ou faça uma captura de tela.
unity command editor_play
unity command run_tests
unity command list_build_targets
unity command screenshotAs execuções são determinísticas, e o que foi mencionado acima representa apenas uma pequena parte; a lista do Unity mostra toda a superfície integrada (cenas, prefabs, materiais, animações, mapas de iluminação/NavMesh, builds, capturas de tela, pacotes e muito mais).
Comandos personalizados
Os comandos personalizados encadeiam uma série de ações em uma única chamada a partir da linha de comando. Um comando é uma função etiquetada no projeto. Exemplos:
- Executar testes + notificar: Execute o conjunto de testes e publique os resultados para a equipe em uma única chamada.
- Relatar ativos não utilizados: Analise o projeto e liste os ativos sem referências, para serem excluídos antes da compilação.
Um comando escrito é determinístico e repetível: mesma chamada, mesmo resultado, o que também facilita a sua transmissão a um agente.
Controle de tempo de execução
O servidor de tempo de execução controla uma compilação em andamento. Habilite-o adicionando um GameObject vazio, adicionando o componente Runtime Pipeline Manager e marcando a opção "Habilitar em compilações" . Com a compilação em andamento, a partir do terminal:
- Diminua a velocidade, pause ou reinicie o tempo.
- Altere valores dinamicamente e dimensione ou mova transformações para um GameObject em tempo de execução.
- Trocar ativos e efeitos em tempo de execução.
Para ações repetidas, escreva comandos de tempo de execução que sejam incluídos no jogo (ajustar valores de jogabilidade, substituir modos de jogo). É determinístico, repetível e pode ser invocado por um agente.
Agentes e avaliação
Todos os comandos estão disponíveis para qualquer agente através da CLI ou do seu modo MCP: comandos integrados, comandos personalizados e eval. Um agente possui duas marchas:
- Comandos nomeados determinísticos para etapas repetíveis
- eval para C# único quando ainda não existe um comando.
Um caso de uso possível seria um agente que utiliza `eval` para construir ou modificar algo, executa um comando determinístico para testá-lo, tira uma captura de tela e compara a imagem com o prompt, iterando até encontrar uma correspondência. `eval` é um código C# arbitrário com controle de acesso por token, portanto, limite o que o agente pode acessar.
Segurança
O pacote Unity CLI e Pipeline foi desenvolvido para desenvolvimento local, não para jogos publicados. Por padrão, tudo permanece em sua máquina; ele é executado apenas enquanto você está desenvolvendo, e a execução de código em tempo real (eval) é controlada por uma chave de acesso por projeto, portanto, um agente não pode executar código C# arbitrário em seu Editor sem ela. Entregar a linha de comando a um agente de IA é como dar acesso ao seu computador a qualquer assistente: ele pode fazer o que você pode, então decida o que você permite que ele acesse e limite o comando `eval` ao trabalho local.
Mais recursos