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 社区丰富且具国际化。用户来自世界各地。他们中的一些人很年轻，很多人不是母语为英语的人。这就是为什么我们都必须使用清晰和通用的语言写作。对于类参考手册，目标是让每个人都能轻松和精确阅读。

总之，请始终尝试：

1. 使用陈述句型

2. 使用精确的动作动词

3. 避免以 -ing 结尾的动词

4. 删除不必要的副词和形容词。

5. 禁止这 8 个词：obvious（显然）、simple（简单）、basic（基本）、easy（容易）、actual（实际）、just（仅仅）、clear（明显）、however（然而）

6. 使用显式引用

7. 使用“'s”表示所有权

8. 使用牛津逗号

描述类有 3 个规则：

1. 在简述中概述该节点

2. 如果它有用，请提及方法返回什么

3. 使用“if true”来描述布尔值

备注

技术作家的工作是将尽可能多的信息打包成尽可能最小和最清晰的句子。这些规范将帮助你实现这一目标。

参见

请查看内容规范，了解你可以在官方文档中编写哪些类型的文档。

英语清晰的 7 条规则

使用陈述句型

尽可能使用陈述句型。将你描述的类、方法和常量作为主语。使用被动语态编写是很自然的，但它更难阅读并会产生更长的句子。

被动句：

The man **was bitten** by the dog.

主动句：

The dog bit the man.

不要使用被动句型：

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

请将节点的名称用作名词：

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

使用精确的动作动词

优先使用精确而通用的动词，不要使用诸如 make、set 以及可以用一个单词替换的任何表达之类的通用动词。

不要重复该方法的名称。名称中已经表达了它会将 pivot 值设置为一个新的值：

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

请解释“set”的结果是什么：使用准确的动词，如 place、position、rotate、fade 等。

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

避免以 -ing 结尾的动词

使用进行时描述连续行动。例如：“is calling”、“is moving”。

不要使用进行时描述即时更改。

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

请使用简单的现在、过去或将来时。

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

例外：如果主语不清楚，替换“ing”动词算不上改进。例如，在前一句中，“it replaces”在“replacing”当前所在的位置没有多大意义。

你可以使用渐进式时态来描述在时间上连续的动作. 任何像动画或协同程序的东西.

小技巧

动词可以变成带有 -ing 的形容词名词。这不是动词时态变换，所以你可以使用它们：the remaining movement、the missing file 等等。

删除不必要的副词和形容词

写尽可能少的形容词和副词. 仅当它们在说明中添加关键信息时, 才使用它们.

不要使用冗余或无意义的副词。延长文档长度但不添加任何信息的词：

**Basically** a big texture [...]

Do write short sentences in a simple, descriptive language:

A big texture [...]

禁止这 8 个词

不要使用这 8 个被禁止的词：

1. obvious（显然）

2. simple（简单）

3. basic（基本）

4. easy（容易）

5. actual（实际）

6. just（仅仅）

7. clear

8. however（然而）（的某些用法）

游戏的创建和编程并不简单，对于初次学习使用 API 的人来说也不容易。列表中的其他单词，如 just 或 actual 不会在句子中添加任何信息。也不要使用相应的副词：obviously、simply、basically、easily、actually、clearly。

不要 举例. 禁止使用的单词加长了说明, 并让注意力从最重要信息上移开:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

请 删除它们:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

“简单”永远不会有帮助。请记住，对于其他用户来说，任何事情都可能很复杂或令人沮丧。没有什么像老套的它很简单让你畏缩的了。这是旧的简述，是 Timer 节点页面上的第一句话：

**Timer**
A **simple** Timer node.

请 代替为解释节点的作用:

**Timer**
Calls a function of your choice after a certain duration.

不要 用 "basic" , 太含糊:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

请 使用简述来概述节点:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

使用显式引用

支持显式引用而不是隐式引用.

不要 使用 "前者" , "后者" 等词语. 这些词在英语中并不是最常见的, 需要你去查阅参考资料.

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

请 重复单词. 他们消除了所有歧义:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

如果需要重复相同的变量名3到4次, 则你可能需要修改你的描述.

使用“'s”表示所有权

避免"The milk of the cow". 英语里感觉不自然. 使用"The cow's milk"代替.

不要 写 "of the X":

The region **of the AtlasTexture that is** used.

请 使用 's . 它使你可以将主要主题放在句子的开头, 并使其简短:

The **AtlasTexture's** used region.

使用牛津逗号枚举任何内容

来自牛津词典:

“牛津逗号”是列表末尾“and”之前的可选逗号：We sell books, videos, and magazines.

[...] 并非所有作家和出版商都使用它，但是当列表中的项目不是单个单词时，它可以阐明句子的含义：These items are available in black and white, red and yellow, and blue and green.

不要让列表的最后一个元素不带逗号：

Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.

请在有两个以上元素清单的最后一个元素 and 或 or 前加上逗号。

Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.

如何编写方法和类

动态类型与静态类型

文档中的代码示例应遵循一致的样式, 以免混淆用户. 由于静态类型提示是GDScript的可选功能, 因此我们选择坚持编写动态代码. 这导致编写简洁明了的GDScript.

例外情况是向用户解释静态类型概念的主题.

不要 用冒号或强制转换添加类型提示:

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D

Do 用动态类型编写常量和变量:

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D

不要 用推断的参数或返回类型编写函数:

func choose(arguments: PackedStringArray) -> String:
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

Do 使用动态类型来写函数:

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

在适当的情况下使用实际代码示例

对于初学者来说，比起抽象的 foo 和 bar，现实世界中的示例更容易被使用。你还可以直接从游戏项目中复制它们，以确保所有代码段都能正确编译。

编写 var speed = 10 而不是 var my_var = 10 可使初学者更好地理解代码. 它为他们提供了有关在实际项目中可以在何处使用代码段的参考框架.

不要写虚构的例子：

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

要写出具体事例：

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

当然，有时候使用实际示例是不切实际的。在这种情况下，你仍应避免使用诸如 my_var、foo()、 my_func() 之类的名称，并考虑示例中更有意义的名称。

在简述中概述该节点

简述是参考手册中最重要的一句话。这是用户与节点的第一次接触：

1. 这是“创建新节点”对话框中的唯一描述。

2. 它位于参考手册中每个页面的顶部

简述应解释节点的角色及其功能，最多 200 个字符。

不要写简短而含糊的摘要：

**Node2D**
Base node for 2D system.

要概述该节点的功能：

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

如果可能的话，请使用该节点的完整描述来提供更多信息和代码示例。

如果它有用，请提及方法返回什么

有些方法会返回重要的值。在描述的结尾，最好在另起一行对它们进行描述。对于名称以 set 或 get 开头的任何方法，无需提及其返回值。

不要使用被动句型：

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

要始终使用“Returns”。

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

注意“陈述句”规则的例外：通过移动（move）方法，外部对撞可以影响方法和调用 move 的主体。在这种情况下，你可以使用被动语态。

使用“if true”来描述布尔值

对于布尔成员变量，总是使用 if true 和/或 if false 来保持显式。Controls whether or not 可能存在歧义，不适用于每个成员变量。

另外，在布尔值、变量名和方法周围用 [code][/code]。

请以“if true”开头：

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

在参数周围使用 [code]

In the class reference, always surround arguments with [code][/code]. In the documentation and in Godot, it will display like this. When you edit XML files in the Godot repository, replace existing arguments written like 'this' or `this` with [code]this[/code].

Godot 文档中的常用词汇

开发人员选择了一些特定的单词来指代界面的区域。它们在文档以及源代码中使用，你应该始终使用它们而不是同义词，这样所有用户都能知道你说的是什么。

界面和常用词汇概述

在编辑器的左上角是 main menu（主菜单）。中间按钮改变的是 workspace（工作区）。右上角的按钮是 playtest button（试玩按钮）。中间显示 2D 或 3D 空间的区域是 viewport（视口）。你可以在它顶部的 toolbar（工具栏）中找到 tool（工具）的列表。

视口两侧的选项卡或可停靠面板叫 dock（停靠面板），包括 FileSystem dock（文件系统面板）、包含场景树的 Scene dock（场景面板）、Import dock（导入面板）、Node dock（节点面板）、Inspector（检查器）也叫 Inspector dock（检查器面板）。如果使用的是默认布局，也可以把选项卡式的停靠面板称作 tab（选项卡）：Scene tab（场景选项卡）、Node tab（节点选项卡）……

视口底部的动画、调试器等是 panel（面板），它们一起构成了 bottom panel（底部面板）。

检查器的可折叠区域是 section（部分）。节点的父类名称无法折叠，称作 Class（类），例如 CharacterBody2D class。具有键值对的单独行是 property（属性）。比如position 和 modulate color 就都是 property。

键盘快捷键规范

键盘和鼠标快捷方式应使用 :kbd: 标记，该标记可使快捷方式在其余文本和内联代码中脱颖而出。使用紧凑形式的修饰键（Ctrl/ Cmd）而不是其拼写形式（Control/ Command）。对于组合按键，请在符号的两侧使用 + 符号。

请确保对 macOS 与其他平台不同的快捷方式有所提及。包括 macOS 在内的所有快捷键列表都可以在这个页面上找到。

尽量将快捷方式集成到句子中。例子如下，为了更好地展示而保留了 :kbd: 标记：

• 按 :kbd:`Ctrl + Alt + T` 切换面板（在 macOS 上则是 :kbd:`Opt + cmd + T`）。

• 按 :kbd:`Space` 并按住鼠标左键在2D编辑器中平移.

• 按 :kbd:`Shift+Up Arrow` 可将节点向上移动8像素.

Manual style guidelines

Follow these formatting and style guidelines when writing the manual.

Use your best judgement. If you can write more clearly by breaking one of these guidelines, please do! But remember that the guidelines exist for a reason.

备注

In many cases, the manual does not follow these guidelines. If you are already making changes to a paragraph or section of the docs, update it to follow these standards. Avoid making unrelated changes that only update style, since every change will require the paragraph to be re-translated.

Text styles

There are a few styles that the manual uses.

Style	RST formatting	Typical usage
Plaintext	text	Used for most text.
Italics	*text*	Used for emphasis. Used for introducing new terms.
Bold	**text**	Used for emphasis, and for editor UI like menus and windows.
Code	`` text ``	Used for variable names, literal values, and code snippets. code is used in many cases where you would use "quoted plaintext" in typical English.
"Quotes"	"text"	Used for some literal or quoted values. In many cases, another style is preferred.

Emphasis

Use either bold style or italic style to emphasize words or sentences. In most cases, either bold or italics is fine. Use whichever seems best, or whatever the page already uses.

Prefer using bold style for simple emphasis.

• Do not close the window without saving first.

Use italic style or to emphasize one word in the context of a sentence.

• You can add a node to the scene (but you can't connect one).

• You can add a node to the scene (but you can't add a resource).

• You can add a node to the scene (but you can't add one to a resource).

Use italic style when introducing new technical terms. Bold style is fine too.

• Godot uses nodes with scripts in a scene tree.

• Godot uses nodes with scripts in a scene tree.

字面量

Use code style for literal values. Literals include:

• Integer or int literals like 0, -2, or 100

• Float literals like 0.0, 0.5, -2.0, or 100.0

• Vector literals like (0.0, 0.0), (0.5, -0.5, 0.5), or (1.0, 2.0, 3.0, 4.0).

Classes, properties, and methods

Link to classes the first time that you mention them in a page. After the first mention, use code style. For common classes, like Node, Control, or Viewport, you can also use plaintext.

Link to class members (properties, methods, enums, and constants) the first time that you mention them in a page. After the first mention, use code style. If the class member is very common, like a Node2D's position, you don't have to link.

When discussing properties in the context of the inspector, use bold style instead.

Editor UI

Use bold style for editor UI, including window titles, menus, buttons, input fields, inspector properties, and inspector sections. Use the exact capitalization that the editor uses.

• Open the Editor Settings window.

• Press the Confirm button.

• Change the node's Transform > Position property to (0, 0).

• In the Project Settings window, enable the Advanced Settings toggle.

Use Bold > With > Separators when describing sequence of menus that the reader must navigate. Use > as a separator. You can omit ellipses in menu names.

• In Project > Project Settings > Input Map, add a new input action.

• Select Scene > Export As... > MeshLibrary....

• Select Scene > Export As > MeshLibrary.

备注

Sometimes, -> or → is used as a separator. This is nonstandard. Replace it with > if you are already making changes to a section.

Project settings

Link to individual project settings. Either include the section and subsection in the link itself, or include the section and subsection separately from the link. Since long links are not split into multiple lines when the page is rendered, prefer splitting the setting name and the section when the link is long.

• Set the Application > Run > Max FPS setting to 60.

• In the project settings under Application > Run, set Max FPS to 60.

• In Project Settings > Application > Run, set Max FPS to 60.

Manually wrapping lines

In the manual, lines must be manually wrapped to no more than 80-100 characters per line. However, links must not be split into multiple lines, and can exceed 100 characters. Tables can also exceed 100 characters.

When making small changes, you don't need to manually re-wrap the whole paragraph, as long as the lines don't exceed 100 characters.

Bad: Line length exceeds 100 characters:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to around 80-90 characters per line is also fine.
If your lines exceed 100 characters, you definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Good: Lines are wrapped to 80-90 characters:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to
around 80-90 characters per line is also fine. If your lines exceed 100 characters, you
definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Best: Lines are wrapped to under 80 characters:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping
to around 80-90 characters per line is also fine. If your lines exceed 100
characters, you definitely need to add a newline! Don't forget to remove
trailing whitespace when you do.

小技巧

In most text editors, you can add a vertical guide or "ruler" at 80 characters. For example, in Visual Studio Code, you can add the following to your settings.json to add rulers at 80 and 100 characters:

"editor.rulers": [80,100],

Section header syntax

Use the following syntax for section headers:

Page title
==========

Renders as h1.
Every page has this.

Section header
--------------

Renders as h2.
Usually appears in sidebar. Many pages only need one level of nested headers.

Sub-section header
~~~~~~~~~~~~~~~~~~

Renders as h3.
Appears in sidebar in some pages, depending on how deeply nested the page is.

Sub-sub-section header
^^^^^^^^^^^^^^^^^^^^^^

Renders as h4.
Usually won't appear in the sidebar.

Currently, there are no cases of deeper header nesting than this. Avoid introducing any deeper nesting.

Note that headers have no inherent meaning. In reStructuredText, headers are parsed based on the order that they initially appear within a page. Make sure that if you use an h3 section header (~~~), you include an h2 sub-section header (---) first.

See the Sphinx documentation and the reStructuredText documentation for more information.

When to refer to a specific Godot version

Most of the time, the class reference and the manual should not specify the first version in which a feature is added. This is because the documentation describes the current features of the engine. Documentation will be read and maintained for many versions after it is initially written, and a reference to a first supported version is only relevant for a few versions after a feature is added. After that, it becomes historical trivia best left to a dedicated changelog.

Follow these guidelines for when to refer to a specific Godot version:

• If a feature was added in the current major version (4.x), you can specify the feature is new in 4.x.

• If a feature or default approach to a problem was changed between major versions (3.x -> 4.x), describe the current feature in the main body of the page, and optionally add a brief sentence or note block to compare 3.x and 4.x.

• If a large feature is added in a 4.x minor version, you can specify the minor version when it was added. Large features have a whole page or large section of documentation. In many cases it should still be avoided, since it's only relevant for the next few minor versions.

• If a small feature is added in a 4.x minor version, do not specify the minor version when it was added. Small features have only a short section of documentation, or are minor additions to existing features.

• If the default approach to a problem is changed in a 4.x minor version, do specify the minor version in which a new default approach was added. For example, the change from TileMap to TileMapLayer in 4.3.

• If a feature was added in a 3.x major or minor version, do not specify when the feature was added. These features are old enough that the exact version in which they were added is not relevant.