Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

類別參照手冊

本頁面將介紹如何編寫類參考手冊。你會學到去哪裡為 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 的原始碼中瞭解這些功能各自如何運作，並填寫相應的 <descrioption>。

你會想要在 Godot 的原始程式碼中學習它們都有什麼用。然後補全或者完善這些標籤中的文字：

<brief_description>
說明
PI（圓周率）常數。
<method>`（在其 `<description> 標籤中；返回型別和參數不帶單獨的文件字串）
<member>
<signal>`（在其 `<description> 標籤中；參數不帶單獨的文件字串）
PI（圓周率）常數。

請以清晰明瞭的文字撰寫。務必遵守撰寫方針以保持說明簡短且容易閱讀。在簡介中 請不要保留空行 ：在 XML 檔中每一行都會開新段落。

如果編輯類別 XML

請編輯 doc/classes/ 內所選類別的檔案來更新類別參照文件。該資料夾包含了用於各個類別的 XML 檔。這些 XML 中列出了可在類別參照文件中找到的常數與方法。Godot 會自動產生並更新 XML 檔。

備註

遊戲引擎中某些模組的 XML 檔在 modules/<模組名稱>/doc_classes/ 目錄下。

使用慣用的編輯器開啟 XML 檔。若使用程式碼編輯器，請確保不要更改到縮排樣式：XML 使用 Tab 資源，BBCode 風格的區塊中則使用 4 個空格。詳情見下方說明。

要檢查你所做出的修改在生成後的文件中是否正確，請在 doc/ 資料夾中執行命令 make rst。這樣就會將 XML 檔轉換為線上文件的格式，存在錯誤時會有錯誤報告。

你也可以自行建構 Godot 然後在內建的類參考手冊中打開被修改的頁面。引擎的編譯方法請查看 compilation guide。

請使用 Vim, Atom, Code, Notepad++ 或其他類似的編輯器來快速編輯檔案。可使用搜尋功能來快速找到類別。

小訣竅

如果您使用 Visual Studio Code，則可以安裝 vscode-xml 擴充 <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml> 來糾察 XML 檔案的類引用。

使用 BBCode 風格的標籤來增強格式

Godot 的 XML 類引用支援類似 BBCode 的標記，用於連結以及格式化文字和程式碼。在下表中，您可以找到可用的標記、用法範例以及轉換為 reStructuredText 後的結果。

光照烘焙

每當連結到另一個類別的成員時，都需要指定類別名稱。對於指向同一類別的鏈接，類別名稱是可選的並且可以省略。

說明	範例	結果
`[Class]` 類別連結	移動 [Sprite]。	移動 class_sprite。
`[註解類別名]` 另一個類別的方法連結	`See [annotation @GDScript.@rpc].`	See @GDScript.@rpc.
[signal 類別.訊號名稱] 定義一個常數。	`See [constant Color.RED].`	See Color.RED.
[member 類別.成員名稱] 同意授權條款	`參見[列舉Mesh.ArrayType]。`	請參閱:ref:Mesh.ArrayType <enum_Mesh_ArrayType>。
[member 類別.成員名稱] 編輯成員	取得 [member Node2D.scale]。	取得 scale 。
[method 類別.方法名稱] 繫結方法	呼叫 [method hide]。	參考 hide 。
`[constructor Class.name]` Link to built-in constructor	`Use [constructor Color.Color].`	Use Color.Color.
`[operator Class.name]` Link to built-in operator	`Use [operator Color.operator *].`	Use Color.operator *.
[signal 類別.訊號名稱] 繫結訊號	發送 [signal Node.renamed]。	發送 renamed。
[method 類別.方法名稱] 同意授權條款	`參見[theme_item Label.font]。`	請參閱:ref:Label.font <class_Label_theme_font_font>。
`name` Parameter name (as code)	“採用 [param size] 作為大小。”	採用“size”作為尺寸。

備註

目前只有 @GDScript 有注解。

格式

說明	範例	結果
`[br]` break	`第 1 行。[br]` `第 2 行。`	1號線。 2號線。
`[lb]` `[rb]` `[` and `]` respectively	`[lb]b[rb]text[lb]/b[rb]`	[b]text[/b]
[b] [/b] 粗體	`Do [b]not[/b] call this method.`	Do not call this method.
[i] [/i] 斜體	`Returns the [i]global[/i] position.`	Returns the global position.
`[u]` `[/u]` Underline	`[u]Always[/u] use this method.`	Always use this method.
`[s]` `[/s]` Strikethrough	`[s]Outdated information.[/s]`	~~Outdated information.~~
`[url]` `[/url]` Hyperlink	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Website
`[center]` `[/center]` Horizontal centering	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` 鍵盤或滑鼠快捷鍵	`Press [kbd]Ctrl + C[/kbd].`	Press `Ctrl + C`.
`[code]` `[/code]` Inline code fragment	`Returns [code]true[/code].`	Returns `true`.

備註

Some supported tags like [color] and [font] are not listed here because they are not recommended in the engine documentation.
[kbd] 停用 BBCode，直到解析器遇到 [/kbd]。
[code] 停用 BBCode，直到解析器遇到 [/code]。

Formatting code blocks

There are two options for formatting code blocks:

Use [codeblock] if you want to add an example for a specific language.
Use [codeblocks], [gdscript], and [csharp] if you want to add the same example for both languages, GDScript and C#.

By default, [codeblock] highlights GDScript syntax. You can change it using the lang attribute. Currently supported options are:

[codeblock lang=text] disables syntax highlighting;
[codeblock lang=gdscript] highlights GDScript syntax;
[codeblock lang=csharp] highlights C# syntax (only in .NET version).

備註

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

警告

使用 [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 程式碼範例！你可以使用這個`實驗性的程式碼翻譯工具 <https://github.com/HaSa1002/codetranslator>`_來加速工作流程。

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

Formatting notes and warnings

若要標記出重要的資訊，可在說明最後新增以「[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 標籤中的一部分，請保持一致性。

Marking API as deprecated/experimental

To mark an API as deprecated or experimental, you need to add the corresponding XML attribute. The attribute value must be a message explaining why the API is not recommended (BBCode markup is supported) or an empty string (the default message will be used). If an API element is marked as deprecated/experimental, then it is considered documented even if the description is empty.

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