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

Principio di riferimento classi

Questa pagina spiega come scrivere il riferimento alle classi. Descrive dove scrivere nuove descrizioni per classi, metodi e proprietà per i tipi di nodo predefiniti di Godot.

Vedi anche

Per imparare a inviare le modifiche al progetto Godot attraverso il sistema di controllo versioni Git, consultare <https://contributing.godotengine.org/en/latest/documentation/class_reference.html>`__.

Il riferimento per ogni classe è contenuto in un file XML come quello seguente:

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

Comincia con descrizioni brevi e lunghe. Nei documenti generati, la descrizione breve si trova sempre in cima alla pagina, mentre la descrizione lunga si trova sotto l'elenco di metodi, variabili e costanti. Metodi, variabili membro, costanti e segnali si trovano in nodi XML separati.

For each, you want to learn how they work in Godot's source code. Then, fill their documentation by completing or improving the text in these tags:

<brief_description>
<description>
<constant>
<method> (nel suo tag <description>; i tipi restituiti e gli argomenti non richiedono stringhe di documentazione separate)
<member>
<signal> (nel suo tag <description>; gli argomenti non richiedono stringhe di documentazione separate)
<constant>

Scrivere in un linguaggio chiaro e semplice. Seguire sempre le linee guida di scrittura per rendere le descrizioni brevi e facili da leggere. Non lasciare righe vuote nelle descrizioni: ogni riga nel file XML risulterà in un nuovo paragrafo, anche se è vuota.

Come modificare un XML di classe

Modificare il file della classe scelta in doc/classes/ per aggiornare il riferimento alla classe. La cartella contiene un file XML per ogni classe. Il file XML elenca le costanti e i metodi presenti nel riferimento alla classe. Godot genera e aggiorna automaticamente il file XML.

Nota

Per alcuni moduli nel codice sorgente del motore, i file XML sono situati invece nella cartella modules/<nome_modulo>/doc_classes/.

Modificalo tramite un editor di testo a piacere. Se si usa un editor di codice, assicurarsi che non modifichi lo stile di indentazione: si dovrebbero utilizzare le tabulazioni per l'XML e quattro spazi all'interno dei blocchi in stile BBCode. Maggiori informazioni di seguito.

Per verificare che le modifiche apportate siano corrette nella documentazione generata, navigare alla cartella doc/ ed eseguire il comando make rst. Questo convertirà i file XML nel formato della documentazione online e segnalerà eventuali errori.

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

Consigliamo di utilizzare un editor di codice che supporti i file XML come Vim, Atom, Visual Studio Code, Notepad++ o un altro per modificare comodamente il file. Si può anche utilizzare la funzione di ricerca per trovare rapidamente classi e proprietà.

Suggerimento

Se si utilizza Visual Studio Code, è possibile installare l'estensione vscode-xml per ottenere il linting per i file XML di riferimento alle classi.

Migliorare la formattazione con i tag di stile BBCode

Il riferimento alle classi XML di Godot supporta tag simili a BBCode per i collegamenti e la formattazione di testo e codice. Nelle tabelle seguenti sono riportati i tag disponibili, gli esempi di utilizzo e i risultati dopo la conversione in reStructuredText.

Collegamento

Ogni volta che si crea un collegamento a un membro di un'altra classe, è necessario specificarne il nome. Per i collegamenti alla stessa classe, il nome della classe è facoltativo e può essere omesso.

Tag e descrizione	Esempio	Risultato
`[Class]` Collega a una classe	`Sposta lo [Sprite2D].`	Sposta lo Sprite2D.
`[annotation Class.name]` Collega a un'annotazione	`Vedi [annotation @GDScript.@rpc].`	Vedi @GDScript.@rpc.
`[constant Class.name]` Collega a una costante	`Vedi [constant Color.RED].`	Vedi Color.RED.
`[enum Class.name]` Collega a un'enumerazione	`Vedi [enum Mesh.ArrayType].`	Vedi Mesh.ArrayType.
`[member Class.name]` Collega a un membro	`Ottieni [member Node2D.scale].`	Ottieni Node2D.scale.
`[method Class.name]` Collega a un metodo	`Chiama [method Node3D.hide].`	Chiama Node3D.hide().
`[constructor Class.name]` Collega a un costruttore integrato	`Usa [constructor Color.Color].`	Usa Color.Color.
`[operator Class.name]` Collega a un operatore integrato	`Usa [operator Color.operator *].`	Usa Color.operator *.
`[signal Class.name]` Collega a un segnale	`Emetti [signal Node.renamed].`	Emetti Node.renamed.
`[theme_item Class.name]` Collega a un elemento del tema	`Vedi [theme_item Label.font].`	Vedi Label.font.
`[param name]` Nome di parametro (come codice)	`Accetta [param size] per le dimensioni.`	Accetta `size` per le dimensioni.

Nota

Attualmente solo @GDScript contiene annotazioni.

Formattazione del testo

Tag e descrizione	Esempio	Risultato
`[br]` Interruzione di riga	`Riga 1.[br]` `Riga 2.`	Riga 1. Riga 2.
`[lb]` `[rb]` `[` e `]` rispettivamente	`[lb]b[rb]testo[lb]/b[rb]`	[b]testo[/b]
`[b]` `[/b]` Grassetto	`[b]Non[/b] chiamare questo metodo.`	Non chiamare questo metodo.
`[i]` `[/i]` Corsivo	`Restituisce la posizione [i]globale[/i].`	Restituisce la posizione globale.
`[u]` `[/u]` Sottolinea	`Usa [u]sempre[/u] questo metodo.`	Always use this method.
`[s]` `[/s]` Barrato	`[s]Informazioni obsolete.[/s]`	~~Outdated information.~~
`[url]` `[/url]` Collegamento ipertestuale	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Sito web
`[center]` `[/center]` Centratura orizzontale	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Scorciatoia da tastiera/mouse	`Premi [kbd]Ctrl + C[/kbd].`	Premi `Ctrl + C`.
`[code]` `[/code]` Frammento di codice in riga	`Restituisce [code]true[/code].`	Restituisce `true`.

Nota

Alcuni tag supportati come [color] e [font] non sono elencati qui perché non sono consigliati nella documentazione del motore.
[kbd] disattiva il BBCode finché il parser non incontra [/kbd].
[code] disattiva il BBCode finché il parser non incontra [/code].

Formattazione dei blocchi di codice

Ci sono due opzioni per formattare i blocchi di codice:

Usa [codeblock] se desideri aggiungere un esempio per un linguaggio specifico.
Usa [codeblocks], [gdscript] e [csharp] se desideri aggiungere lo stesso esempio per entrambi i linguaggi, GDScript e C#.

Normalmente, [codeblock] evidenzia la sintassi in GDScript. È possibile cambiarla tramite l'attributo lang. Le opzioni attualmente supportate sono:

[codeblock lang=text] disabilita l'evidenziazione della sintassi;
[codeblock lang=gdscript] evidenzia la sintassi in GDScript;
[codeblock lang=csharp] evidenzia la sintassi in C# (solamente nella versione .NET).

Nota

[codeblock] disattiva il BBCode finché il parser non incontra [/codeblock].

Avvertimento

Usa [codeblock] per i blocchi di codice preformattati. A partire da Godot 4.5, Si dovrebbero utilizzare tabulazioni per l'indentazione.

Per esempio:

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

Verrà visualizzato come:

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

Se è necessario avere versioni diverse di codice in GDScript e C#, usa invece [codeblocks]. Se usi [codeblocks], devi anche avere almeno uno dei tag specifici della lingua, [gdscript] e [csharp].

Scrivi sempre prima gli esempi di codice in GDScript! Puoi usare questo ` strumento sperimentale di traduzione del codice <https://github.com/HaSa1002/codetranslator>`_ per velocizzare il tuo flusso di lavoro.

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

Quanto sopra apparirà come:

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

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

Formattazione di note e avvertenze

Per indicare informazioni importanti, aggiungi un paragrafo che inizia con "[b]Nota:[/b]" alla fine della descrizione:

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

Per indicare informazioni cruciali che potrebbero causare problemi di sicurezza o perdita di dati se non seguite attentamente, aggiungi un paragrafo che inizia con "[b]Attenzione:[/b]" alla fine della descrizione:

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

In tutti i paragrafi descritti in precedenza, assicurati che la punteggiatura faccia parte dei tag BBCode per coerenza.

Segnare l'API come deprecata/sperimentale

Per contrassegnare un'API come deprecata o sperimentale, è necessario aggiungere l'attributo XML corrispondente. Il valore dell'attributo deve essere un messaggio che spiega perché l'API non è consigliata (il markup BBCode è supportato) o una stringa vuota (sarà utilizzato il messaggio predefinito). Se un elemento dell'API è segnato come deprecato/sperimentale, viene considerato documentato anche se la descrizione è vuota.

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