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

Introdução à referência de classe

Esta página explica como escrever a referência de classes. Você aprenderá onde escrever novas descrições para as classes, métodos e propriedades dos tipos de nós nativos do Godot.

Ver também

To aprender a enviar suas alterações para o projeto Godot usando o sistema de controle de versão Git, consulte a Documentação de contribuição da referência de classes.

A referência para cada classe está contida em um arquivo XML como o exemplo abaixo:

<class name="Node2D" inherits="CanvasItem" version="4.0">
    <brief_description>
        A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
    </brief_description>
    <description>
        A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
    </description>
    <tutorials>
        <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
        <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
    </tutorials>
    <methods>
        <method name="apply_scale">
            <return type="void">
            </return>
            <argument index="0" name="ratio" type="Vector2">
            </argument>
            <description>
                Multiplies the current scale by the [code]ratio[/code] vector.
            </description>
        </method>
        [...]
        <method name="translate">
            <return type="void">
            </return>
            <argument index="0" name="offset" type="Vector2">
            </argument>
            <description>
                Translates the node by the given [code]offset[/code] in local coordinates.
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
            Global position.
        </member>
        [...]
        <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
            Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
        </member>
    </members>
    <constants>
    </constants>
</class>

Ela começa com descrições breves e longas. Nos documentos gerados, a descrição breve fica sempre no topo da página, enquanto a descrição longa fica abaixo da lista de métodos, variáveis e constantes. Você pode encontrar métodos, variáveis de membro, constantes e sinais em nós XML separados.

Para cada um, você deve aprender como eles funcionam no código-fonte do Godot. Em seguida, preencha a documentação deles completando ou melhorando o texto nestas tags:

<brief_description>
<description>
<constant>
<method> (in its <description> tag; return types and arguments don't take separate documentation strings)
<member>
<signal> (in its <description> tag; arguments don't take separate documentation strings)
<constant>

Escreva em uma linguagem clara e simples. Siga sempre as diretrizes de escrita para manter suas descrições curtas e fáceis de ler. Não deixe linhas em branco nas descrições: cada linha no arquivo XML resultará em um novo parágrafo, mesmo que esteja vazia.

Como editar o XML da classe

Edite o arquivo da classe escolhida em doc/classes/ para atualizar a referência da classe. A pasta contém um arquivo XML para cada classe. O XML lista as constantes e os métodos que você encontrará na referência da classe. O Godot gera e atualiza o XML automaticamente.

Nota

Para alguns módulos no código-fonte da engine, você encontrará os arquivos XML no diretório modules/<module_name>/doc_classes/ em seu lugar.

Edit it using your favorite text editor. If you use a code editor, make sure that tabs are used for the indentation.

Para verificar se as modificações feitas estão corretas na documentação gerada, navegue até a pasta doc/ e execute o comando make rst. Isso converterá os arquivos XML para o formato da documentação online e exibirá erros se algo estiver errado.

Alternatively, you can build Godot and open the modified page in the built-in class reference. To learn how to compile the engine, read the compilation guide.

Recomendamos usar um editor de código que suporte arquivos XML, como Vim, Atom, Visual Studio Code, Notepad++ ou outro para editar confortavelmente o arquivo. Você também pode usar o recurso de busca deles para encontrar classes e propriedades rapidamente.

Dica

Se você usa o Visual Studio Code, pode instalar a extensão vscode-xml para obter linting para os arquivos XML de referência de classe.

Melhore a formatação com tags de estilo BBCode

A referência de classe XML do Godot suporta tags semelhantes ao BBCode para links, bem como para formatação de texto e código. Nas tabelas abaixo, você encontra as tags disponíveis, exemplos de uso e os resultados após a conversão para reStructuredText.

Vinculação

Sempre que você vincular a um membro de outra classe, precisará especificar o nome da classe. Para links para a mesma classe, o nome da classe é opcional e pode ser omitido.

Tag e Descrição	Exemplo	Resultado
`[Class]` Link para classe	`Mova o [Sprite2D].`	Mova o Sprite2D.
`[annotation Classe.nome]` Link para anotação	`Veja [annotation @GDScript.@rpc].`	Veja @GDScript.@rpc.
`[constant Classe.nome]` Link para constante	`Veja [constant Color.RED].`	Veja Color.RED.
`[enum Classe.nome]` Link para enum	`Veja [enum Mesh.ArrayType].`	Veja Mesh.ArrayType.
`[member Classe.nome]` Link para membro	`Obtenha [member Node2D.scale].`	Obtenha Node2D.scale.
`[method Class.name]` Link para método	`Chame [method Node3D.hide].`	Chame Node3D.hide().
`[constructor Class.name]` Link para construtor integrado	`Use [constructor Color.Color].`	Use Color.Color.
`[operator Class.name]` Link para operador integrado	`Use [operator Color.operator *].`	Use Color.operator *.
`[signal Classe.nome]` Link para sinal	`Emita [signal Node.renamed].`	Emita Node.renamed.
`[theme_item Classe.nome]` Link para item de tema	`Veja [theme_item Label.font].`	Veja Label.font.
`[param name]` Nome do parâmetro (como código)	`Recebe [param size] para o tamanho.`	Recebe `size` para o tamanho.

Nota

Atualmente, apenas o @GDScript possui anotações.

Formatando texto

Tag e Descrição	Exemplo	Resultado
`[br]` Quebra de linha	`Linha 1.[br]` `Linha 2.`	Linha 1. Linha 2.
`[lb]` `[rb]` `[` e `]` respectivamente	`[lb]b[rb]texto[lb]/b[rb]`	[b]texto[/b]
`[b]` `[/b]` Negrito	`Não[/b] chame este método.`	Não chame este método.
`[i]` `[/i]` Itálico	`Retorna a posição [i]global[/i].`	Retorna a posição global.
`[u]` `[/u]` Sublinhado	`[u]Sempre[/u] use este método.`	Always use this method.
`[s]` `[/s]` Tachado	`[s]Informação desatualizada.[/s]`	~~Outdated information.~~
`[url]` `[/url]` Hiperlink	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Website
`[center]` `[/center]` Centralização horizontal	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Atalho de teclado/mouse	`Pressione [kbd]Ctrl + C[/kbd].`	Pressione `Ctrl + C`.
`[code]` `[/code]` Fragmento de código inline	`Retorna [code]true[/code].`	Retorna `true`.

Nota

Algumas tags suportadas como [color] e [font] não estão listadas aqui porque não são recomendadas na documentação da engine.
[kbd] desativa o BBCode até que o analisador encontre [/kbd].
[code] desativa o BBCode até que o analisador encontre [/code].

Formatando blocos de código

Existem duas opções para formatar blocos de código:

Use [codeblock] se quiser adicionar um exemplo para uma linguagem específica.
Use [codeblocks], [gdscript] e [csharp] se quiser adicionar o mesmo exemplo para ambas as linguagens, GDScript e C#.

Por padrão, [codeblock] destaca a sintaxe do GDScript. Você pode alterá-la usando o atributo lang. As opções suportadas atualmente são:

[codeblock lang=text] desativa o destaque de sintaxe;
[codeblock lang=gdscript] destaca a sintaxe do GDScript;
[codeblock lang=csharp] destaca a sintaxe de C# (apenas na versão .NET).

Nota

[codeblock] desativa o BBCode até que o analisador encontre [/codeblock].

Por exemplo:

[codeblock]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/codeblock]

Será exibido como:

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

Se você precisar ter versões de código diferentes em GDScript e C#, use [codeblocks] em seu lugar. Se usar [codeblocks], você também precisa ter pelo menos uma das tags específicas da linguagem, [gdscript] e [csharp].

Sempre escreva os exemplos de código em GDScript primeiro! Você pode usar esta ferramenta experimental de tradução de código para acelerar seu fluxo de trabalho.

[codeblocks]
[gdscript]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/gdscript]
[csharp]
public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}
[/csharp]
[/codeblocks]

O exemplo acima será exibido como:

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}

Formatando notas e avisos

Para indicar informações importantes, adicione um parágrafo começando com "[b]Note:[/b]" (Nota) ao final da descrição:

[b]Note:[/b] Only available when using the Forward+ renderer.

Para indicar informações cruciais que podem causar problemas de segurança ou perda de dados se não forem seguidas com cuidado, adicione um parágrafo começando com "[b]Warning:[/b]" (Aviso) ao final da descrição:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

Em todos os parágrafos descritos acima, certifique-se de que a pontuação faça parte das tags BBCode para fins de consistência.

Marcando a API como obsoleta/experimental

Para marcar uma API como obsoleta (deprecated) ou experimental, você precisa adicionar o atributo XML correspondente. O valor do atributo deve ser uma mensagem explicando por que a API não é recomendada (marcação BBCode é suportada) ou uma string vazia (a mensagem padrão será usada). Se um elemento da API for marcado como obsoleto/experimental, ele será considerado documentado mesmo se a descrição estiver vazia.

<class name="Parallax2D" inherits="Node2D" experimental="This node is meant to replace [ParallaxBackground] and [ParallaxLayer]. The implementation may change in the future." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
    [...]
</class>

<constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard.">
    HTTP status code [code]305 Use Proxy[/code].
</constant>

<member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" deprecated="Use [member Node.auto_translate_mode] instead.">
    Toggles if any text should automatically change to its translated version depending on the current locale.
</member>

<method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
    <return type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
    <description>
        Returns the call mode used for "Call Method" tracks.
    </description>
</method>