类参考入门
- 如何编辑类 XML
  - 使用 BBCode 风格标签来改进格式
  - 将 API 标记为已弃用/实验性

类参考入门

本页面将介绍如何编写类参考手册。你会学到去哪里为 Godot 内置节点类型的类、方法、属性编写新的描述。

参见

要学习如何使用 Git 版本控制系统向 Godot 项目提交你的修改，请参见为类参考手册贡献。

每个类的参考文档都被包含在一个如下的 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/<模块名称>/doc_classes/ 目录下。

用你喜欢的文本编辑器编辑它。如果你使用代码编辑器，请确保它不会改变缩进样式：XML 使用制表符，而 BBCode 风格的块内使用 4 个空格。下面有更多这方面的内容。

要检查你所做出的修改在生成后的文档中是否正确，请在 doc/ 文件夹中执行命令 make rst。这样就会将 XML 文件转换为在线文档的格式，存在错误时会有错误报告。

你也可以自行构建 Godot 然后在内置的类参考手册中打开被修改的页面。引擎的编译方法请查看 compilation guide。

我们推荐使用 Vim、Atom、Visual Studio Code、Notepad++ 等支持 XML 的代码编辑器，或者其他能够方便编辑此类文件的编辑器。你还可以使用它们的搜索功能快速查找类和属性。

小技巧

如果你使用 Visual Studio Code，则可以安装 vscode-xml 扩展 <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml> 来纠察 XML 文件的类引用。

使用 BBCode 风格标签来改进格式

Godot 的 XML 类引用支持类似 BBCode 的标记，用于链接以及格式化文本和代码。在下表中，你可以找到可用的标记、用法示例以及转换为 reStructuredText 后的结果。

链接

每从其他类里链接一个成员，你都要在成员名前面加上该类的类名。而链接类内成员时，类名可省略。

描述	示例	结果
`[Class]` 链接类	`移动 [Sprite]。`	移动 Sprite2D。
`[annotation Class.name]` 链接到注解	`见 [annotation @GDScript.@rpc].`	见 @GDScript.@export。
`[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]` 换行	`行 1。[br]` `行 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]网站[/url]`	https://example.com 网站
`[center]` `[/center]` 水平居中	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` 键盘和鼠标快捷键	`按下 [kbd]Ctrl + C[/kbd] 组合键。`	按下 :kbd:`</a>Ctrl + C`组合键。
`[code]` `[/code]` 嵌入式代码片段	`返回[code]true[/code]。`	返回 `true` 。

备注

Some supported tags like [color] and [font] are not listed here because they are not recommended in the engine documentation.
[kbd] 与 [/kbd] 之间的 BBCode 代码均无效。
[code] 与 [/code] 之间的 BBCode 代码均无效。

格式化代码块

格式化代码块有两种方法：

如果要添加特定语言的示例，请使用 [codeblock]。
如果要添加相同示例的 GDScript 和 C# 的版本，请使用 [codeblocks]、[gdscript]、[csharp]。

[codeblock] 默认会高亮 GDScript 语法，用 lang 修饰符即可对其语法高亮所用的语言进行修改。目前支持下列语言的高亮：

[codeblock lang=text] 禁用语法高亮;
[codeblock lang=gdscript] 高亮 GDScript 语法;
[codeblock lang=csharp] 高亮 C# 语法（仅.NET版本有效）。

备注

[codeblock] 与 [/codeblock] 之间的 BBCode 代码均无效。

警告

对预格式化的代码块使用 [codeblock]。在 [codeblock] 中，请始终使用四个空格进行缩进。解析器将删除制表符。

例如：

[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())

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

Formatting notes and warnings

要表示重要信息，请在描述末尾添加一段以“[b]Note:[/b]”开头的内容：

[b]Note:[/b] Only available when using the Vulkan 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 标记为已弃用/实验性

To mark an API as deprecated or experimental, you need to add the corresponding XML attribute. The attribute value must be a message explaining why the API is not recommended (BBCode markup is supported) or an empty string (the default message will be used). If an API element is marked as deprecated/experimental, then it is considered documented even if the description is empty.

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