Esta página da Web foi automaticamente traduzida para sua conveniência. Não podemos garantir a precisão ou a confiabilidade do conteúdo traduzido. Se tiver dúvidas sobre a precisão do conteúdo traduzido, consulte a versão oficial em inglês da página da Web.
Em nosso último artigo, vimos como começar com o Unity CLI e o pacote Pipeline. Se você nunca tentou nenhum dos dois ou simplesmente precisa de uma revisão, confira aqui.
Neste artigo, queríamos compartilhar alguns comandos a mais que você pode adicionar à sua caixa de ferramentas de desenvolvedor. Com mais de 140 comandos, e mais sendo adicionados a cada atualização, você não precisa aprender todos eles. No entanto, memorizar alguns dos comandos essenciais e saber quais outras opções estão disponíveis o preparará para aproveitar melhor os fluxos de trabalho de desenvolvedor de IA. Sinta-se à vontade para folhear e selecionar aqueles que são novos e pular os que você já conhece. Vamos mergulhar.
Um rápido aviso antes de mergulharmos nos detalhes: novos recursos e melhorias estão sendo adicionados frequentemente. No momento da escrita, estou usando a versão 1.0.0-beta.10 do Unity CLI combinada com 0.6.0-exp.1 do pacote com.unity.pipeline e Unity 6000.6.0f1. Como tal, as coisas podem mudar no futuro e se você encontrar problemas, consulte a documentação do Unity CLI: https://docs.unity.com/en-us/unity-cli/use-unity-cli.
1. Use --help para qualquer comando
Você provavelmente já sabe e usou o comando unity --help. No entanto, --help pode ser anexado a qualquer nível de um comando aninhado para obter documentação instantânea. Na dúvida, simplesmente adicione --help no final.
Aqui estão alguns exemplos:
Você provavelmente já sabe e usou o comando unity --help. No entanto, --help pode ser anexado a qualquer nível de um comando aninhado para obter documentação instantânea. Na dúvida, simplesmente adicione --help no final.
Aqui estão alguns exemplos:# Documentação para obter todos os editores disponíveis
editores unity --help
# Obter parâmetros para instalar um módulo específico
unity install-modules --help
# Ajuda para comandos de Authentication
unity auth --help
# Ajuda para o comando de login especificamente
unity auth login --help
Cada tela de ajuda exibirá instantaneamente exatamente o que o comando faz, quais opções estão disponíveis e quais argumentos ele espera.
A flag --help é também o que os agentes usam para explorar a ferramenta, então ao iniciar uma nova sessão com sua CLI, você pode pedir ao seu agente para executar --help para garantir que ele está conectado.
2. Liste os comandos
Falando em documentação e em encontrar seu caminho entre as muitas opções disponíveis, também há este comando (quando executado sem argumentos):
comando unity
Este comando se conecta a um Unity Editor em execução através do servidor local do pacote Pipeline e fornece uma lista de cada comando registrado que a API do Editor expõe ao shell e o agente pode usar para trabalhar dentro do Unity.
Um exemplo de uma maneira de usar comandos poderia ser:comando unity editor_play
Para fazer o Editor conectado entrar no Modo Play (nosso equivalente CLI de clicar no botão Play) para que seus scripts comecem a rodar sem que você precise tocar na UI do Editor. Da mesma forma, o correspondente é:unity command editor_stop
Para garantir que seu agente esteja ciente do que o CLI pode fazer (e porque às vezes parece uma caixa preta), uma dica que você pode usar ao iniciar um novo prompt é ser mais exploratório e dar ao Claude, Codex etc. contexto sobre o que o CLI pode fazer. Você pode fazer isso executando um comando como:Execute "unity command" em um bash e me diga o que ele pode fazer, e teste um comando "eval" simples
3. Verificando status e executando múltiplas instâncias
Se você precisar verificar se o Unity CLI está em execução, pode simplesmente usar o comando:status da Unity
Deve retornar algo como isto:Editor Unity (porta 7800): readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersão: 6000.6.0d1PID: 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á, o caminho do Projeto, a Versão do Editor e um identificador de processo (PID).
unity status já lista todos os Editores conectados, então responde "quais estão rodando?" por si só. Quando você precisa saber especificamente quais desses projetos têm o pacote Pipeline instalado e acessível, use:# pipeline
lista de pipeline Unity
Que mostra todos os projetos Unity que o CLI conhece que têm o pacote Pipeline em execução, listando cada projeto ao lado de sua porta do servidor e se está atualmente acessível.
Quando vários editores estão rodando como no exemplo acima, você pode direcionar um passando --project-path com o caminho do projeto dele. Caso contrário, a CLI seleciona o Editor cujo projeto contém o diretório atual.
4. Bandeiras curtas e longas
A maioria dos comandos também oferece um atalho de uma letra projetado para digitação rápida no seu fluxo de trabalho diário no terminal. Então, em vez de executar unity --help, você também pode usar apenas unity -h, ambos dando-lhe a mesma resposta, mas economizando alguns toques de tecla.unity --help # Versão de flag longa (melhor legibilidade)
unity -h # Versão de flag curta (mais rápido no dia a dia)
5. Verifique o tamanho do seu projeto
Se você está procurando liberar espaço, este comando pode ajudar você a identificar rapidamente o tamanho dos seus projetos Unity:
Pegada de disco por pasta para um projeto, para que você possa ver quanto é regenerável (Biblioteca/Temp)
tamanhos dos projetos da unity
# Resuma cada projeto registrado, ordenado por tamanho
tamanho dos projetos Unity --all
6. Controle o formato da saída
Por padrão, os comandos retornam texto legível por humanos, mas você pode mudar o formato para JSON quando um script precisa de JSON aninhado limpo para analisar. Padrão para saída legível por humanos quando seu agente estiver lendo um resultado pequeno e simples diretamente e não precisará analisá-lo programaticamente, mude para --format json assim que a resposta tiver estrutura ou tamanho que de outra forma exigiria adivinhação de regex contra um formato que não é garantido permanecer estável.
# Machine-readable JSON
lista de editores unity --format json
Formato amigável para humanos
lista de editores unity --format human
7. Visualizar a instalação do módulo sem baixar
Antes de se comprometer com o download e o espaço em disco que os módulos grandes ocupam, você pode usar --dry-run, que mostrará exatamente quais módulos seriam instalados e seu tamanho combinado, sem baixar nada.
unity install-modules --module android ios --dry-run
Fazer um ensaio geral fornece uma boa visão geral de como o projeto completo será.
8. Inspecione a configuração de uma compilação antes de se comprometer com o tempo de compilação
Não há --dry-run para builds, mas você ainda pode validar o formato de um antes de pagar por uma compilação. unity build requer ou --target ou --profile, e várias flags saem antes que qualquer construção aconteça, capturando um alvo errado ou um perfil de build ausente em segundos em vez de minutos.
# Teste sua compilação antes de executá-la
unity build --list-targets
# Listar perfis
unity build --list-profiles
9. Instalar uma versão específica do Editor com todos os módulos de uma vez
Para ambientes de CI onde a reprodutibilidade é importante, você pode instalar uma versão exata do Editor sem o Hub. A versão é um argumento posicional, --cm puxa módulos filhos automaticamente, e os módulos de plataforma nomeados vêm do comando separado install-modules.
# A versão é posicional, não uma flag --version
unity install 6000.6.0f1
# Incluir módulos filhos automaticamente
unity install 6000.6.0f1 --cm
# Adicionar módulos da plataforma (comando separado, suporta --dry-run)
unity install-modules --module android ios webgl
10. Processo de instalação e atualização do editor a partir do terminal
Em vez de usar o Hub para administrar seu processo de instalação, use o comando básico unity install, que fornecerá uma lista de todas as versões do Editor disponíveis, que você pode então instalar sem abrir o Hub.
Guia de instalação interativo
instalar unity
Depois de instalar as novas versões, você pode atualizar o projeto usando o comando upgrade especificando o caminho da pasta do seu projeto e a versão para a qual deseja atualizar:# Substitua o caminho do projeto e a versão do editor conforme necessário para o seu projeto
unity projects upgrade /Users/thomaskr/Github/UnityProjects/CLIDemo --to 6000.6.0f1
Na captura de tela acima você pode ver como a atualização foi feita em um simples comando de linha.
11. Criar um projeto a partir do terminal
Você pode criar novos projetos via CLI com apenas alguns comandos:
#O modelo interativo padrão
unity projects create "CLI demo"
Executar o modo padrão fornece um assistente interativo que o guia pelo processo. Basta escolher a versão do editor que você deseja usar, vincular ao Unity Cloud e escolher modelos e versões do Editor durante a criação, tornando muito fácil configurar um novo projeto de forma semelhante ao que você faria no Hub.
No entanto, ao contrário do Hub, você também pode automatizar suas configurações, caso tenha um fluxo de trabalho de configuração frequente, simplesmente definindo as opções como você deseja. Aqui está um exemplo onde você define uma versão específica do editor, modelo e caminho do projeto.
Com modelo (3D, 2D, VR, etc. - simplesmente substitua os espaços reservados)
unity projects new "CLI demo" --editor-version 6000.6.0b9 --template com.unity.template.3d --path ~/MyProjects
12. Capturar capturas de tela
Se você precisar capturar capturas de tela em seus fluxos de trabalho, você tem três comandos diferentes disponíveis.
# Captura a cena ou a visualização do jogo em um arquivo PNG, retorna o caminho. Params: --view, --output, --width, --height
Visão do jogo
# Nota: A UI de sobreposição de espaço de tela NÃO está na saída de uma câmera, então retorna preto
captura de tela do comando unity --view game
Visão de cena
captura de tela do comando unity ---visualizar cena
# Capturar em uma resolução e câmera específicas, obter base64 de volta inline
# Lê o backbuffer composto, então a UI de sobreposição é incluída. Modo de Jogo apenas.
unity command capture_game_view --width 1920 --height 1080 --camera "Main Camera" --save_path Screenshots/check.png
A saída será algo como isto:
Isso pode ser útil para o ciclo de verificação "implementar isso, tirar uma captura de tela, comparar com o design" das próprias diretrizes de melhores práticas do Claude Code, já que a imagem retorna como dados que o agente pode raciocinar imediatamente, em vez de um caminho que ele depois tem que abrir separadamente.
13. Changelog
Como novos recursos estão sendo adicionados rapidamente ao Unity CLI e ao pacote Pipeline, um comando útil que gosto de usar é o changelog, que você pode obter simplesmente executando:
unity changelog
Resume as mudanças recentes dando-lhe uma visão geral rápida do que observar e talvez novos comandos para experimentar.
14. Executar C# com Eval
Quando o pacote Unity Pipeline está rodando dentro do seu Editor, o CLI pode compilar e executar snippets C# ao vivo no Editor usando o comando eval. Como não há recompilação em nível de projeto e nem recarregamento de domínio, ele executa em milissegundos em vez de fazer você esperar. Você pode usar isso para executar scripts de configuração automatizados, consultar estados do editor ou até mesmo executar arquivos de script C# do seu disco usando unity command eval_file --file path/to/script.cs.
# Retorna verdadeiro se o Editor estiver atualmente no Modo de Jogo
unity command eval --code "return UnityEditor.EditorApplication.isPlaying;"
# Registre uma string simples na janela do console
unity command eval --code 'Debug.Log("Eu fui invocado no terminal");'
15. Teste
A ferramenta de teste da Unity, também chamada de Unity Test Framework, pode ser executada diretamente da CLI.
Unity divide os testes em duas categorias, e a diferença é muito importante uma vez que um agente os executa repetidamente:
- Testes de Modo de Edição: executam instantaneamente, sem pressionar Play. Bom para testar lógica simples (matemática, manipulação de dados, classes não-MonoBehaviour).
- Testes de Modo de Jogo: realmente jogue seu jogo brevemente, da maneira que um jogador experimentaria. Mais lento, porque a Unity tem que recarregar coisas nos bastidores.
Você provavelmente quer começar com os testes do Modo de Edição. Eles são mais rápidos, mais simples de escrever e cobrem a maior parte do que você precisa no início. Assim que você tiver o Test Framework e o Unity CLI instalados, você pode invocá-lo a partir da linha de comando:
# Execute os testes do Modo de Edição do projeto
unity test --mode EditMode
# Filtrar para um subconjunto e escrever um relatório JUnit
unity test --mode EditMode --filter MyNamespace.MyTests --junit-output results.xml
# Executar apenas testes afetados por mudanças recentes
unity test --affected
Isto executa em todos os testes do Modo de Edição. Adicione --junit-output results.xml e você também obtém um relatório estruturado do que passou e falhou. Então peça ao seu agente para executar os testes e resumir o que ele encontra, algo como: "Execute os testes do Modo de Edição e me diga apenas o que está falhando, em inglês simples." O agente executa o comando, lê o relatório e relata, sem mais necessidade de rolagem manual de logs.
16. Gerencie sua nuvem
Embora o sign-in management esteja sob unity auth, você pode usar unity cloud para gerenciar sua organização e projetos do Unity Cloud a partir do terminal.
# Abre uma lista de todos os comandos de nuvem disponíveis
Unity Cloud
# Para obter o ID da sua organização e conta
status do Unity Cloud
# Apenas o id da organização ativa, pronto para pipe
org atual do Unity Cloud
17. Verifique o médico
Ao solucionar problemas ou verificar seu ambiente, você pode usar o comando unity doctor em vez de auditar manualmente a Authentication, instalações e arquivos de log. O comando executa uma verificação de saúde abrangente da sua configuração, incluindo editores disponíveis, configurações de proxy e logs de atividade recentes em uma única saída. É particularmente útil para diagnosticar erros de configuração silenciosos em máquinas de CI durante a configuração inicial.
# Diagnostique sua configuração
doutor unity
# Adiciona rastreamentos de pilha de erro completos
unity doctor --verbose
Como a má configuração de proxy silencioso é um culpado comum de falhas de compilação, você pode considerar verificar a saúde do Editor antes de executar as compilações. Você pode simplesmente automatizar isso para rodar em máquinas de CI durante a configuração.
Você também pode usar o comando unity env. É um subconjunto de unity doctor que você gostaria quando precisa apenas de um caminho, por exemplo, para limpar o cache de download ou para inspecionar manualmente o user-settings.json.
caminhos resolvidos (caminho de instalação, caminho de cache, caminho de configuração)
ambiente unity
18. Criando comandos personalizados
O atributo [CliCommand] facilita a escrita de comandos personalizados para fornecer aos seus agentes de IA scripts personalizados. Para usar o comando CLI, você só precisa de um método C# estático padrão e decorá-lo com os atributos [CliCommand] e [CliArg].
O pacote Pipeline descobre automaticamente esses atributos durante a compilação, o que significa que nenhum arquivo de configuração ou registro manual é necessário. Quando você executa unity command sem argumentos, a CLI lista dinamicamente todos os comandos personalizados disponíveis juntamente com os comandos embutidos.
Observação: O atributo [CliCommand] torna os comandos descobertos e invocáveis via CLI. Para execução parametrizada, você chama o método diretamente usando unity command eval com sintaxe C#, em vez de passar flags no estilo CLI.
Vamos ver um comando personalizado rápido de "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 inclua o namespace Unity.Pipeline.Commands:
using UnityEngine;
using Unity.Pipeline.Commands;
public static class HelloWorldCommand
{
[CliCommand("hello-cli", "Um teste de olá mundo")]
public static void SayHello()
{
Debug.Log("Olá pessoal! Sou um comando CLI personalizado.";
}
}
Para executar seu novo comando, inicie seu terminal e execute:
comando unity hello-cli
Ao executá-lo, ele imprime o resultado do comando no seu terminal, e a saída Debug.Log aparece na janela Console do Editor.
Se você quiser saber mais sobre como criar comandos personalizados, abordaremos isso em um artigo futuro.
19. Usando servidor MCP
Embora usar a CLI seja geralmente o fluxo de trabalho recomendado, a CLI do Unity também pode operar como um servidor MCP, se você quiser integração de ferramentas nativa ou se seu agente tiver dificuldades com comandos de shell.
O MCP simplifica a integração ao dar aos agentes acesso direto aos nomes das ferramentas, descrições e esquemas estruturados através de uma conexão persistente, evitando a execução de shell bruta e a análise de saída. Enquanto o CLI se adapta a scripts e fluxos de trabalho manuais, o MCP incorpora perfeitamente as ferramentas Unity em fluxos de trabalho de IA. Ambos alcançam as mesmas capacidades de Editor, sem diferença de desempenho significativa.
Clientes de IA geralmente iniciam o servidor MCP automaticamente. Embora o servidor funcione de forma independente, as ferramentas do Editor exigem um Editor ativo com o pacote Pipeline. Pense no MCP como uma interface alternativa se suas ferramentas estiverem com problemas por algum motivo. Na maioria dos casos de uso, o Unity CLI será a melhor opção.
Configure seu cliente de IA com:
# Veja quais agentes são suportados
unity mcp configure --list
# Adicionar o servidor ao Claude Code
unity mcp configure claude-code
# Ou para Cursor, escopado apenas para o projeto atual
unity mcp configure cursor --local
Visualizar a alteração da configuração sem escrevê-la
unity mcp configure vscode --dry-run
20. Agente Unity para CLI
A Unity envia uma habilidade de agente para a CLI. Isso pode ajudar seu agente a saber quais comandos existem e como chamá-los. A CLI pode instalá-lo para você:
# Imprimir as habilidades disponíveis sem instalá-las
habilidade unity
# Liste os arquivos dos quais a habilidade é feita
unity skill show --list
# Mostrar clientes suportados e status de instalação
unity skill install --list
# Instale-o no seu cliente de IA
instalar habilidade unity claude-code
Atualizar para a versão mais recente
atualização de habilidade unity
E agora?
Espero que este tenha sido um resumo rápido útil dos comandos. Como mencionei, você não precisa memorizar tudo, mas saber alguns comandos básicos pode ser muito útil. Em nosso próximo artigo, analisaremos mais de perto o trabalho com Claude Code e Unity. Feliz codificação de jogos!