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

Справочник по классам

Эта страница объясняет, как написать ссылку на класс. Вы узнаете, где писать новые описания для классов, методов и свойств встроенных узлов Godot.

См. также

Чтобы узнать, как отправлять изменения в проект Godot с помощью системы контроля версий Git, см. Документацию по вкладу ссылок на классы.

Ссылка на каждый класс содержится в 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>

Всё начинается с краткого и полного описаний. В сгенерированной документации краткое описание всегда находится в верхней части страницы, а полное — под списком методов, переменных и констант. Методы, переменные-члены, константы и сигналы находятся в отдельных узлах XML.

Для каждого из них вам необходимо изучить, как они работают в исходном коде Godot. Затем заполните документацию, дополнив или улучшив текст в следующих тегах:

• <brief_description>

• <description>

• <constant>

• <method> (в теге <description>; возвращаемые типы и аргументы не занимают отдельные строки документации)

• <member>

• <signal> (в теге <description>; аргументы не занимают отдельные строки документации)

• <constant>

Пишите понятным и простым языком. Всегда следуйте правилам написания, чтобы ваши описания были краткими и легко читаемыми. Не оставляйте пустых строк в описаниях: каждая строка в XML-файле будет начинаться с нового абзаца, даже если она пустая.

Как отредактировать класс XML

Отредактируйте файл выбранного класса в doc/classes/, чтобы обновить ссылку на класс. В этой папке содержится XML-файл для каждого класса. В XML-файле перечислены константы и методы, которые вы найдете в ссылке на класс. Godot автоматически генерирует и обновляет XML-файл.

Примечание

Для некоторых модулей в исходном коде движка XML-файлы находятся в каталоге modules/<module_name>/doc_classes/.

Отредактируйте его в вашем любимом текстовом редакторе. Если вы используете редактор кода, убедитесь, что он не меняет стиль отступов: для XML следует использовать табуляцию, а внутри блоков в стиле BBCode — четыре пробела. Подробнее об этом ниже.

Чтобы проверить корректность внесённых вами изменений в сгенерированную документацию, перейдите в папку doc/ и выполните команду make rst. Это преобразует XML-файлы в формат онлайн-документации и выведет сообщения об ошибках, если что-то не так.

В качестве альтернативы вы можете собрать Godot и открыть изменённую страницу во встроенном справочнике по коду. Чтобы узнать, как скомпилировать движок, прочтите руководство по компиляции.

Для удобного редактирования файла рекомендуем использовать редактор кода с поддержкой XML-файлов, например Vim, Atom, Visual Studio Code, Notepad++ или другой. Вы также можете воспользоваться функцией поиска для быстрого поиска классов и свойств.

Совет

Если вы используете Visual Studio Code, вы можете установить расширение vscode-xml, чтобы выполнить линтинг для XML-файлов ссылок на классы.

Улучши форматирование с тегами стиля BBCode

Справочник XML-классов Godot поддерживает теги типа BBCode для связывания и форматирования текста и кода. В таблицах ниже представлены доступные теги, примеры использования и результаты преобразования в reStructuredText.

Связывание

При ссылке на член другого класса необходимо указывать имя класса. Для ссылок на тот же класс имя класса необязательно и может быть опущено.

Тег и Описание	Пример	Результат
[Class] Ссылка на класс	Переместите [Sprite2D].	Переместите Sprite2D.
[annotation Class.name] Ссылка на аннотацию	См. [annotation @GDScript.@rpc].	См. @GDScript.@rpc.
[constant Class.name] Ссылка на константу	См. [constant Color.RED].	См. Color.RED.
[enum Class.name] Ссылка на перечисление	См. [enum Mesh.ArrayType].	См. Mesh.ArrayType.
[member Class.name] Ссылка на участника	Получить[member Node2D.scale].	Получите Node2D.scale.
[method Class.name] Ссылка на метод	Вызов [method Node3D.hide].	Вызов Node3D.hide().
[constructor Class.name] Ссылка на встроенный конструктор	Использовать [constructor Color.Color].	Используйте Color.Color.
[operator Class.name] Ссылка на встроенный оператор	Использовать [operator Color.operator *].	Используйте Color.operator *.
[signal Class.name] Ссылка на сигнал	Выдать [signal Node.renamed].	Передать Node.renamed.
[theme_item Class.name] Ссылка на тему	См. [theme_item Label.font].	См. Label.font.
[param name] Имя параметра (в виде кода)	Принимает [param size] в качестве размера.	Принимает size в качестве размера.

Примечание

В настоящее время аннотации имеются только у @GDScript.

Форматирование текста

Тег и Описание	Пример	Результат
[br] Перенос строки	Line 1.[br] Line 2.	Строка 1. Строка 2.
[lb] [rb] [ and ] соответственно	[lb]b[rb]text[lb]/b[rb]	[b]text[/b]
[b] [/b] Жирный	[b]Не[/b] вызывайте этот метод.	Не вызывайте этот метод.
[i] [/i] Italic	Возвращает [i]глобальную[/i] позицию.	Возвращает глобальную позицию.
[u] [/u] Подчеркнуть	[u]Всегда[/u] используйте этот метод.	Always use this method.
[s] [/s] Зачеркивание	[s]Устаревшая информация.[/s]	Outdated information.
[url] [/url] Гиперссылка	[url]https://example.com[/url] [url=https://example.com]Website[/url]	https://example.com Website
[center] [/center] Горизонтальное центрирование	[center]2 + 2 = 4[/center]	2 + 2 = 4
[kbd] [/kbd] Сочетание клавиш/мыши	Press [kbd]Ctrl + C[/kbd].	Нажмите Ctrl + C.
[code] [/code] Фрагмент встроенного кода	Возвращает [code]true[/code].	Возвращает true.

Примечание

1. Некоторые поддерживаемые теги как [color] and [font] не приведены здесь, потому что не рекомендованы в документации движка.

2. [kbd] отключает BBCode до тех пор, пока анализатор не встретит [/kbd].

3. [code] отключает BBCode до тех пор, пока анализатор не встретит [/code].

Блоки форматирования

Существует два варианта форматирования блоков:

1. Используйте [codeblock] если вы хотите добавить пример для определенного языка.

2. Используйте [codeblocks], [gdscript],и [csharp] если вы хотите добавить такой же пример для обоих языков, GDScript и C#.

По умолчанию [codeblock] подсвечивает синтаксис GDScript. Вы можете изменить это с помощью атрибута lang. В настоящее время поддерживаются следующие параметры:

• [codeblock lang=text] отключает подсветку синтаксиса;

• [codeblock lang=gdscript] подсвечивает синтаксис GDScript;

• [codeblock lang=csharp] подсвечивает синтаксис C# (только в версии .NET).

Примечание

[codeblock] отключает BBCode до тех пор, пока анализатор не встретит [/codeblock].

Предупреждение

Используйте [codeblock] для предварительно отформатированных блоков кода. Начиная с Godot 4.5, для разделения должны использоваться отступы.

Например:

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

Будет показано как:

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

Если нужно одновременно иметь код в GDScript и C#, заключайте его в [codeblock], а также используйте специфические теги, такие как [gdscript] и [csharp].

Всегда сначала пишите примеры кода GDScript! Вы можете использовать этот экспериментальный инструмент перевода кода для ускорения рабочего процесса.

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

Снизу будет отображено как:

GDScriptC#

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

Форматирование заметок и предупреждений

Чтобы обозначить важную информацию, добавьте в конце описания абзац, начинающийся со слов "[b]Note:[/b]" (Примечание:):

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

Чтобы обозначить важную информацию, несоблюдение которой может привести к проблемам безопасности или потере данных, добавьте в конец описания абзац, начинающийся со слов «[b]Warning: (Предупреждение:)[/b]»:

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

Во всех описанных выше параграфах убедитесь, что знаки препинания являются частью тегов BBCode для соблюдения единообразия.

Отметка API как устаревшего/экспериментального

Чтобы отметить API как устаревший или экспериментальный, необходимо добавить соответствующий XML-атрибут. Значение атрибута должно быть сообщением, объясняющим, почему API не рекомендуется к использованию (поддерживается разметка BBCode), или пустой строкой (будет использовано сообщение по умолчанию). Если элемент API отмечен как устаревший/экспериментальный, он считается задокументированным, даже если описание пустое.

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