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 內建節點型別的類別、方法及屬性新增說明。

也參考

若要學習如何使用 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 檔案。

備註

對於引擎原始碼中的部分模組，你會在 modules/<module_name>/doc_classes/ 資料夾中找到 XML 檔案。

請用你喜歡的文字編輯器編輯這些檔案。若使用程式碼編輯器，請確保不要改變縮排格式：XML 應使用 Tab 字元縮排，BBCode 樣式區塊內則應使用四個空白縮排。詳情請見下方說明。

要確認你的修改在產生的文件中是否正確，請進入 doc/ 資料夾並執行 make rst 指令。這會將 XML 檔案轉換為線上文件格式，若有錯誤會顯示錯誤訊息。

你也可以編譯 Godot，並在內建的類別參考中開啟你修改過的頁面。如需學習如何編譯引擎，請參考 compilation guide。

建議你使用支援 XML 的程式碼編輯器，例如 Vim、Atom、Visual Studio Code、Notepad++ 等，以方便地編輯檔案。也可以利用搜尋功能快速找到類別與屬性。

小訣竅

如果你使用 Visual Studio Code，可安裝 vscode-xml 擴充套件 來檢查類別參考 XML 檔案的格式。

使用 BBCode 樣式標籤改善格式

Godot 的 XML 類別參考支援類似 BBCode 的標籤，可用於連結與格式化文字或程式碼。下表列出了可用標籤、用法範例及轉換為 reStructuredText 後的結果。

連結

當你要連結到其他類別的成員時，需要寫上類別名稱。若是連結到同一類別的成員，類別名稱可省略。

標籤與說明	範例	結果
[Class] 連結至類別	移動 [Sprite2D]。	移動 Sprite2D。
[annotation Class.name] 連結至註解	請參閱 [annotation @GDScript.@rpc]。	請參閱 @GDScript.@rpc。
[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]Always[/u] use this method.	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]。	按下 Ctrl + C。
[code] [/code] 行內程式碼片段	回傳 [code]true[/code]。	回傳 true。

備註

1. 有些支援的標籤（如 [color] 與 [font]）未在此列出，因為不建議在引擎文件中使用。

2. [kbd] 會停用 BBCode，直到解析器遇到 [/kbd] 為止。

3. [code] 會停用 BBCode，直到解析器遇到 [/code] 為止。

格式化程式碼區塊

有兩種方式可以格式化程式碼區塊：

1. 如果你想為特定語言新增範例，請使用 [codeblock]。

2. 如果你要同時提供 GDScript 與 C# 的範例，請使用 [codeblocks]、[gdscript] 及 [csharp] 標籤。

預設情況下，[codeblock] 會高亮顯示 GDScript 語法。你可以透過 lang 屬性來更改，目前支援的選項有：

• [codeblock lang=text] 不會進行語法高亮;

• [codeblock lang=gdscript] 會高亮 GDScript 語法;

• [codeblock lang=csharp] 會高亮 C# 語法（僅 .NET 版本適用）。

備註

[codeblock] 會停用 BBCode，直到解析器遇到 [/codeblock] 為止。

警告

請用 [codeblock] 來標記預先格式化的程式碼區塊。自 Godot 4.5 起，縮排應使用 Tab。

例如：

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

格式化注意事項與警告

若要標示重要資訊，請在說明最後加入以「[b]Note:[/b]」開頭的段落：

[b]Note:[/b] Only available when using the Forward+ 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 為已棄用／實驗性

若要標記 API 為已棄用或實驗性，請在 XML 中加入對應屬性。屬性值必須是說明該 API 為何不推薦使用的訊息（支援 BBCode 標記），或為空字串（將顯示預設訊息）。若 API 元素已被標記為已棄用／實驗性，即使說明為空也視為已有文件。

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