文件撰寫方針

Godot 社群多元且國際化，用戶來自世界各地。有些用戶年紀很輕，多數也非英語母語者。因此，我們必須使用清晰且通用的語言撰寫文件。對於類別參考，目標是讓每個人都能輕鬆閱讀且內容精確。

總結來說，請盡量做到：

1. 使用主動語態

2. 使用精確的動作動詞

3. 避免使用以 -ing 結尾的動詞

4. 移除不必要的副詞與形容詞。

5. 禁止使用以下八個單字：obvious、simple、basic、easy、actual、just、clear、however

6. 使用明確的參照

7. 使用 's 表示所有格

8. 使用牛津逗號

描述類別時有三個原則：

1. 在簡介中提供節點的整體說明

2. 必要時說明方法的回傳值

3. 使用「if true」來描述布林值

備註

技術文件編寫者的工作，就是將最多的資訊濃縮進最簡潔明瞭的句子裡。這些指引能協助你達成此目標。

也參考

請參閱 內容規範，了解在官方文件中可以撰寫的各類型文件。

七項讓英文更清晰的規則

使用主動語態

盡可能使用主動語態。以你要描述的類別、方法與常數作為主詞。雖然被動語態較常見，閱讀起來卻較不易且句子較長。

被動語態：

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 等泛用動詞，並盡量用一個單字取代冗長表達。

不要 重複方法名稱，名稱本身已說明該動作：

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 形式反而會讓句子更難懂。例如前一句話的「replacing」若改成「it replaces」就不適合。

若要描述隨時間持續進行的動作（如動畫、協程等），可使用進行式。

小訣竅

動詞加上 -ing 可做為形容詞，這非時態變化，因此可以這樣使用，如 the remaining movement、the missing file 等。

移除不必要的副詞與形容詞

儘量少用副詞與形容詞，只有在它們能提供關鍵資訊時才使用。

不要 使用冗贅或無意義的副詞，這些只會讓文件變長而無實質內容：

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

請 用簡單的描述性語言寫出短句：

A big texture [...]

禁止使用這八個詞彙

絕對不要 使用這八個禁用詞：

1. obvious

2. simple

3. basic

4. easy

5. actual

6. just

7. 清除

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.

「Simple」從來沒幫上忙。記得，對其他人來說，任何東西都可能很複雜、令人沮喪。沒什麼比「it's simple」更讓人難受。以下是 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.

如果同一變數名稱需重複三四次，請考慮重寫句子。

使用 '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 的靜態型別提示為可選功能，我們選擇以動態型別為主，使程式碼更簡潔且易於理解。

唯獨說明靜態型別概念的主題為例外。

不要 用冒號或型別轉換來加型別提示：

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

請 用動態型別寫常數與變數：

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]

請 用動態型別撰寫函式：

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] 包住參數

在類別參考中，所有參數都需用 [code][/code] 包起來。Godot 文件和編輯器中會以 這樣 顯示。若在 Godot 儲存庫編輯 XML 檔案，請將 'this' 或 `this` 改為 [code]this[/code]。

Godot 文件常用詞彙

開發團隊選定了一些專用詞彙來稱呼介面各區塊。這些詞會出現在原始碼及說明文件中，請務必使用這些固定用語，避免混用同義詞，讓使用者更容易理解。

介面總覽與常用詞彙

編輯器左上角是 主選單（Main Menus），中間的按鈕切換 工作區（Workspace）。右上角的按鈕稱為 執行測試按鈕（Playtest Buttons）。中央顯示 2D 或 3D 空間的區域是 檢視區（Viewport），其上方則有包含 工具（Tools） 的 工具列（Toolbar）。

檢視區兩側的分頁或可停靠面板稱為 停駐列（Docks）。包含 檔案系統停駐列（FileSystem dock）、內含場景樹的 場景停駐列（Scene dock）、匯入停駐列（Import dock）、節點停駐列（Node dock），以及 屬性檢視器（Inspector） 或 屬性檢視器停駐列（Inspector dock）。預設配置下，這些分頁稱為 分頁（Tabs），如 場景分頁（Scene tab）、節點分頁（Node tab） 等。

動畫、除錯等顯示在檢視區底部的區域稱為 面板（Panels），合稱 底部面板（Bottom Panels）。

屬性檢視器中可收合的區域稱為 段落（Sections）。不可收合的父類別名稱稱為 類別（Classes），如 CharacterBody2D 類別。每一行的鍵值對稱為 屬性（Properties），如 position 或 modulate color。

鍵盤快捷鍵指引

鍵盤和滑鼠快捷鍵應使用 :kbd: 標籤，以便在文字與程式碼中脫穎而出。修飾鍵請用簡寫（Ctrl / Cmd），不要用全名（Control / Command）。組合鍵請用 + 符號，符號前後要有空格。

請確保當快捷鍵在 macOS 上與其他平台不同時要特別註明。你可以在 本頁 找到所有快捷鍵及其在 macOS 上的對應。

請盡量將快捷鍵整合進語句中。以下範例特別保留 :kbd: 標籤以強調可見度：

• 按 :kbd:`Ctrl + Alt + T` 切換面板（macOS 上為 :kbd:`Opt + Cmd + T`）。

• 按 :kbd:`Space` 並按住滑鼠左鍵可在 2D 編輯器中平移檢視。

• 按 :kbd:`Shift + 上方向鍵` 可將節點向上移動 8 像素。

手冊樣式指引

撰寫手冊時請遵循以下格式與樣式規範。

請自行判斷是否該靈活運用規範。若打破規則能讓說明更清楚，請放心這麼做！但要記住，這些規範都是有其目的的。

備註

手冊內容未必都遵循本指引。如果你正在修改段落或章節，請一併更新為符合這些標準。避免只為調整格式而做無關內容的變更，因為每次調整都會造成該段需重新翻譯。

文字樣式

手冊內容會使用幾種不同的樣式。

樣式	RST 格式	常見用途
純文字	text	用於一般文字。
斜體	*text*	強調語氣或介紹新術語時使用。
粗體	**text**	用於強調，也用於編輯器 UI（選單、視窗等）名稱。
程式碼	text	用於變數名稱、字面值、程式碼片段。許多原本以引號標示的內容也可改用 code 樣式。
「引號」	"text"	用於部分字串或引用值，但多數情況建議用其他樣式。

強調

強調時可用 粗體 或 斜體。一般來說，兩者擇一即可，依情境或頁面慣例決定。

單純強調時建議使用 粗體。

• 不要 未儲存就關閉視窗。

句中強調單一詞彙時可用 斜體。

• 你可以 新增 節點到場景（但不能連接一個節點）。

• 你可以新增 節點 到場景（但不能加上資源）。

• 你可以新增節點到 場景 （但不能加到資源）。

介紹新術語時可用 斜體，粗體 也可以。

• Godot 使用 節點 搭配 腳本 組成 場景樹。

• Godot 使用 節點 與 腳本 組成 場景樹。

字面值

字面值請用 程式碼樣式。常見字面值類型：

• 整數（int）字面值，如 0、-2、100

• 浮點數字面值，如 0.0、0.5、-2.0、100.0

• 向量字面值，如 (0.0, 0.0)、(0.5, -0.5, 0.5)、(1.0, 2.0, 3.0, 4.0)。

類別、屬性與方法

首次提及類別時請加連結，之後改用 程式碼樣式。常用類別（如 Node、Control、Viewport）可直接用純文字。

首次提及類別成員（屬性、方法、列舉、常數）時請加連結，之後用 程式碼樣式。若為常見成員（如 Node2D 的 position），則可省略連結。

若是在屬性檢視器（Inspector）內容中討論屬性，請用 粗體 樣式。

編輯器 UI

編輯器 UI（如視窗標題、選單、按鈕、輸入欄、檢視器屬性與區塊）請用 粗體，並遵照編輯器原本的大小寫。

• 開啟 Editor Settings 視窗。

• 按下 Confirm 按鈕。

• 將節點的 Transform > Position 屬性設為 (0, 0)。

• 在 Project Settings 視窗中啟用 Advanced Settings。

描述選單操作路徑時請用 粗體 > 加分隔符號，分隔符號為 >，選單名稱中的省略號可省略。

• 在 Project > Project Settings > Input Map 新增一個輸入動作。

• 選擇 Scene > Export As... > MeshLibrary...。

• 選擇 Scene > Export As > MeshLibrary。

備註

有時會看到用 -> 或 → 做分隔符，這不是標準格式。若有修改內容，請一併改為 >。

專案設定

連結到單一專案設定時，可將區段與子區段一起放進連結，或分開標示。由於長連結在頁面上不會自動換行，遇到很長的設定名稱時，建議將設定名稱與區段分開標記。

• 將 Application > Run > Max FPS 設定為 60。

• 於專案設定的 Application > Run 下，將 Max FPS 設為 60。

• 在 Project Settings > Application > Run 中，將 Max FPS 設為 60。

手動換行

手冊內容每行最多 80-100 字元需手動換行。但連結和表格可超過 100 字元且不可強制斷行。

做小修改時，若每行未超過 100 字元，不必整段重排。

錯誤： 行長超過 100 字元：

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.

良好： 每行換行於 80-90 字元：

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.

最佳： 每行不超過 80 字元換行：

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.

小訣竅

多數編輯器可設置 80 字元的「直尺」輔助線。例如 VS Code 可在 settings.json 加入如下內容，標示 80 與 100 字元：

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

章節標題語法

章節標題請用以下格式：

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.

目前無更深層次的標題巢狀，請避免新增更多層級。

請注意，標題本身不帶語意，reStructuredText 會依頁面首次出現順序解析。若使用 h3 標題（~~~），前面必須先有 h2 （---）。

更多資訊請見 Sphinx documentation 及 reStructuredText documentation。

何時應標示 Godot 版本

大多數情況下，類別參考和手冊不應標示功能首次加入的版本。這是因為文件描述的是*目前*的引擎功能。文件初版之後會跨多個版本被閱讀及維護，而首次支援版本的註明只在新增後幾個版本內有用，之後便成為歷史資訊，建議留給變更日誌。

如需標示 Godot 版本，請遵循以下原則：

• 若功能是當前主版（4.x）才加入， 可以標註 此為 4.x 新功能。

• 若功能或解決方式在主版間（如 3.x → 4.x）變更，正文應敘述當前功能，另可簡述與舊版比較。

• 若大型功能在 4.x 次版新增， 可以標示 加入的次版號。通常這會佔據一整頁或大章節，但大多數狀況下仍應避免，因為只對少數新舊版本有意義。

• 若小型功能在 4.x 次版新增， 不須標示 加入的次版號。這類功能通常只佔一小節，或僅為現有功能的小增補。

• 若解決方式在 4.x 次版變更預設， 應標示 變更的版本。例如 4.3 版將 TileMap 改為 TileMapLayer 。

• 功能若是在 3.x 版（主版或次版）新增， 不需標示 加入版本，這類功能已太舊，標示版號意義不大。