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

Эта страница объясняет, как написать ссылку на класс. Вы узнаете, где писать новые описания для классов, методов и свойств встроенных узлов 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`.

Примечание

Некоторые поддерживаемые теги как [color] and [font] не приведены здесь, потому что не рекомендованы в документации движка.
[kbd] отключает BBCode до тех пор, пока анализатор не встретит [/kbd].
[code] отключает BBCode до тех пор, пока анализатор не встретит [/code].

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

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

Используйте [codeblock] если вы хотите добавить пример для определенного языка.
Используйте [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]

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

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

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

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

Чтобы обозначить важную информацию, добавьте в конце описания абзац, начинающийся со слов "[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>