Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
类参考入门¶
本页面将介绍如何编写类参考手册。你会学到去哪里为 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 文件的类引用。