A beginner’s guide to Unity CLI and the Pipeline package

Recentemente lançamos a CLI do Unity e o feedback tem sido extremamente positivo, com cada vez mais casos de uso inspiradores surgindo. No entanto, se você, como muitos outros, acha as ferramentas de linha de comando um pouco intimidantes, se sente mais como um designer do que como um programador, ou simplesmente ainda não teve tempo para experimentar, este guia foi feito para você.

O que é a CLI do Unity ?

Um dos maiores pontos fortes do Editor do Unity é a GUI), que facilita o gerenciamento visual de projetos complexos. Inspecionar um modelo pré-fabricado, ajustar valores de materiais, executar testes, simular a iluminação ou rastrear erros no console são ações que podem ser feitas com apenas alguns cliques do mouse no Editor. Esse fluxo de trabalho tem servido aos usuários por quase duas décadas, tornando-se o gargalo para tarefas repetitivas, automação e fluxos de trabalho orientados por IA (agentes). Um agente de IA consegue navegar por cliques e interfaces exclusivamente visuais, mas isso requer uma camada extra de interpretação visual, não nativa, que torna o processo mais lento e adiciona uma sobrecarga desnecessária, consumindo tokens rapidamente.

É aí que entram a nova CLI do Unity e o pacote experimental Unity Pipeline.

A CLI do Unity é, como o próprio nome sugere, uma interface de linha de comando para gerenciar o Unity. Por não possuir interface gráfica de usuário, é excepcionalmente adequado para automação e fluxos de trabalho orientados a agentes. Ele funciona como um binário (aplicativo) independente que inclui tudo o que precisa para ser executado, gerenciado e interagir com o Unity. Em outras palavras, você pode executar comandos a partir do terminal que se comunica diretamente com o Unity, substituindo a camada de cliques do mouse e fluxos de trabalho inteiros no Hub ou no Editor.

Observação: Novos recursos e melhorias são adicionados com frequência. No momento da redação deste documento, a versão 1.0.0-beta.6 do Unity CLI, combinada com a versão 0.5.0-exp.1 do pacote com.unity.pipeline e o Unity 6000.6.0b9, é a configuração mais atualizada. Se você encontrar algum problema, consulte a documentação da CLI do Unity : https://docs.unity.com/en-us/unity-cli/use-unity-cli

Como o Unity CLI e o pacote Pipeline funcionam juntos

Embora o binário independente do Unity CLI lide com a configuração do seu ambiente (como instalar editores, módulos e gerenciar licenças), o verdadeiro valor surge quando você o combina com o pacote Unity Pipeline ( com.unity.pipeline ).

Este pacote Unity Pipeline transforma essencialmente o seu Editor em execução num servidor HTTP local. Como o Editor permanece aberto em segundo plano, suas cenas carregadas e o banco de dados de recursos permanecem "ativos" na memória do sistema. Ao manter tudo pré-carregado, você evita completamente a frustrante sobrecarga de inicialização de ligar o motor a partir de um estado frio. Seu terminal (ou um agente de IA) agora pode controlar o Editor instantaneamente para executar testes, carregar cenas ou modificar GameObjects.

O sistema também lida com o notório gargalo de recarregamento de domínio. Antes do pacote Pipeline, sempre que você ou seu agente de IA faziam alterações diretas em um script C# no disco, era necessário esperar que o Unity recompilasse o projeto e recarregasse o domínio. Algumas ações exigiriam até mesmo que você focasse em algo ou clicasse em algo no Editor antes que pudessem prosseguir.

Mas o servidor local do pacote Pipeline lida com esse processo de compilação de forma completamente assíncrona. A conexão permanece estável e ativa durante toda a compilação, garantindo que sua sessão de terminal nunca seja interrompida ou expire enquanto o Editor recarrega em segundo plano.

As coisas ficam ainda mais rápidas quando você executa o código dinamicamente por meio do comando eval . Aqui, o pacote Pipeline no Editor funciona como um tradutor instantâneo, compilando seu trecho de código C# em tempo real e inserindo-o diretamente na thread principal do Unity. Como essa execução dinâmica é totalmente independente, ela ignora completamente o processo de recompilação e recarregamento de domínio em todo o projeto. Você pula completamente a espera tediosa e recebe seus resultados em milissegundos.

Isso significa que seus scripts de automação complexos não travarão nem perderão a conexão só porque uma compilação massiva de um projeto está acontecendo em segundo plano, enquanto seus comandos rápidos no terminal continuarão sendo executados com latência praticamente zero. Você obtém estabilidade e velocidade na mesma ferramenta.

Migrando do MCP para a CLI do Unity

Você pode estar se perguntando: "E quanto ao servidor oficial do Protocolo de Contexto de Modelo (MCP) da Unity ?" Por que eu não deveria simplesmente usar ou continuar usando isso?”

A resposta curta é que não vamos abandonar o suporte ao MCP. No entanto, o Unity CLI e o pacote Pipeline lidam com todos os mesmos casos de uso que o MCP e muito mais, mas fazem isso de forma muito melhor e mais rápida.

A resposta mais completa reside na arquitetura. As configurações tradicionais do MCP exigem um ambiente cliente ativo (como o Claude Desktop ou o Cursor) para atuar como um tradutor entre o seu agente de IA e o Unity. Mas agentes modernos, nativos de terminal, como o Claude Code, já são incrivelmente bons em executar comandos padrão do shell diretamente. Ao usar comandos de linha de comando diretos, como `unity command` ou `unity eval` , você elimina completamente a sobrecarga de configurar e manter um servidor MCP. Seu agente pode se comunicar diretamente com a Unity por meio de um servidor HTTP local unificado e ultrarrápido. Isso significa que você escreve configurações mais limpas, gasta menos tempo depurando sockets de conexão e pode deixar sua IA operar com a velocidade nativa do terminal.

Além disso, o servidor MCP legado era executado diretamente dentro do processo do Editor como um pacote C#. Isso significava que a própria ponte de conexão estava vinculada à thread principal e ao espaço de memória do Unity. Assim que você compilava o código ou acionava uma recarga de domínio, o Unity liberava sua memória, o que frequentemente fazia com que o socket de conexão caísse, lançasse exceções null ou travasse o agente no meio do loop.

O pacote com.unity.pipeline atual também é um pacote C# executado dentro do Editor, mas expõe um servidor HTTP e uma API REST (não uma ponte de socket), razão pela qual é mais resiliente a recarregamentos de domínio. Como esse servidor local processa comandos de forma assíncrona, sua conexão de terminal permanece completamente estável e ativa mesmo durante compilações complexas e recarregamentos de domínio.

Em resumo, ao migrar para a CLI do Unity , você evita completamente quedas de conexão e desperdício de tokens. Por fim, a CLI também oferece um modo MCP caso você tenha um caso de uso específico para o qual queira utilizar o MCP.

Instalando o pacote CLI e Pipeline

A instalação dos pacotes CLI e Pipeline é feita automaticamente com o Unity Hub nas versões mais recentes. No momento em que este texto foi escrito, existem várias maneiras de instalar o Unity CLI, portanto, certifique-se de consultar a documentação para obter a versão mais recente.

Se, por algum motivo, você ainda não o tiver instalado, a maneira mais simples é usar comandos do terminal para o processo de instalação. Você pode assistir ao vídeo ou seguir as instruções abaixo.

Para instalar a CLI do Unity , basta executar os seguintes comandos no seu terminal, dependendo da plataforma que você estiver usando:

# macOS ou Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

# Windows

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

O próximo passo é instalar o pacote Unity Pipeline:

instalação do pipeline do Unity

Após a instalação de ambos, você pode verificar se estão funcionando corretamente.

Verificando as instalações

Para confirmar a instalação, basta executar o seguinte comando:

status de unidade

Deverá retornar algo como isto:

Editor Unity (porta 7800): readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion: 6000.6.0b7PID: 85009

Se você vir o estado "pronto" ao lado da primeira linha, significa que o Editor está ativo e acessível. Também confirma em qual porta o Editor está instalado, o caminho do projeto, a versão do Editor e um identificador de processo (PID).

Em seguida, para garantir que seu acesso foi autenticado, execute o seguinte comando:

login de autenticação do Unity

Isso abrirá seu navegador para que você possa fazer login na sua conta Unity usando o método OAuth. Após a autenticação, a CLI armazena suas credenciais no chaveiro do sistema, para que comandos futuros que necessitem de autenticação (como `unity projects list`, `unity build`, `unity license`, `unity cloud` ) funcionem automaticamente, sem solicitar novamente.

Executando alguns comandos básicos

Com a CLI e o pacote Pipeline instalados, é hora de experimentar mais alguns comandos. Vamos começar com o comando `unity --help` , que oferece uma visão geral rápida de tudo o que você pode fazer.

unidade --ajuda

O comando `unity --help` fornece uma lista de todos os comandos básicos disponíveis, com uma visão geral e as opções disponíveis para cada um.

A princípio, a quantidade de opções pode parecer um pouco complexa, mas a sintaxe da CLI segue um padrão muito lógico e consistente.

Vamos usar um comando que acabamos de usar como exemplo, mas desta vez com uma opção:

login de autenticação do Unity --não interativo

Da esquerda para a direita:

• O comando `unity` ativa a CLI do Unity e, portanto, é o comando principal.
• auth login são os subcomandos. Você pode pensar neles como verbos que dizem ao programa principal exatamente qual ação tomar. Aqui, o parâmetro `auth` direciona a CLI para o sistema de autenticação, e o parâmetro `login` instrui o usuário a efetuar o login.
• --non-interactive é a opção. Considere as opções como semelhantes aos parâmetros. São modificadores que dizem ao comando como ele deve se comportar. Nesse caso, ele instrui a CLI a fazer login diretamente pelo terminal, em vez de abrir uma janela visual do navegador. As opções também são, por vezes, chamadas de "flags" quando usadas no contexto de opções de ativação/desativação.

Existe também um atalho de uma única letra, projetado para digitação rápida no seu fluxo de trabalho diário no terminal.

Voltando à nossa opção de ajuda ( --help ), em vez de executar `unity --help`, você também pode usar `unity -h` , que fornece a mesma resposta.

unidade --ajuda # Versão com flag longa (melhor legibilidade) unity -h # Versão com flag curta (mais rápida no dia a dia)

As opções abreviadas usam um único hífen (-) e são projetadas como um atalho, enquanto as opções longas usam dois hífens (--) e são as descrições completas equivalentes, projetadas para facilitar a leitura.

O comando --help é a ferramenta mais importante do seu conjunto de ferramentas; você pode adicioná-lo a praticamente qualquer nível de um comando aninhado para obter documentação rapidamente. Aqui estão alguns exemplos do comando de autenticação que acabamos de abordar:

# Ajuda para comandos de autenticação

autenticação do Unity --ajuda

# Ajuda específica para o comando de login

login de autenticação do Unity --ajuda

Cada tela de ajuda exibirá instantaneamente a descrição exata do comando, as opções disponíveis e os argumentos esperados. Na dúvida, basta perguntar ao próprio comando!

Vamos experimentar os comandos de releases como outro exemplo:

lançamentos da unidade

Isso me dá uma boa visão geral de todas as versões disponíveis para Unity no momento em que escrevo.

Agora vamos adicionar a opção --help :

lançamentos do Unity --ajuda

O comando `unity releases --help` fornece uma explicação de todas as opções que você pode adicionar para refinar sua busca por versões do Unity .

Por exemplo, no momento em que este texto foi escrito, estávamos usando a versão beta 6.6b7 do Unity e queríamos instalar a versão beta mais recente. Podemos usar o comando básico de instalação do Unity , que nos dará uma interface visual simples, onde podemos escolher a versão desejada.

instalação do Unity

Vamos escolher a versão b9, que iniciará a instalação em segundo plano (e levará alguns minutos para ser concluída).

Em vez de usar o assistente de instalação, você também pode usar o comando --help para obter uma visão geral de todos os comandos:

instalação do Unity --ajuda

Isso lhe dá uma visão geral semelhante a esta:

Pela lista, você pode ver que é possível passar a versão do Unity que deseja instalar como argumento. Isso significa que, se você quisesse instalar uma versão específica, poderia fazer isso com um único comando usando:

Basta substituir a versão pela que você deseja usar.

instalação do Unity 6000.5.9f1

Entretanto, nossa nova versão do Editor já foi instalada, então agora precisamos atualizar o projeto. Para isso, adicione a versão específica na qual deseja abrir o projeto. Isso seria o mesmo que entrar no Hub e escolher outra versão do Editor para abrir o projeto, acionando assim a atualização do projeto.

unity open --version 6000.6.0b9

Como mencionamos anteriormente, o pacote Pipeline abre um enorme conjunto de ferramentas que contém praticamente tudo o que você pode fazer dentro do Unity Editor (e com novos comandos sendo adicionados constantemente à medida que a versão beta amadurece).

Se você quiser ver quais comandos estão disponíveis no seu projeto atual, execute:

lista de unidade

Este comando fornece uma tabela de alto nível mostrando o nome, o grupo e uma breve descrição de cada comando. É uma ótima maneira de começar a navegar rapidamente pelas centenas de comandos integrados, como eval , add_animator_layer , build e find_assets .

Quando você precisa saber exatamente como formatar suas entradas. Você pode executar:

comando de unidade

Executar este comando sem argumentos fornece o "plano" detalhado dos comandos do Unity , com documentação para cada comando registrado, incluindo opções (os parâmetros e tipos de dados exatos que o comando espera).

Ambos os comandos interagem com o mesmo processo do Editor conectado, mas retornam diferentes níveis de detalhe. Ao começar a criar scripts de automação personalizados ou configurar fluxos de trabalho de agentes que controlam o Unity nos bastidores, o comando `unity command` se tornará rapidamente sua ferramenta de consulta mais utilizada para estruturar chamadas automatizadas e eficientes.

Por fim, vamos concluir examinando o comando `eval` e como executar um teste simples `Debug.Log ( "Hello World" )` dentro do console do Unity . `eval` é um comando do pacote Pipeline (e possivelmente o mais interessante entre os mais de 140 comandos integrados) que compila e executa código C# dinamicamente no processo do Editor. Tente executar o seguinte comando:

comando unity eval --code 'Debug.Log("olá do Unity CLI");'

Isso resulta no seguinte valor JSON , onde "success" é retornado como verdadeiro se a operação foi bem-sucedida.

No Editor, você pode agora verificar se isso realmente funcionou na janela do Console .

Vamos analisar o comando:

comando unity eval --code 'Debug.Log("olá do Unity CLI");'

Lendo da esquerda para a direita:

1. O Unity executa a ferramenta Unity CLI.
2. O comando é o subcomando que instrui o programa a "conversar com um Editor conectado".
3. O comando `eval` é um subcomando que significa "avalie (execute) algum código para mim".
4. --code é uma opção (ou sinalizador) que indica "aqui está o código a ser executado".
5. 'Debug.Log("hello from unity cli");' é o valor de --code ; o código real a ser executado.

Conectando o LLM

Familiarizar-se com alguns comandos básicos pode ajudar a agilizar a manutenção das suas instalações do Unity , mas o seu verdadeiro potencial surge quando você começa a automatizar e integrar seus fluxos de trabalho de agentes.

Com o Unity CLI e o pacote Pipeline, você pode conectar o agente de sua escolha. Isso significa que, independentemente de você usar Claude, Codex, Copilot ou modelos locais, etc., a CLI foi projetada para se integrar à sua configuração existente e preferida e deve se conectar sem exigir nenhuma configuração adicional.

Basta abrir um terminal, navegar (usando o comando cd) diretamente para o diretório do seu projeto Unity e iniciar o agente digitando “claude” (ou o comando do seu agente). Você pode confirmar sua conexão simplesmente perguntando ao agente algo como o seguinte:

Execute o comando "unity" em um terminal e me diga o que ele faz. Em seguida, teste um comando "eval" simples.

Conectando o LLM usando o MCP

A Unity descontinuou o servidor MCP integrado ao editor no pacote com.unity.ai.assistant . Ele foi substituído pelo servidor MCP integrado da CLI do Unity ( unity mcp ), que utiliza o pacote Unity Pipeline. Ele utiliza o mesmo protocolo, permitindo que os clientes se conectem sem problemas. O modo MCP continua sendo totalmente compatível com agentes que não conseguem executar comandos arbitrários do shell ou que têm dificuldades com a composição da linha de comando.

Para usar o MCP, execute o seguinte comando:

configurar unitm mcp

Este comando injeta automaticamente a configuração diretamente nas configurações do seu agente. Para testar se o seu LLM está conectado, execute um pequeno teste solicitando que sua ferramenta LLM execute algo semelhante ao seguinte:

Quero que você crie um cubo 2 × 2 × 2 no centro da cena que está aberta no momento. Em seguida, crie um script que faça com que ele gire continuamente em torno dos três eixos a 45 graus por segundo.

Eis a resposta de Claude Code:

Feito isso, o programa deverá entrar no modo Play e executar a cena para que você possa verificar se o cubo está girando corretamente.

Expanda com seus próprios comandos personalizados.

O conjunto de ferramentas integrado da CLI abrange todos os recursos básicos, como ativar/desativar o modo Play, recompilar e executar testes unitários. No entanto, o verdadeiro poder dessa arquitetura reside em sua extensibilidade. Você pode facilmente escrever comandos personalizados para fornecer aos seus agentes de IA um contexto específico para o projeto e ferramentas exclusivas criadas especialmente para o seu jogo.

Criar um comando personalizado é muito simples. Tudo o que você precisa fazer é escrever um método estático padrão em C# e decorá-lo com os atributos [CliCommand] e [CliArg] .

O pacote Pipeline descobre automaticamente esses atributos durante a compilação, o que significa que não requer nenhuma configuração manual ou arquivos de registro. Ao executar o comando `unity` sem argumentos, a CLI lista dinamicamente todos os comandos personalizados disponíveis, juntamente com os comandos integrados.

Observação: O atributo [CliCommand] torna os comandos detectáveis ​​e invocáveis ​​através da CLI. Para execução parametrizada, você chama o método diretamente usando o comando `eval` do Unity com sintaxe C#, em vez de passar parâmetros no estilo da CLI.

Vamos dar uma olhada rápida em um comando personalizado "Olá Mundo" em ação.

Crie um novo script C# chamado HelloWorldCommand.cs . Certifique-se de que a classe e o método sejam estáticos e incluam o namespace Unity :

using UnityEngine;

using Unity.Pipeline.Commands;

classe pública estática HelloWorldCommand

{

[CliCommand("hello-world", "Um comando simples 'Olá, mundo!'")]

public static void SayHello()

{

Debug.Log("Hello, World! Este é um comando CLI personalizado.");

}

}

Para executar o novo comando, abra o terminal e execute o seguinte comando:

comando unitário olá-mundo

O terminal deve ter uma aparência semelhante a esta.

E o seu registro no console deve ser semelhante a este:

Você também pode expandir o recurso se precisar passar parâmetros usando o atributo [CliArg] .

using UnityEngine;

using Unity.Pipeline.Commands;

classe pública estática HelloWorldCommand

{

[CliCommand("hello-world", "Um comando simples 'Olá, mundo!'")]

public static void SayHello(

[CliArg("nome", "Quem cumprimentar")] string nome)

{

Debug.Log($"Olá, {name}! Este é um comando CLI personalizado.");

}

}

Para executar o novo comando, abra o terminal e execute:

comando unity hello-world --name "thomas"

Instalando o plugin Unity Agent

A Unity também oferece um plugin oficial para desenvolvimento de jogos , que, no momento da redação deste texto, está disponível para Claude Code, Codex e Grok. Ele oferece habilidades selecionadas para desenvolvimento de jogos e otimização de desempenho. Após a instalação, as habilidades são carregadas automaticamente quando você trabalha em um projeto Unity em qualquer uma das opções acima. Para instalar no Claude, basta executar este comando:

Adicione o plugin Claude ao marketplace Unity-Technologies/unity-agent-plugin

github.com/Unity-Technologies/unity-agent-plugin

Outra dica rápida para usuários do Claude Code que estão iniciando um novo projeto é executar a fase de inicialização, que configura o Claude com o contexto básico do seu projeto, criando um arquivo claude.md . É um arquivo Markdown que fica na raiz da pasta do seu projeto e que o Claude Code lê no início de cada sessão.

/init # Execute este comando dentro do Claude Code

Dessa forma, você pode usá-lo para informar ao Claude sobre sua pilha de tecnologias preferida, como, por exemplo, se você prefere o uGUI em vez do UI Toolkit como interface de usuário, o Input System mais recente em vez do gerenciador de entrada mais antigo, etc. Também pode ser usado para decisões de arquitetura, como usar um padrão de localizador de serviços em vez de singletons, MVP para o design da interface do usuário, etc.

Embora Claude também crie memória automaticamente durante o funcionamento, salvando aprendizados entre sessões sem que você precise escrever nada, o arquivo Claude.md ajuda a orientar a direção geral do projeto específico.

À medida que avança no processo, você pode considerar adicionar instruções mais personalizadas, como um guia de estilo de código. Escrevi um artigo sobre como isso funciona para as instruções personalizadas no assistente de IA, mas os princípios são exatamente os mesmos para o Claude Code, caso você tenha interesse em saber mais.

Próximos passos

Esperamos que esta introdução tenha sido útil para você começar. Se você estiver interessado em otimizar ainda mais seu fluxo de trabalho agentivo, confira o artigo sobre como configurar instruções personalizadas para seu LLM, incluindo a definição de um guia de estilo de código Unity C# .

Confira o vídeo aqui:

Interface de linha de comando (CLI) do Unity