類別參考入門

本頁將說明如何撰寫類別參考文件。你會學到應該在哪裡為 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`。

備註

有些支援的標籤（如 [color] 與 [font]）未在此列出，因為不建議在引擎文件中使用。
[kbd] 會停用 BBCode，直到解析器遇到 [/kbd] 為止。
[code] 會停用 BBCode，直到解析器遇到 [/code] 為止。

格式化程式碼區塊

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

如果你想為特定語言新增範例，請使用 [codeblock]。
如果你要同時提供 GDScript 與 C# 的範例，請使用 [codeblocks]、[gdscript] 及 [csharp] 標籤。

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

[codeblock lang=text] 不會進行語法高亮;
[codeblock lang=gdscript] 會高亮 GDScript 語法;
[codeblock lang=csharp] 會高亮 C# 語法（僅 .NET 版本適用）。

備註

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

警告

請用 [codeblock] 來標記預先格式化的程式碼區塊。區塊內縮排一律使用 四個空格，解析器會自動移除 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]

上述內容會顯示為：

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}

格式化注意事項與警告

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

[b]Note:[/b] Only available when using the Vulkan 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>