Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Tutorial de linha de comando

Alguns desenvolvedores gostam de usar a linha de comando extensivamente. Godot é projetado para funcionar com elas, então aqui estão os passos para trabalhar inteiramente a partir da linha de comando. Como a engine depende de quase nenhuma biblioteca externa, os tempos de inicialização são muito rápidos, o que o torna adequado para esse fluxo de trabalho.

Nota

No Windows e Linux, você pode rodar um binário do Godot em um terminal especificando o seu caminho absoluto ou relativo.

No macOS, o processo é diferente devido ao fato de o Godot estar contido dentro de um pacote .app (que é uma pasta, não um arquivo). Para executar um binário do Godot a partir de um terminal no macOS, você deve usar cd até a pasta onde o pacote da aplicação Godot está localizado e então executar Godot.app/Contents/MacOS/Godot seguido dos argumentos de linha de comando desejados. Se você renomeou o pacote da aplicação de Godot para outro nome, certifique-se de ajustar o comando adequadamente.

Referência para linha de comando

Legenda

• Disponível em compilações de editor, modelos de exportação de depuração e modelos de exportação de versão.

• Disponível apenas em compilações do editor e modelos de exportação de depuração.

• Disponível apenas em builds do editor e em modelos de exportação compilados com disable_path_overrides=false.

• Apenas disponível em compilações de editores.

Note que os argumentos de linha de comando desconhecidos não têm nenhum efeito. O motor não vai avisá-lo ao usar um argumento de linha de comando que não existe com um determinado tipo de compilação.

Opções gerais

Comando	Descrição
-h, --help	Exibe a lista de opções de linha de comando.
--version	Exibe a string de versão.
-v, --verbose	Usa o modo verboso para a saída padrão (stdout).
-q, --quiet	Modo silencioso, oculta as mensagens da saída padrão (stdout). Os erros ainda são exibidos.
--no-header	Não exibir a versão da engine e o cabeçalho do método de renderização ao iniciar.

Opções de execução

Comando	Descrição
--, ++	Separador para argumentos fornecidos pelo usuário. Os argumentos seguintes não são usados pelo motor, mas podem ser lidos através de OS.get_cmdline_user_args().
-e, --editor	Inicia o editor em vez de executar a cena.
-p, --project-manager	Inicie o Gerenciador de Projetos, mesmo que um projeto seja detectado automaticamente.
--recovery-mode	Start the editor in recovery mode, which disables features that can typically cause startup crashes, such as tool scripts, editor plugins, and GDExtension addons.
--debug-server <uri>	Inicia o servidor de depuração do editor (<protocol>://<host/IP>[:<port>], por exemplo, tcp://127.0.0.1:6007)
--dap-port <porta>	Usa a porta especificada para o Protocolo de Depuração do GDScript (Debug Adapter Protocol). Faixa de portas recomendada: [1024, 49151].
--lsp-port <porta>	Usa a porta especificada para o Protocolo de Servidor de Linguagem do GDScript (Language Server Protocol). Faixa de portas recomendada: [1024, 49151].
--quit	Sai após a primeira iteração.
--quit-after	Sai após o número de iterações especificado. Defina como 0 para desativar.
-l, --language <locale>	Usa uma localização (locale) específico. <locale> segue o formato language_Script_COUNTRY_VARIANT, onde "language" é um código de idioma de 2 ou 3 letras em minúsculas e o restante é opcional. Veja Códigos de localidade para mais detalhes.
--path <diretório>	Caminho para um projeto (o <directory> deve conter um arquivo "project.godot").
--scene <caminho>	Caminho ou UID de uma cena no projeto que deve ser iniciada.
--main-pack <arquivo>	Caminho para um arquivo de pacote (.pck) a ser carregado.
--render-thread <modo>	Modo da thread de renderização ("unsafe", "safe", "separate"). Consulte Modelo de Threads para mais detalhes.
--remote-fs <endereço>	Sistema de arquivos remoto (endereço <host/IP>[:<port>]).
--remote-fs-password <senha>	Senha para Arquivos remoto.
--audio-driver <driver>	Driver de áudio. Use --help primeiro para exibir a lista de drivers disponíveis.
--display-driver <driver>	Driver de tela (e driver de renderização). Use --help primeiro para exibir a lista de drivers disponíveis.
--audio-output-latency <ms>	Substitui a latência de saída de áudio em milissegundos (o padrão é 15 ms). Valores menores tornam a reprodução de som mais responsiva, mas aumentam o uso da CPU e podem resultar em estalos no áudio se a CPU não conseguir acompanhar.
--rendering-method <renderizador>	Nome do renderizador. Os valores válidos são forward_plus, mobile e gl_compatibility. Requer suporte do driver.
--rendering-driver <driver>	Driver de renderização (depende do driver de tela). Use --help primeiro para exibir a lista de drivers disponíveis.
--gpu-index <device_index>	Usar uma GPU específica (disponível apenas nos renderizadores Forward+/Mobile; execute com --verbose para obter a lista de dispositivos disponíveis).
--text-driver <driver>	Driver de texto (fontes, BiDi, modelagem).
--tablet-driver <driver>	Driver de entrada para mesa digitalizadora.
--headless	Habilita o modo headless (--display-driver headless --audio-driver Dummy). Útil para servidores e com --script.
--log-file	Escreve o log de saída/erro no caminho especificado em vez do local padrão definido pelo projeto. O caminho do <file> deve ser absoluto ou relativo ao diretório do projeto.
--write-movie <arquivo>	Execute a engine de forma que um filme seja gravado (geralmente com extensão .avi ou .png). --fixed-fps é forçado quando habilitado, mas pode ser usado para alterar o FPS do filme. --disable-vsync pode acelerar a gravação do filme, mas dificulta a interação. --quit-after pode ser usado para especificar o número de quadros a serem gravados.

Opções de exibição

Comando	Descrição
-f, --fullscreen	Solicita o modo tela cheia.
-m, --maximized	Solicita uma janela maximizada.
-w, --windowed	Solicita o modo em janela.
-t, --always-on-top	Solicita uma janela sempre no topo.
--resolution <largura>x<altura>	Solicita a resolução da janela.
--position <X>,<Y>	Solicita a posição da janela.
--screen <N>	Solicita a tela da janela.
--single-window (janela única)	Use uma única janela (sem subjanelas separadas).
--xr-mode <modo>	Seleciona o modo XR ("default", "off", "on").
--wid <window_id>	Solicita que seja associada a uma janela pai.
--accessibility <modo>	Select accessibility mode ["auto" (when screen reader is running, default), "always", "disabled"].

Opções de Depuração

Comando	Descrição
-d, --debug	Depuração (depurador local na saída padrão stdout).
-b, --breakpoints	Lista de pontos de interrupção (breakpoints) como pares fonte::linha separados por vírgula, sem espaços (use %20 em seu lugar).
--ignore-error-breaks	Se o depurador estiver conectado, impede o envio de breakpoints de erro.
--profiling	Habilita a criação de perfil (profiling) no depurador de script.
--gpu-profile (perfil da gpu)	Exibe um perfil de desempenho da GPU das tarefas que mais demoraram durante a renderização do quadro.
--gpu-validation (validação da gpu)	Habilita as camadas de validação da API gráfica validation layers para depuração.
--gpu-abort (interrupção da gpu)	Interromper a execução em caso de erros de GPU (geralmente erros de camadas de validação) pode ajudar a identificar o problema se o sistema travar.
--generate-spirv-debug-info	Gera informações de depuração SPIR-V. Isso permite a depuração de shaders em nível de código-fonte com o RenderDoc.
--extra-gpu-memory-tracking	Enables additional memory tracking (see RenderingDevice.get_driver_and_device_memory_report() and linked methods). Currently only implemented for Vulkan. Enabling this feature may cause crashes on some systems due to buggy drivers or bugs in the Vulkan Loader. See https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	Força barreiras entre breadcrumbs. Útil para identificar um comando que esteja causando reinicializações da GPU. Atualmente, isso só está implementado para Vulkan.
--remote-debug <uri>	Depuração remota (<protocol>://<host/IP>[:<port>], por exemplo tcp://127.0.0.1:6007).
--single-threaded-scene (cena única)	A árvore de cenas é executada em modo de thread única. Os grupos de subthreads são desabilitados e executados na thread principal.
--debug-collisions	Mostra os formatos de colisão ao executar a cena.
--debug-paths (depuração de caminhos)	Mostra as linhas de caminho ao executar a cena.
--debug-navigation	Mostra os polígonos de navegação ao executar a cena.
--debug-avoidance (depuração de evitação)	Mostra os visuais de depuração de desvio de navegação ao executar a cena.
--debug-stringnames (depuração de nomes de strings)	Imprime todas as alocações de StringName no stdout quando a engine é encerrada.
--debug-canvas-item-redraw	Exibe um retângulo sempre que um item de canvas solicita uma atualização (útil para diagnosticar o modo de baixo uso de processador).
--max-fps <fps>	Define um número máximo de quadros por segundo renderizados (pode ser usado para limitar o consumo de energia). Um valor de 0 resulta em taxa de quadros ilimitada.
--frame-delay <ms>	Simula alta carga de CPU (atrasa cada quadro em <ms> milissegundos). Não use como um limitador de FPS; use --max-fps em seu lugar.
--time-scale <escala>	Força a escala de tempo (valores mais altos são mais rápidos, 1.0 é a velocidade normal).
--disable-vsync (desabilitar sincronização vertical)	Força a desativação da sincronização vertical, mesmo se habilitada nas configurações do projeto. Não substitui a aplicação de V-Sync no nível do driver.
--disable-render-loop	Desativa o loop de renderização para que a renderização ocorra apenas quando chamada explicitamente a partir de um script.
--disable-crash-handler	Desativa o manipulador de travamentos (crash handler) quando houver suporte pelo código da plataforma.
--fixed-fps <fps>	Força um número fixo de quadros por segundo. Esta configuração desativa a sincronização em tempo real.
--delta-smoothing <enable>	Habilita ou desabilita a suavização do delta entre quadros ("enable", "disable").
--print-fps	Imprime os quadros por segundo na saída padrão (stdout).
--editor-pseudolocalization	Habilita a pseudolocalização para o editor e o gerenciador de projetos.

Ferramentas independentes

Comando	Descrição
-s, --script <script>	Executa um script. <script> deve ser um caminho de recurso relativo ao projeto (myscript.gd será interpretado como res://my_script.gd) ou um caminho absoluto no sistema de arquivos (por exemplo, no Windows: C:/tmp/my_script.gd).
--main-loop <nome_do_main_loop>	Executa um MainLoop especificado pelo seu nome de classe global.
--check-only	Apenas analisa em busca de erros e sai (use com --script).
--import	Inicia o editor, aguarda a importação de quaisquer recursos e, em seguida, encerra. Implica --editor e --quit.
--export-release <preset> <caminho>	Exporta o projeto em modo de lançamento (release) usando a predefinição e o caminho de saída fornecidos. O nome da predefinição deve corresponder a um definido em "export_presets.cfg". O <path> deve ser absoluto ou relativo ao diretório do projeto e incluir o nome do arquivo para o binário (ex: "builds/game.exe"). O diretório de destino deve existir.
--export-debug <preset> <caminho>	Semelhante ao --export-release, mas usa o template de depuração. Implica --import.
--export-pack <preset> <caminho>	Semelhante a --export-release, mas exporta apenas o pacote de jogo para a predefinição fornecida. A extensão no <path> determina se será no formato PCK ou ZIP. Implica --import.
--export-patch <preset> <caminho>	Exporta o pacote apenas com os arquivos alterados. Veja a descrição de --export-pack para outras considerações.
--patches <caminhos>	Lista de patches para usar com --export-patch. A lista é separada por vírgulas.
--install-android-build-template	Instala o modelo de build do Android. Usado em conjunto com --export-release ou --export-debug.
--convert-3to4 [<max_file_kb>] [<max_line_size>]	Converta o projeto de Godot 3.x para Godot 4.x.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	Mostrar que elementos serão renomeados ao converter o projeto de Godot 3.x para Godot 4.x.
--doctool [<caminho>]	Despeja a referência da API da engine no <path> fornecido em formato XML, mesclando se arquivos existentes forem encontrados.
--no-docbase	Impede a geração dos tipos base (usado com --doctool).
--gdextension-docs	Em vez de despejar a API da engine, gere a referência da API a partir de todas as GDExtensions carregadas no projeto atual (usado com --doctool).
--gdscript-docs <caminho>	Em vez de extrair a API da engine, gera a referência da API a partir da documentação interna nos arquivos GDScript encontrados em <path> (usado com --doctool).
--build-solutions	Compila as soluções de script (por exemplo, para projetos em C#). Implica --editor e requer um projeto válido para editar.
--dump-gdextension-interface	Gera o arquivo de cabeçalho GDExtension "gdextension_interface.h" na pasta atual. Este arquivo é a base necessária para implementar uma GDExtension.
--dump-gdextension-interface-json	Gera um despejo JSON da interface GDExtension chamado "gdextension_interface.json" na pasta atual.
--dump-extension-api	Gera um despejo JSON da API do Godot para bindings de GDExtension chamado "extension_api.json" na pasta atual.
--dump-extension-api-with-docs	Gera um despejo JSON da API do Godot como na opção anterior, mas incluindo documentação.
--validate-extension-api <caminho>	Valida um arquivo de API de extensão despejado (com a opção acima) de uma versão anterior da engine para garantir a compatibilidade da API. Se incompatibilidades ou erros forem detectados, o código de retorno será diferente de zero.
--benchmark	Benchmark the runtime and print it to console.
--benchmark-file <caminho>	Benchmark the runtime and save it to the given file path, in JSON format. <path> should be absolute.
--test [--help]	Executa os testes unitários (requer a compilação da engine com tests=yes). Use --test --help para mais informações.

Caminho

Recomenda-se colocar o binário do seu editor da Godot na sua variável de ambiente PATH, para que ele possa ser executado facilmente de qualquer lugar digitando godot. Você pode fazer isso no Linux colocando o binário da Godot em /usr/local/bin e garantindo que ele se chame godot (case-sensitive/diferenciando maiúsculas de minúsculas).

Para fazer isso facilmente no Windows ou macOS, você pode instalar o Godot usando Scoop (no Windows) ou Homebrew (no macOS). Isso tornará automaticamente a cópia do Godot instalada disponível no PATH:

WindowsmacOS

# Add "Extras" bucket
scoop bucket add extras

# Standard editor:
scoop install godot

# Editor with C# support (will be available as `godot-mono` in `PATH`):
scoop install godot-mono

Definindo o caminho do projeto

Dependendo de onde seu binário Godot está localizado e qual é seu diretório de trabalho atual, talvez seja necessário definir o caminho para o seu projeto para que qualquer um dos comandos a seguir funcione corretamente.

Ao executar o editor, isso pode ser feito fornecendo o caminho para o arquivo project.godot do seu projeto como primeiro argumento, desta forma:

godot path_to_your_project/project.godot [other] [commands] [and] [args]

Para todos os comandos, isso pode ser feito utilizando o argumento --path:

godot --path path_to_your_project [other] [commands] [and] [args]

Por exemplo, o comando completo para exportar seu jogo (conforme explicado abaixo) pode ser assim:

godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe

Ao iniciar a partir de um subdiretório do seu projeto, use o argumento --upwards para que o Godot encontre automaticamente o arquivo project.godot pesquisando recursivamente nos diretórios pais.

Por exemplo, executar uma cena (conforme explicado abaixo) aninhada em um subdiretório pode parecer assim quando seu diretório de trabalho estiver no mesmo caminho:

godot --upwards nested_scene.tscn

Criando um projeto

A criação de um projeto a partir da linha de comando pode ser feita navegando no shell até o local desejado e criando um arquivo project.godot.

mkdir newgame
cd newgame
touch project.godot

O projeto agora pode ser aberto com Godot.

Executando o editor

Executar o editor é feito iniciando o Godot com a flag -e. Isso deve ser feito dentro do diretório do projeto ou definindo o caminho do projeto conforme explicado acima; caso contrário, o comando será ignorado e o Gerenciador de Projetos será exibido.

godot -e

Ao passar o caminho completo para o arquivo project.godot, o sinalizador (flag) -e pode ser omitido.

Se uma cena foi criada e salva, ela pode ser editada posteriormente, executando o mesmo código com aquela cena como argumento.

godot -e scene.tscn

Apagando uma cena

O Godot é amigável com o seu sistema de arquivos e não cria arquivos extras de metadados. Use rm para apagar um arquivo de cena. Certifique-se de que nada faça referência a essa cena. Caso contrário, um erro será lançado ao abrir o projeto.

rm scene.tscn

Executando o jogo

Para executar o jogo, execute o Godot dentro do diretório do projeto ou utilizando o caminho do projeto conforme explicado acima.

godot

Observe que passar o arquivo project.godot sempre executará o editor em vez de executar o jogo.

Quando uma cena específica precisa ser testada, passe essa cena para a linha de comando.

godot scene.tscn

Depuração

Capturar erros pela linha de comando pode ser uma tarefa difícil, pois eles passam rapidamente pela tela. Para isso, existe um depurador de linha de comando disponível ao adicionar -d. Ele funciona tanto para executar o jogo quanto uma cena específica.

godot -d

godot -d scene.tscn

Exportando

A exportação do projeto pela linha de comando também é suportada. Isso é especialmente útil para ambientes de integração contínua.

Nota

O uso do argumento de linha de comando --headless é obrigatório em plataformas que não têm acesso à GPU (como integração contínua). Em plataformas com acesso à GPU, --headless impede que uma janela seja aberta durante a exportação do projeto.

# `godot` must be a Godot editor binary, not an export template.
# Also, export templates must be installed for the editor
# (or a valid custom export template must be defined in the export preset).
godot --headless --export-release "Linux/X11" /var/builds/project
godot --headless --export-release Android /var/builds/project.apk

O nome do preset deve corresponder ao nome de um preset de exportação definido no arquivo export_presets.cfg do projeto. Se o nome da predefinição contiver espaços ou caracteres especiais (como "Windows Desktop"), ele deve ser colocado entre aspas.

Para exportar uma versão de depuração do jogo, use a opção --export-debug em vez de --export-release. Seus parâmetros e uso são os mesmos.

Para exportar apenas um arquivo PCK, use a opção --export-pack seguida pelo nome da predefinição e o caminho de saída, com a extensão do arquivo, em vez de --export-release ou --export-debug. A extensão do caminho de saída determina o formato do pacote, seja PCK ou ZIP.

Aviso

Ao especificar um caminho relativo como o caminho para --export-release, --export-debug ou --export-pack, o caminho será relativo ao diretório que contém o arquivo project.godot, não relativo ao diretório de trabalho atual.

Executando um script

É possível executar um script .gd pela linha de comando. Esse recurso é especialmente útil em projetos grandes, por exemplo, para conversão em lote de recursos ou processos personalizados de importação/exportação.

O script deve herdar de SceneTree ou MainLoop.

Aqui está um exemplo de sayhello.gd mostrando como isso funciona:

#!/usr/bin/env -S godot -s
extends SceneTree

func _init():
    print("Hello!")
    quit()

E como executá-lo:

# Prints "Hello!" to standard output.
godot -s sayhello.gd

Se nenhum project.godot existir no caminho, o caminho atual é assumido como o diretório de trabalho atual (a menos que -path seja especificado).

O caminho do script será interpretado como um caminho de recurso relativo ao projeto, neste caso, res://sayhello.gd. Você também pode usar um caminho absoluto do sistema de arquivos, o que é útil se o script estiver localizado fora do diretório do projeto.

A primeira linha de sayhello.gd acima é comumente referida como shebang. Se o binário Godot estiver em seu PATH como godot, ele permite que você execute o script da seguinte forma em distribuições Linux modernas, bem como no macOS:

# Mark script as executable.
chmod +x sayhello.gd
# Prints "Hello!" to standard output.
./sayhello.gd

Se o acima não funcionar em sua versão atual do Linux ou macOS, você sempre pode fazer com que o shebang execute Godot diretamente de onde está localizado da seguinte maneira:

#!/usr/bin/godot -s