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>

• <константа>

• <method> (у його тегу <description>; типи повернення та аргументи не приймають окремих рядків документації)

• <member>

• <signal> (у його тегу <description>; аргументи не приймають окремих рядків документації)

• <константа>

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

Як редагувати XML класу

Відредагуйте файл для вибраного класу в doc/classes/, щоб оновити посилання на клас. Папка містить файл XML для кожного класу. XML містить перелік констант і методів, які ви знайдете в довідці про клас. Godot створює та оновлює XML автоматично.

Примітка

Для деяких модулів у вихідному коді механізму ви знайдете файли XML у каталозі modules/<module_name>/doc_classes/.

Відредагуйте його за допомогою улюбленого текстового редактора. Якщо ви використовуєте редактор коду, переконайтеся, що він не змінює стиль відступу: ви повинні використовувати вкладки для XML і чотири пробіли всередині блоків у стилі BBCode. Детальніше про це нижче.

Щоб перевірити правильність внесених вами змін у створеній документації, перейдіть до папки doc/ і виконайте команду make rst. Це перетворить файли XML у формат онлайнової документації та виведе помилки, якщо щось не так.

Крім того, ви можете створити Godot і відкрити змінену сторінку у вбудованому довідковому коді. Щоб дізнатися, як скомпілювати двигун, прочитайте compilation guide.

Ми рекомендуємо використовувати редактор коду, який підтримує файли XML, наприклад Vim, Atom, Visual Studio Code, Notepad++ або інший, щоб зручно редагувати файл. Ви також можете скористатися їх функцією пошуку, щоб швидко знайти класи та властивості.

Порада

Якщо ви використовуєте Visual Studio Code, ви можете встановити розширення vscode-xml, щоб отримати linting для XML-файлів посилання на клас.

Покращуйте форматування за допомогою тегів стилю BBCode

Довідник класу XML Godot підтримує теги, подібні до BBCode, для зв’язування, а також форматування тексту та коду. У таблицях нижче ви можете знайти доступні теги, приклади використання та результати після перетворення на reStructuredText.

Посилання

Щоразу, коли ви посилаєтеся на члена іншого класу, вам потрібно вказати назву класу. Для посилань на той самий клас ім’я класу є необов’язковим і його можна опустити.

Тег і опис	Приклад	Результат
[Class] Посилання на клас	Перемістити [Sprite2D].	Перемістити class_Sprite2D.
[annotation Class.name] Посилання на анотацію	Див. [annotation @GDScript.@rpc].	Перегляньте @GDScript.@rpc.
[constant Class.name] Посилання на константу	Див. [constant Color.RED].	Перегляньте Color.RED.
[enum Class.name] Посилання на enum	Див. [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 *.
[сигнал 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] [ і ] відповідно	[lb]b[rb]text[lb]/b[rb]	[b]text[/b]
[b] [/b] Напівжирний	[b]Не[/b] викликайте цей метод.	Не викликайте цей метод.
[i] [/i] Курсив	Повертає [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] Комбінація клавіш/миші	Натисніть [kbd]Ctrl + C[/kbd].	Натисніть Ctrl + C.
[code] [/code] Вбудований фрагмент коду	Повертає [code]true[/code].	Повертає true.

Примітка

1. Деякі підтримувані теги, такі як [color] і [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#, використовуйте натомість [codeblocks]. Якщо ви використовуєте [codeblocks], вам також потрібно мати принаймні один із специфічних для мови тегів [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]Примітка:[/b]»:

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

Щоб позначити важливу інформацію, яка може спричинити проблеми з безпекою або втрату даних, якщо її не дотримуватися, додайте абзац, що починається з «[b]Попередження:[/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>