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...

Script Editor

Introdução

O editor de scripts do Godot Engine é um editor de texto poderoso e totalmente integrado, que não apenas facilita o processo de escrever e depurar código em GDScript, como também permite trabalhar com arquivos de texto simples, oferecendo aos desenvolvedores um ambiente contínuo para programar a lógica e os comportamentos do jogo. Ele pode realçar seu código, identar automaticamente, realizar verificações de sintaxe e muito mais. Você também pode criar pontos de interrupção para depurar seu projeto sem precisar alternar para outra janela. O editor de texto também funciona como um visualizador offline da referência de classes, que pode ser acessado de várias maneiras, conforme descrito em Documentação integrada.

Features

Alguns dos principais recursos do editor de texto estão listados abaixo:

• Editor de código totalmente integrado para GDScript.

• Syntax highlighting support for GDScript and JSON files.

• Verificação de sintaxe para arquivos GDScript e JSON.

• Marcadores e suporte para pontos de interrupção.

• Indentação automática.

• Code folding.

• Tema personalizável.

• Múltiplos cursores, que podem ser ativados usando Alt + Clique com o Botão Esquerdo.

• Autocompletar de variáveis, funções, constantes, etc.

• Refatoração inline de símbolos ao selecioná-los e usar Ctrl + D.

• Busca e substituição em massa entre os arquivos do projeto.

Uso

Se você estiver usando GDScript em seu projeto, o editor de texto integrado do Godot fornece tudo o que você precisa, servindo como um ponto central para utilizar totalmente o Godot Engine. Praticamente todos os parâmetros que podem ser ajustados pela interface do usuário também podem ser modificados diretamente por meio de código.

Nota

Se você deseja usar um editor de texto externo ou prefere usar C# em seu projeto, veja Usando um editor de texto externo e Configurando um editor externo.

Dica

Assim como muitas partes da interface do Godot, o editor de texto também pode ser personalizado ajustando suas configurações conforme sua preferência. Você pode acessar essas configurações abrindo Editor > Configurações do Editor e indo até o grupo Editor de Texto.

Você pode abrir o Editor de Scripts usando o botão Script no seletor de áreas de trabalho, localizado na parte superior central da interface do Godot. Alternativamente, você pode usar o botão Abrir Script ao lado de um nó no painel da Árvore de Cena, ou dar um clique duplo em um arquivo .gd ou em um arquivo de texto reconhecido no painel Sistema de Arquivos para abri-lo diretamente no Editor de Scripts.

Depois de aberto, você verá os menus do editor de texto na parte superior, abaixo do seletor de cenas. Ao lado dos menus, você encontrará botões para abrir a documentação online ou pesquisar na referência de classes integrada. À direita desses botões, há duas setas de navegação que permitem percorrer seu histórico de visualização. Por fim, você pode usar o botão de flutuar para separar o editor de texto da janela do Godot, o que é útil se você estiver trabalhando com múltiplos monitores.

Logo abaixo dos menus, à esquerda, você verá o painel de scripts. No centro, ao lado do painel de scripts, está a área de codificação. Abaixo da área de codificação, está a barra de status, que exibe a quantidade de erros e avisos no código. Clicar nos ícones de erro ou aviso exibirá a lista de erros com os números das linhas. Clicar em um deles levará você diretamente para essa linha. Você também pode optar por ignorar avisos abrindo a lista e clicando em Ignorar. A barra de status também permite alterar o nível de zoom do código clicando no valor de porcentagem. Você também pode usar Ctrl + Roda do Mouse (Cmd + Roda do Mouse no Mac) para obter o mesmo efeito. A barra de status também mostra a posição atual do cursor em termos de linha e coluna, e se a indentação está sendo feita usando tabulações (tabs) ou espaços.

Muitas das ações realizadas no editor de texto também podem ser executadas usando atalhos. As ações exibem seus atalhos correspondentes ao lado delas. Para uma lista completa de atalhos, consulte atalhos do editor de texto.

Nas próximas seções, vamos explorar diferentes aspectos do editor de texto. Você também pode selecionar uma seção abaixo para ir diretamente a um tópico específico:

Script Panel

Abaixo dos menus, no painel à esquerda, você verá uma lista de arquivos abertos e páginas de documentação. Dependendo do tipo de arquivo, essa lista exibirá um ícone ao lado do nome do arquivo. Por exemplo, o ícone significa que é um GDScript. O ícone indica que é um script em C#. O ícone significa que é uma referência de classe embutida. Por fim, o ícone indica que é um script em execução no momento (Veja tool annotation para mais informações sobre isso). Ao passar o mouse sobre um arquivo, será exibida uma dica de ferramenta com sua localização relativa na pasta do projeto.

Na barra de status, clicar na seta para a esquerda oculta o painel de scripts, e clicar na seta para a direita o exibe.

Se você não alterou nenhuma configuração, os nomes dos arquivos podem ter uma coloração diferente. Isso ajuda a identificar os arquivos editados recentemente, destacando-os. Esse comportamento pode ser alterado em Editor > Configurações do Editor, ajustando as propriedades de Temperatura do Script na seção Editor de Texto.

A barra de filtro acima dos nomes dos arquivos oferece uma busca prática e sem diferenciação de maiúsculas/minúsculas para encontrar um arquivo específico. Mesmo que você apenas digite algumas letras do nome do arquivo na barra, os arquivos que contêm essas letras em ordem também aparecerão. Suponha que exista um arquivo chamado button.gd na lista. Se você digitar btn na barra de filtro, esse arquivo aparecerá nos resultados. Para redefinir o filtro, basta limpar o conteúdo da barra de filtro.

Um asterisco (*) ao lado do nome de um arquivo indica que o arquivo possui alterações não salvas.

Dica

Se você digitar apenas "*" na barra de filtro, todos os arquivos não salvos serão exibidos.

Você pode arrastar um arquivo para alterar a ordem de exibição. Clicar com o botão do meio em um arquivo o fecha. Clicar com o botão direito em um arquivo fornece várias opções para salvar ou fechar arquivos, ou para copiar o caminho relativo do arquivo. Nesse menu:

Você também pode usar Mover para Cima e Mover para Baixo para alterar a ordem do arquivo, ou usar Ordenar para organizar todos os arquivos em ordem alfabética. Alternar Painel de Scripts oculta o painel, que pode ser exibido novamente usando a seta para a direita na barra de status. Fechar Documentações fecha todos os documentos de referência abertos, deixando apenas os arquivos de script abertos. Mostrar no Sistema de Arquivos localiza e destaca o arquivo no painel Aba de arquivos.

Abaixo da lista de arquivos, você verá o nome do arquivo atualmente aberto. O botão ao lado permite alternar a ordenação dos métodos definidos nesse arquivo entre alfabética e a ordem em que aparecem. Logo abaixo, está o resumo do arquivo. Se for um arquivo de script, ele exibirá a lista de métodos definidos. Se, no entanto, uma página de referência de classe estiver aberta, essa área mostrará o índice desse documento. Clicar em um item dessa lista fará com que você seja direcionado para a função ou seção correspondente no arquivo. Da mesma forma, a barra Filtrar Métodos permite buscar uma função ou seção específica dentro do documento selecionado, com o mesmo comportamento do filtro de scripts.

Menus

Os menus do editor de texto estão localizados abaixo do seletor de cenas e permitem acessar uma variedade de ferramentas e opções, como gerenciamento de arquivos, busca e substituição, controles de depuração e recursos de formatação de código.

Dica

Um asterisco (*) ao lado de uma ação significa que esta operação também está disponível no menu de contexto, que pode ser aberto clicando com o botão direito do mouse no editor de código.

The File menu provides the following options:

• Novo Script...: Abre o diálogo de novo script para criar e adicionar o script ao projeto. Se a criação for bem-sucedida, ele será aberto diretamente no editor de texto. Dependendo da versão do Godot (com suporte a C# ou não), você pode escolher .gd ou .cs como extensão.

• Novo Arquivo de Texto...: Abre a caixa de diálogo de arquivo para criar um arquivo de texto simples com um dos formatos reconhecidos. O Godot também pode destacar arquivos json.

• Abrir...: Abre a caixa de diálogo de arquivo para permitir que você navegue dentro do seu computador e escolha qualquer arquivo de texto reconhecido para abri-lo.

• Reabrir script fechado: reabre os últimos scripts fechados. Você pode usar esta opção várias vezes para reabrir outros scripts fechados, caso tenha fechado mais de um.

• Abrir Recentes: Exibe uma lista dos últimos scripts abertos. Você também pode limpar a lista usando a opção fornecida na parte inferior.

• Salvar: Salva o script selecionado no momento.

• Salvar como...: Abre a caixa de diálogo de arquivo para salvar o script aberto no momento com um nome diferente.

• Salvar tudo: Salva todos os scripts abertos não salvos no editor de texto. Scripts com alterações não salvas terão um asterisco (*) ao lado de seus nomes na lista de scripts.

• Soft Reload Tool Script: Se o script selecionado for um tool, recarrega o script para executá-lo novamente.

• Copiar caminho do script: Copia o caminho relativo do script selecionado no projeto usando o prefixo res://.

• Mostrar no Sistema de arquivos: localiza e destaca o arquivo selecionado na aba do Sistema de arquivos.

• Histórico Anterior: Altera o script ativo para o que foi aberto anteriormente. Isso é útil quando você tem vários scripts abertos e deseja navegar rapidamente de volta para o último script editado. Se você também alterou a posição do cursor em mais de 10 linhas, primeiro o moverá para o local anterior no mesmo arquivo.

• Histórico Próximo: Após usar Histórico Anterior para retornar a um script anterior, este recurso permite avançar no histórico de scripts, alternando para scripts acessados anteriormente. Semelhante ao anterior, se você também alterou a posição do cursor em mais de 10 linhas, você o moverá primeiro para o próximo local no mesmo arquivo.

• Tema: Oferece opções para importar um tema existente, salvá-lo ou recarregá-lo. A alteração das configurações do tema é feita por meio das Configurações do Editor.

• Fechar: Fecha o script ativo.

• Fechar tudo: fecha todos os scripts abertos e solicita salvamento caso haja alterações não salvas.

• Fechar outras abas: fecha todos os scripts abertos, exceto o selecionado.

• Fechar documentos: fecha as páginas de documentação de referência da classe, deixando apenas os scripts.

• Executar: Se o script estende EditorScript e é destinado a ser executado sem rodar o projeto, esta opção executa o script. Veja Running one-off scripts using EditorScript para mais informações.

• Alternar Painel de Scripts: Mostra ou oculta o painel de scripts localizado no lado esquerdo do editor de texto, permitindo expandir a área de codificação disponível. Mais sobre o Painel de Scripts é explicado em above.

O menu Editar fornece várias opções para operações de linha:

• Desfazer*: Permite reverter a ação ou série de ações mais recente, restaurando o documento ou código ao seu estado anterior antes das alterações serem feitas.

• Refazer*: Permite que você reaplique uma ação que foi desfeita anteriormente, refazendo efetivamente a última ação, que foi revertida pela função Desfazer.

• Cortar*: Corta a seleção para a área de transferência.

• Copiar*: Copia a seleção para a área de transferência.

• Colar*: Cola o conteúdo da área de transferência se ele contiver texto.

• Select All*: Selects the all code in the text editor.

• Duplicar seleção: Copia a seleção e a anexa ao lado da seleção.

• Linhas Duplicadas: Duplica a linha atual e a adiciona como uma nova linha abaixo da linha atual.

• Avaliar Seleção: Calcula os valores do texto selecionado se ele contiver somente uma expressão matemática, como 83 * 3 ou pow(2,3).

• Alternar Quebra de Linha: Desativa a barra de rolagem horizontal, quebrando as linhas longas para a próxima linha. Observe que esta é apenas uma mudança visual e nenhuma nova quebra de linha foi adicionada.

• Linha: Fornece um conjunto de operações de linha. Dependendo do arquivo aberto, as opções também podem estar diretamente no menu Editar, em vez de um submenu.

  • Mover para cima: move a linha atual ou a(s) linha(s) selecionada(s) uma linha para cima.

  • Mover para baixo: move a linha atual ou a(s) linha(s) selecionada(s) uma linha para baixo.

  • Recuo*: recua o texto do cursor ou da(s) linha(s) selecionada(s), seguindo a configuração de recuo.

  • Desfazer recuo*: Desfaz o recuo do texto do cursor ou da(s) linha(s) selecionada(s), seguindo a configuração de recuo.

  • Excluir linha: Exclui a linha atual ou a(s) linha(s) selecionada(s).

  • Alternar Comentário*: Comenta e descomenta a linha atual ou a(s) linha(s) selecionada(s). Você pode executar a mesma ação selecionando a(s) linha(s) e escolhendo a mesma ação após clicar com o botão direito do mouse no texto selecionado.

• Dobra de Código (Folding): Fornece um conjunto de opções para dobrar o texto selecionado. Dependendo do arquivo aberto, as opções também podem estar diretamente no menu Editar, em vez de em um submenu.

  • Dobrar/Desdobrar Linha: Se o código na linha atual tiver um bloco de código ou uma região de código abaixo dele, essa opção oculta o bloco ao colapsar as linhas. Você pode desdobrá-lo usando essa opção novamente, clicando na seta ">" ao lado do número da linha na área de codificação ou no ícone de reticências "..." no final da linha dobrada.

  • Dobrar Todas as Linhas: Dobra todos os blocos de código ou regiões de código no documento aberto.

  • Desdobrar Todas as Linhas: Expande todos os blocos de código e regiões de código no documento aberto.

  • Criar Região de Código: Envolve o texto selecionado em uma região de código dobrável para melhorar a legibilidade de scripts maiores. Veja Tipos definidos por padrão para mais informações.

• Consulta de Autocompletar: Sugere símbolos internos ou criados pelo usuário para autocompletar o código parcialmente escrito. As setas Cima e Baixo navegam pela lista, pressionar Enter ou Tab aceita e adiciona o símbolo destacado ao código. O Tab também substituirá o texto existente à direita do cursor.

• Cortar espaços em branco à direita: remove o espaçamento extra no final de cada linha no arquivo.

• Aparar novas linhas finais: remove as novas linhas extras no final do arquivo.

• Recuo: Oferece opções para o recuo do arquivo aberto. Dependendo do arquivo aberto, as opções também podem estar diretamente no menu Editar, em vez de um submenu.

  • Converter recuo em espaços: converte todo o recuo no arquivo em espaços.

  • Converter recuo em tabulações: converte todo o recuo do arquivo em tabulações.

  • Recuo automático: Converte o recuo das linhas selecionadas (ou do arquivo inteiro) seguindo a configuração de recuo.

• Converter maiúsculas e minúsculas: altera a caixa do texto selecionado para Maiúsculas*, Minúsculas* ou coloca cada letra inicial das palavras em maiúscula.

• Marcador de sintaxe (Syntax Highlighter): Permite que você escolha o Marcador de sintaxe.

  • Texto simples: Desabilita o destaque.

  • Padrão: Destaque padrão para scripts C#.

  • JSON: Destaque de sintaxe para arquivos JSON.

  • GDScript: Destaque de sintaxe para arquivos GDScript.

The Search menu provides the following options:

• Buscar...: Abre a barra de busca rápida abaixo da barra de status para procurar texto no arquivo aberto. Você pode navegar para a próxima correspondência e para a anterior usando as setas para cima e para baixo, respectivamente. Marcar Diferenciar Maiúsculas/Minúsculas torna a busca sensível a maiúsculas e minúsculas. Marcar Palavras Inteiras significa que o texto não pode ter letras ou números ao lado dele, somente símbolos e espaços em branco.

• Localizar próximo: semelhante à seta para baixo, mostra a próxima ocorrência.

• Localizar anterior: Semelhante à seta para cima, mostra a ocorrência anterior.

• Substituir...: Abre a barra de busca e substituição abaixo da barra de status para encontrar texto e substituí-lo no arquivo aberto. Você pode escolher substituí-los uma vez por vez ou todos de uma vez. Além disso, é possível limitar a substituição ao texto selecionado marcando a caixa Somente Seleção na barra de busca e substituição. Você também pode usar Ctrl + D para selecionar adicionalmente a próxima instância do texto atualmente selecionado, permitindo que você faça uma substituição em linha em várias ocorrências.

• Localizar em Arquivos...: Abre uma janela para pesquisar texto nos arquivos da pasta do projeto. Selecionar "Localizar..." inicia com a pasta escolhida e inclui as extensões de arquivo verificadas nos filtros. Os resultados são exibidos no painel inferior, com o número de correspondências e o número total de arquivos encontrados, na aba Resultados da Pesquisa. Clicar em um resultado abre o arquivo e vai para a linha correspondente.

• Substituir em Arquivos...: Abre uma janela para pesquisar e substituir texto por texto diferente dentro dos arquivos encontrados na pasta do projeto. Após clicar em Substituir..., você pode selecionar em quais arquivos substituir usando a aba Resultados da Pesquisa no painel inferior, (des)marcando-os e clicando no botão Substituir Tudo.

Aviso

Observe que a operação "Substituir em arquivos" é irreversível!

Dica

As janelas Localizar em Arquivos e Substituir em Arquivos compartilham os botões Pesquisar... e Substituir.... A única diferença é que: na última janela (Substituir em Arquivos) tem um campo de texto adicional que preenche automaticamente o painel de resultados da pesquisa quando o botão Substituir... é clicado. A operação de substituição só é executada se você clicar no botão Substituir Tudo neste painel inferior, permitindo que você também edite a palavra a ser substituída posteriormente neste painel.

• Ajuda contextual*: Abre a lista de referências de classes integradas, semelhante a pressionar F1 em um símbolo ou escolher Procurar símbolo no menu de contexto.

O menu Ir para permite que você navegue pelo código facilmente com estas opções:

• Ir para a Função...: Abre a lista de funções para acessar. Você pode obter o mesmo resultado digitando na barra de métodos de filtro no painel de script.

• Ir para a linha...: Vai para o número da linha inserido no editor de código.

• Marcadores: Contém ações para a funcionalidade de marcadores, que você pode usar para navegar pelo código com mais facilidade, como uma seção incompleta. As linhas marcadas terão um símbolo de marcador azul à esquerda do número da linha.

  • Alternar marcador*: Adiciona ou remove o marcador na linha onde está o cursor. Você também pode clicar com o botão direito do mouse em uma linha para fazer isso.

  • Remover todos os marcadores: Remove todos os marcadores no documento aberto.

  • Ir para o próximo marcador: Vai para o próximo marcador no documento aberto.

  • Ir para o marcador anterior: Vai para o marcador anterior no documento aberto.

  • O menu Marcadores também conterá a lista de linhas marcadas, incluindo o número da linha e exibindo o conteúdo parcial daquela linha.

• Pontos de interrupção: Pontos de interrupção são úteis durante a depuração do seu código. Semelhante ao menu Marcadores, este menu permite adicionar ou remover pontos de interrupção, navegar entre eles e pular diretamente para um ponto de interrupção específico. Uma maneira fácil de adicionar um ponto de interrupção é passar o mouse sobre a área em branco à esquerda de um número de linha. Ele exibirá um círculo vermelho desbotado. Clicar nele adicionará um ponto de interrupção e o círculo permanecerá lá. Clicar em um círculo remove o ponto de interrupção.

O menu Depuração oferece ações que podem ser usadas durante a depuração. Veja Script editor debug tools and options para mais informações.

Coding area

Nota

Esta seção cobrirá apenas o básico da área de codificação em termos de interface do usuário. Para aprender mais sobre programação no Godot, consulte a documentação GDScript ou Scripting.

A área de codificação é onde você digitará seus scripts se estiver usando o editor de texto integrado. Ela oferece recursos de destaque e preenchimento automático para ajudar você durante a codificação.

A área de codificação mostra os números das linhas no lado esquerdo. Abaixo das setas de navegação, no lado direito, há um minimapa clicável que oferece uma visão geral de todo o script, permitindo que você navegue por ele.

Se uma linha de código for longa o suficiente (mais de 80 caracteres, por padrão), o editor de texto exibirá uma linha vertical que pode ser usada como uma diretriz suave. Para uma diretriz rígida, esse valor é definido para 100 caracteres, por padrão. Ambos os valores podem ser alterados, ou a exibição da linha pode ser alternada nas configurações de "Aparência" do editor de texto.

No script, à esquerda das definições de funções, você pode ver ícones adicionais. O ícone indica que essa função é uma override de uma função existente. Clicar nele abre a documentação da função original. O ícone significa que é um método receptor de um sinal. Clicar nele mostra de onde o sinal está vindo. O ícone à esquerda da linha indica um bloco dobrável. Você pode clicar para colapsá-lo ou expandi-lo. Alternativamente, o ícone de reticências (...) também pode ser clicado para expandir um bloco dobrado.

O exemplo abaixo resume o parágrafo acima. As linhas 52, 56 e 58 são blocos dobráveis, a linha 57 é uma região de código com o nome "Nova Região de Código", que também pode ser dobrada, e a linha 62 é um bloco dobrado. A linha 53 é um marcador, que pode ser acessado rapidamente usando o menu Ir para > Marcadores. A linha 55 é um ponto de interrupção que pode ser usado em depuração.

Muitas das cores do editor de texto, como as cores de destaque ou até mesmo as cores dos ícones de pontos de interrupção, ou marcadores, podem ser personalizadas. Você pode experimentá-las abrindo as configurações do editor de texto, navegando até a seção Editor > Configurações do Editor > Editor de Texto.