Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Guías de referencia de clases¶

Esta página explica cómo escribir la referencia de clases. Aprenderás dónde escribir nuevas descripciones para las clases, métodos y propiedades de los tipos de nodos incorporados en Godot.

Ver también

Para aprender a enviar tus cambios al proyecto Godot utilizando el sistema de control de versiones Git, consulta Contribuyendo a la referencia de la clase.

La referencia para cada clase se encuentra en un archivo XML como el que se muestra a continuación:

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

Comienza con descripciones breves y largas. En la documentación generada, la descripción breve siempre está en la parte superior de la página, mientras que la descripción larga se encuentra debajo de la lista de métodos, variables y constantes. Puedes encontrar métodos, variables miembro, constantes y señales en nodos XML separados.

Para cada uno de ellos, deseas aprender cómo funcionan en el código fuente de Godot. Luego, completa o mejora su documentación rellenando los textos en estas etiquetas:

<brief_description>
<description>
<constant>
<method> (en su etiqueta <description>; los tipos de retorno y los argumentos no requieren descripciones separadas)
<member>
<signal> (en su etiqueta <description>; los argumentos no requieren descripciones separadas)
<constant>

Escribe en un lenguaje claro y sencillo. Siempre sigue las pautas de escritura para mantener tus descripciones cortas y fáciles de leer. No dejes líneas vacías en las descripciones: cada línea en el archivo XML resultará en un nuevo párrafo, incluso si está vacía.

Cómo editar una clase XML¶

Edita el archivo de la clase que elijas en doc/classes/ para actualizar la referencia de la clase. La carpeta contiene un archivo XML para cada clase. El XML lista las constantes y métodos que encontrarás en la referencia de la clase. Godot genera y actualiza automáticamente el XML.

Nota

Para algunos módulos en el código fuente del motor, encontrarás los archivos XML en el directorio modules/<nombre_del_modulo>/doc_classes/.

Edítalo usando tu editor de texto favorito. Si utilizas un editor de código, asegúrate de que no cambie el estilo de sangría: debes usar tabulaciones para el XML y cuatro espacios dentro de bloques de estilo BBCode. Más detalles a continuación.

Para comprobar que las modificaciones que has realizado son correctas en la documentación generada, navega hasta la carpeta doc/ y ejecuta el comando make rst. Esto convertirá los archivos XML al formato de la documentación en línea y mostrará errores si algo está mal.

Como alternativa, puedes compilar Godot y abrir la página modificada en la referencia de código integrada. Para aprender cómo compilar el motor, lee la guía de compilación.

Recomendamos usar un editor de código que admita archivos XML como Vim, Atom, Visual Studio Code, Notepad++ u otro para editar cómodamente el archivo. También puedes utilizar su función de búsqueda para encontrar clases y propiedades rápidamente.

Truco

Si usas Visual Studio Code, puedes instalar la extensión vscode-xml para obtener linting para archivos XML de referencia de clases.

Mejore el formato con etiquetas de estilo BBCode¶

La referencia de clase XML de Godot admite etiquetas similares a BBCode para vincular y formatear texto y código. En las tablas siguientes encontrarás las etiquetas disponibles, ejemplos de uso y los resultados después de la conversión a reStructuredText.

Linking¶

Whenever you link to a member of another class, you need to specify the class name. For links to the same class, the class name is optional and can be omitted.

Tag and Description	Ejemplo	Resultado
`[Class]` Link to class	`Mueve el [Sprite2D].`	Move the Sprite2D.
`[annotation Class.name]` Link to annotation	`See [annotation @GDScript.@export].`	See @GDScript.@export.
`[constant Class.name]` Vínculo a constante	`See [constant @GlobalScope.KEY_F1].`	See @GlobalScope.KEY_F1.
`[enum Class.name]` Link to enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[method Class.name]` Link to method	`Llama a [method Node3D.hide].`	Call Node3D.hide().
`[member Class.name]` Vínculo a miembro	`Obtén [member Node2D.scale].`	Get Node2D.scale.
`[signal Class.name]` Link to signal	`Emite [signal Node.renamed].`	Emit Node.renamed.
`[theme_item Class.name]` Link to theme item	`See [theme_item Label.font].`	See Label.font.

Nota

Currently only @GDScript has annotations.

Formateando texto¶

Tag and Description	Ejemplo	Resultado
`[param name]` Formats a parameter name (as code)	`Takes [param size] for the size.`	Takes `size` for the size.
`[br]` Line break	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[b]` `[/b]` Negrita	`Un texto en [b]negrita[/b].`	Algo de texto en negrita.
`[i]` `[/i]` Cursiva	`Un texto en [i]itálica[/i].`	Algo de texto en cursiva.
`[kbd]` `[/kbd]` Atajo del teclado/ratón	`Una tecla [kbd]Ctrl + C[/kbd].`	Alguna tecla `Ctrl + C`.

Formateando código¶

Tag and Description	Ejemplo	Resultado
`[code]` `[/code]` Monospace	`Un texto [code]monoespaciado[/code].`	Algo de texto `monospace`.
`[codeblock]` `[/codeblock]` Bloque pre-formateado con múltiples líneas	Ver a continuación.	Ver a continuación.
`[codeblocks]` `[/codeblocks]` Codeblock para múltiples lenguajes	Ver a continuación.	Ver a continuación.
`[gdscript]` `[/gdscript]` Pestaña de bloque de código de GDScript en bloques de código	Ver a continuación.	Ver a continuación.
`[csharp]` `[/csharp]` Pestaña de bloque de código C# en bloques de código	Ver a continuación.	Ver a continuación.

Nota

[code] disables BBCode until the parser encounters [/code].
[codeblock] disables BBCode until the parser encounters [/codeblock].

Advertencia

Usa [codeblock] para bloques de código preformateados. Dentro de [codeblock], siempre utiliza cuatro espacios para la indentación. El analizador eliminará las tabulaciones.

Por ejemplo:

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

Se mostrará como:

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

Si necesitas tener diferentes versiones de código en GDScript y C#, usa [codeblocks] en su lugar. Si usas [codeblocks], también debes tener al menos una de las etiquetas específicas del lenguaje, como [gdscript] y [csharp].

¡Siempre escribe ejemplos de código en GDScript primero! Puedes utilizar esta herramienta experimental de traducción de código para acelerar tu flujo de trabajo.

[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]

Lo anterior se mostrará como:

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

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

Para denotar información importante, agrega un párrafo que comience con "[b]Nota:[/b]" al final de la descripción:

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

Para denotar información crucial que podría causar problemas de seguridad o pérdida de datos si no se sigue cuidadosamente, agrega un párrafo que comience con "[b]Advertencia:[/b]" al final de la descripción:

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

Para propiedades obsoletas, agrega un párrafo que comience con "[i]Obsoleto.[/i]". Observa el uso de cursiva en lugar de negrita:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

Claro, en todos los párrafos descritos anteriormente, asegúrate de que la puntuación forme parte de las etiquetas BBCode para mantener la consistencia.