mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
307 lines
16 KiB
ReStructuredText
307 lines
16 KiB
ReStructuredText
.. _doc_class_reference_primer:
|
|
|
|
Class reference primer
|
|
======================
|
|
|
|
This page explains how to write the class reference. You will learn where to
|
|
write new descriptions for the classes, methods, and properties for Godot's
|
|
built-in node types.
|
|
|
|
.. seealso::
|
|
|
|
To learn to submit your changes to the Godot project using the Git version
|
|
control system, see :ref:`doc_updating_the_class_reference`.
|
|
|
|
The reference for each class is contained in an XML file like the one below:
|
|
|
|
.. code-block:: xml
|
|
|
|
<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>
|
|
|
|
|
|
It starts with brief and long descriptions. In the generated docs, the brief
|
|
description is always at the top of the page, while the long description lies
|
|
below the list of methods, variables, and constants. You can find methods,
|
|
member variables, constants, and signals in separate XML nodes.
|
|
|
|
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>` (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>`
|
|
|
|
Write in a clear and simple language. Always follow the :ref:`writing guidelines
|
|
<doc_docs_writing_guidelines>` to keep your descriptions short and easy to read.
|
|
**Do not leave empty lines** in the descriptions: each line in the XML file will
|
|
result in a new paragraph, even if it is empty.
|
|
|
|
.. _doc_class_reference_editing_xml:
|
|
|
|
How to edit class XML
|
|
---------------------
|
|
|
|
Edit the file for your chosen class in ``doc/classes/`` to update the class
|
|
reference. The folder contains an XML file for each class. The XML lists the
|
|
constants and methods you will find in the class reference. Godot generates and
|
|
updates the XML automatically.
|
|
|
|
.. note:: For some modules in the engine's source code, you'll find the XML
|
|
files in the ``modules/<module_name>/doc_classes/`` directory instead.
|
|
|
|
Edit it using your favorite text editor. If you use a code editor, make sure
|
|
that it doesn't change the indent style: you should use tabs for the XML and
|
|
four spaces inside BBCode-style blocks. More on that below.
|
|
|
|
To check that the modifications you've made are correct in the generated
|
|
documentation, navigate to the ``doc/`` folder and run the command ``make rst``.
|
|
This will convert the XML files to the online documentation's format and output
|
|
errors if anything's wrong.
|
|
|
|
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 :ref:`compilation
|
|
guide <toc-devel-compiling>`.
|
|
|
|
We recommend using a code editor that supports XML files like Vim, Atom, Visual Studio Code,
|
|
Notepad++, or another to comfortably edit the file. You can also use their
|
|
search feature to find classes and properties quickly.
|
|
|
|
.. tip::
|
|
|
|
If you use Visual Studio Code, you can install the
|
|
`vscode-xml extension <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml>`__
|
|
to get linting for class reference XML files.
|
|
|
|
.. _doc_class_reference_bbcode:
|
|
|
|
Improve formatting with BBCode style tags
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Godot's XML class reference supports BBCode-like tags for linking as well as formatting text and code.
|
|
In the tables below you can find the available tags, usage examples and the results after conversion to 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 | Example | Result |
|
|
+===============================+=========================================+======================================================================+
|
|
| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. |
|
|
| | Link to class | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export <class_@GDScript_annotation_@export>`. |
|
|
| | Link to annotation | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
|
|
| | Link to constant | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`. |
|
|
| | Link to enum | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`. |
|
|
| | Link to method | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale <class_Node2D_property_scale>`. |
|
|
| | Link to member | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed <class_Node_signal_renamed>`. |
|
|
| | Link to signal | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font <class_Label_theme_font_font>`. |
|
|
| | Link to theme item | | |
|
|
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
|
|
|
|
.. note::
|
|
|
|
Currently only :ref:`class_@GDScript` has annotations.
|
|
|
|
Formatting text
|
|
"""""""""""""""
|
|
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
| Tag and Description | Example | Result |
|
|
+======================================+======================================+==============================+
|
|
| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. |
|
|
| | Formats a parameter name (as code) | | |
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. |
|
|
| | Line break | | ``Line 2.`` | | Line 2. |
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. |
|
|
| | Bold | | |
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. |
|
|
| | Italic | | |
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. |
|
|
| | Keyboard/mouse shortcut | | |
|
|
+--------------------------------------+--------------------------------------+------------------------------+
|
|
|
|
Formatting code
|
|
"""""""""""""""
|
|
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
| Tag and Description | Example | Result |
|
|
+========================================+=======================================+==========================+
|
|
| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. |
|
|
| | Monospace | | |
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* |
|
|
| | Multiline preformatted block | | |
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
| | ``[codeblocks]`` ``[/codeblocks]`` | *See below.* | *See below.* |
|
|
| | Codeblock for multiple languages | | |
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
| | ``[gdscript]`` ``[/gdscript]`` | *See below.* | *See below.* |
|
|
| | GDScript codeblock tab in codeblocks | | |
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
| | ``[csharp]`` ``[/csharp]`` | *See below.* | *See below.* |
|
|
| | C# codeblock tab in codeblocks | | |
|
|
+----------------------------------------+---------------------------------------+--------------------------+
|
|
|
|
.. note::
|
|
|
|
1. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
|
|
2. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
|
|
|
|
.. warning::
|
|
|
|
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
|
|
always use **four spaces** for indentation. The parser will delete tabs.
|
|
|
|
For example:
|
|
|
|
.. code-block:: none
|
|
|
|
[codeblock]
|
|
func _ready():
|
|
var sprite = get_node("Sprite2D")
|
|
print(sprite.get_pos())
|
|
[/codeblock]
|
|
|
|
Will display as:
|
|
|
|
.. code-block:: gdscript
|
|
|
|
func _ready():
|
|
var sprite = get_node("Sprite2D")
|
|
print(sprite.get_pos())
|
|
|
|
If you need to have different code version in GDScript and C#, use
|
|
``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at
|
|
least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``.
|
|
|
|
Always write GDScript code examples first! You can use this `experimental code
|
|
translation tool <https://github.com/HaSa1002/codetranslator>`_ to speed up your
|
|
workflow.
|
|
|
|
.. code-block:: none
|
|
|
|
[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]
|
|
|
|
The above will display as:
|
|
|
|
.. tabs::
|
|
.. code-tab:: gdscript GDScript
|
|
|
|
func _ready():
|
|
var sprite = get_node("Sprite2D")
|
|
print(sprite.get_pos())
|
|
|
|
.. code-tab:: csharp
|
|
|
|
public override void _Ready()
|
|
{
|
|
var sprite = GetNode("Sprite2D");
|
|
GD.Print(sprite.GetPos());
|
|
}
|
|
|
|
To denote important information, add a paragraph starting with "[b]Note:[/b]" at
|
|
the end of the description:
|
|
|
|
.. code-block:: none
|
|
|
|
[b]Note:[/b] Only available when using the Vulkan renderer.
|
|
|
|
To denote crucial information that could cause security issues or loss of data
|
|
if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at
|
|
the end of the description:
|
|
|
|
.. code-block:: none
|
|
|
|
[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
|
|
|
|
For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
|
|
Notice the use of italics instead of bold:
|
|
|
|
.. code-block:: none
|
|
|
|
[i]Deprecated.[/i] This property has been replaced by [member other_property].
|
|
|
|
In all the paragraphs described above, make sure the punctuation is part of the
|
|
BBCode tags for consistency.
|