文档编写指南

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 rules for clear English

使用陈述句型

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

被动句:

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.

使用精确的动作动词

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

不要 重复方法的名称。它已经声明会将 pivot 值设置为新值:

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

解释这个 set 的含义是什么:使用精确的动词,如 placepositionrotatefade 等。

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的形容词名词。这不是一个动词时态变换,所以您可以使用它们:剩余的运动(the remaining movement)缺少的文件(the missing file) 等等。

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

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

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

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

一种简单的描述性语言写短句:

A big texture [...]

禁止这8个词

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

  1. 显然(obvious)
  2. 简单(simple)
  3. 基本(basic)
  4. 容易(easy)
  5. 实际(actual)
  6. 仅仅(just)
  7. 明显(clear)
  8. however(某些用法)

游戏的创建和编程并不简单,对于初次学习使用API的人来说,更是如此。列表中的其他单词,如 justactual,不会在句子中添加任何信息。也不要使用相应的副词: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.

使用显式引用

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

不要 使用如 前者(the former)后者(the latter) 等词语。它们不是英语中最常见的词语,它们要求您查看引用文献。

[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 KinematicBody2D node, a CollisionShape2D node and a sprite node.

andor 之前添加逗号,特别是对于超过两个元素的列表的最后一个元素之前。

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

如何编写方法和类

Dynamic vs static typing

The code examples in the documentation should follow a consistent style not to confuse users. As static type hints are an optional feature of GDScript, we chose to stick to writing dynamic code. This leads to writing GDScript that is concise and accessible.

The exception is topics that explain static typing concepts to users.

Don’t add a type hint with a colon or by casting:

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

Do write constants variables with dynamic typing:

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

Don’t write functions with inferred arguments or return types:

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

Do write functions using dynamic typing:

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]

Use real-world code examples where appropriate

Real-world examples are more accessible to beginners than abstract foos and bars. You can also copy them directly from your game projects, ensuring that any code snippet compiles without errors.

Writing var speed = 10 rather than var my_var = 10 allows beginners to understand code better. It gives them a frame of reference as to where they could use the code snippets in a live project.

Don’t write made-up examples:

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


func foo():
    # Do stuff

Do write concrete examples:

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

Of course, there are times when using real-world examples is impractical. In those situations, you should still avoid using names such as my_var, foo() or my_func() and consider more meaningful names for your examples.

在简述中概述节点

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

  1. 这是 创建新节点 对话框中的唯一描述。
  2. 它位于参考手册中每个页面的顶部

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

不要 写一些简短而含糊的摘要:

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

概述节点的功能:

**Node2D**
2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.

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

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

一些方法返回重要值。在描述的结尾,最好在新行上描述它们。对于名称以 setget 开头的任何方法,无需提及其返回值。

不要 使用被动句型:

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.

注意 陈述句 规则的例外:通过移动方法,外部对撞可以影响方法和调用 移动 的主体。在这种情况下,您可以使用被动语态。

使用 if true 来描述布尔值

对于布尔成员变量,总是使用 if true 和/或 if false 来保持显式。控制是否 可能不明确,且不适用于每个成员变量。

布尔值、变量名和方法围绕着 [code][/code]

if true 开头:

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

在参数周围使用 [code]

在类参考手册中,始终使用 [code][/code] 包围参数。在文档和Godot中,它将显示为 this。在Godot存储库中编辑XML文件时,用 [code]this[/code] 替换现在的参数,如 'this'`this`

Common vocabulary to use in Godot’s documentation

开发人员选择了一些特定的单词来引用界面的区域。它们在文档以及源代码中使用,您应该始终使用它们而不是同义词,因此用户知道您在谈论什么。

Overview of the interface and common vocabulary

界面和常用词汇概述

在编辑器的左上角是 主菜单(main menus)。在中心,按钮改变了 工作区(workspace)。右上角的按钮是 播放测试按钮(playtest buttons)。显示在2D或3D空间中心区域的是 视图(viewport)。在它的顶部,您会在 工具栏(toolbar) 中找到一个 工具(tools) 列表。

视图两侧的选项卡或可停靠面板是 停靠面板(docks)。有 文件系统停靠面板(FileSystem dock)、包含您的场景树的 场景停靠面板(Scene dock)导入停靠面板(Import dock)节点停靠面板(node dock)、以及 属性检查器(Inspector)检查器停靠面板(Inspector dock)。使用默认布局,您可以调用选项卡式停靠面板 选项卡(tabs)场景选项卡(Scene tab)节点选项卡(Node tab)……

视图底部的动画、调试器等是 面板(panels)。它们一起构成了 底部面板(bottom panels)

属性检查器的可折叠区域是 部分(sections)。您无法折叠的节点的父类名称是 类(Classes),例如 KinematicBody2D class。具有键值对的单独行是 属性(properties)。例如,位置(position)调整颜色(modulate color) 都是 属性(properties)

Keyboard shortcut guidelines

Keyboard and mouse shortcuts should make use of the :kbd: tag, which allows shortcuts to stand out from the rest of the text and inline code. Use the compact form for modifier keys (Ctrl/Cmd) instead of their spelled out form (Control/Command). For combinations, use the + symbol with a space on either side of the symbol.

Make sure to mention shortcuts that differ on macOS compared to other platforms. On macOS, Cmd often replaces Ctrl in keyboard shortcuts.

Try to integrate the shortcut into sentences the best you can. Here are some examples with the :kbd: tag left as-is for better visibility:

  • Press :kbd:`Ctrl + Alt + T` to toggle the panel (:kbd:`Cmd + Alt + T` on macOS).
  • Press :kbd:`Space` and hold the left mouse button to pan in the 2D editor.
  • Press :kbd:`Shift + Up Arrow` to move the node upwards by 8 pixels.

图像贡献指南

文档中很重要的一部分是图像,并且要遵循几个重要的准则。

首先,在截屏时应始终使用默认编辑器主题和文本。

To improve the apperance of 3D screenshots, use 4× MSAA, enable anisotropic filtering on the project’s textures, and set the anisotropic filter quality to 16× in Project Settings.

Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower connections.

当您需要突出显示编辑器的某个区域以显示某些内容,如按钮或选项时,请使用不带斜角的2像素粗轮廓。

Before you add or replace any images in the documentation, they should be run through a PNG compressor to save size. The built in lossless compressor in programs like Krita or Photoshop should be enough. For heavier images, also look into using a lossy compressor, such as pngquant where almost no image quality is lost during compression.