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

GDScript 文件註解

在 GDScript 中，註解可用於為你的程式碼撰寫說明文件，也能為腳本成員添加描述。普通註解和文件註解有兩個差異。首先，文件註解必須以雙井號 ## 開頭。其次，它必須緊接在腳本成員之前，或若是腳本說明則須放在腳本最上方。若有加上文件註解的匯出變數，其描述會在編輯器中顯示為工具提示。這些說明文件也可由編輯器匯出成 XML 檔案。

腳本文件撰寫方式

腳本說明文件註解必須寫在所有成員文件之前。建議的腳本說明格式可分三個部分。

• 腳本的簡短描述。

• 詳細描述。

• 教學連結，以及已棄用/實驗性註記。

為了分隔不同區塊，文件註解支援特殊標籤。標籤必須在行首（可忽略前導空白），格式為 @ 加上關鍵字。

標籤

簡要說明	無標籤。必須放在說明區塊的最開頭。
說明	無標籤。以一行空白分隔簡要與詳細描述。
教學	@tutorial: https://example.com @tutorial(此處填寫標題): https://example.com
已棄用	@deprecated @deprecated: 請改用 [AnotherClass]。
實驗性	@experimental @experimental: 此類別尚未穩定。

例如：

extends Node2D
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial:             https://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental

警告

若標籤名稱與冒號之間有空格（如 @tutorial  :），則此標籤無效會被忽略。

備註

當描述跨多行時，前後空白會被移除並以單一空格串接。若要保留換行請使用 [br] 。可參考下方的 BBCode 與類別參考 。

腳本成員文件化

可撰寫說明文件的成員有：

• 訊號

• 列舉

• 列舉值

• 常數

• 變數

• 函式

• 內部類別

腳本成員的文件註解必須緊接於該成員（或其註解）之前。描述可多行，但每行都必須以雙井號 ## 開頭才會被視為說明文件的一部分。

標籤

說明	無標籤。
已棄用	@deprecated @deprecated: 請改用 [member another]。
實驗性	@experimental @experimental: 此方法尚未完成。

例如：

## The description of the variable.
## @deprecated: Use [member other_var] instead.
var my_var

另外，你也可以使用行內說明註解：

signal my_signal ## My signal.

enum MyEnum { ## My enum.
    VALUE_A = 0, ## Value A.
    VALUE_B = 1, ## Value B.
}

const MY_CONST = 1 ## My constant.

var my_var ## My variable.


func my_func(): ## My func.
    pass


class MyClass: ## My class.
    pass

每當腳本更新時，說明文件會自動於編輯器的說明視窗中同步更新。若成員變數或函式名稱以底線開頭，將被視為私有成員，不會出現在文件裡，也不會顯示於說明視窗。

完整腳本範例

extends Node2D
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial:             https://example.com/tutorial_1
## @tutorial(Tutorial 2): https://example.com/tutorial_2
## @experimental

## The description of a signal.
signal my_signal

## This is a description of the below enum.
enum Direction {
    ## Direction up.
    UP = 0,
    ## Direction down.
    DOWN = 1,
    ## Direction left.
    LEFT = 2,
    ## Direction right.
    RIGHT = 3,
}

## The description of a constant.
const GRAVITY = 9.8

## The description of the variable v1.
var v1

## This is a multiline description of the variable v2.[br]
## The type information below will be extracted for the documentation.
var v2: int

## If the member has any annotation, the annotation should
## immediately precede it.
@export
var v3 := some_func()


## As the following function is documented, even though its name starts with
## an underscore, it will appear in the help window.
func _fn(p1: int, p2: String) -> int:
    return 0


# The below function isn't documented and its name starts with an underscore
# so it will treated as private and will not be shown in the help window.
func _internal() -> void:
    pass


## Documenting an inner class.
##
## The same rules apply here. The documentation must
## immediately precede the class definition.
##
## @tutorial: https://example.com/tutorial
## @experimental
class Inner:

    ## Inner class variable v4.
    var v4


    ## Inner class function fn.
    func fn(): pass

@deprecated 與 @experimental 標籤

你可以將類別或其任何成員標記為已棄用或實驗性，這樣在內建說明檢視器就會顯示對應的註記。也可以加上簡短說明，說明為何此 API 不建議使用。這對外掛或函式庫作者特別有幫助。

• 已棄用 標記表示此 API 未來主要版本可能移除或有不相容更動，通常僅為向下相容而保留。

• 實驗性 標記表示此 API 尚不穩定，可能於目前主要分支中變更或移除。不建議於正式產品程式中使用。

備註

雖然技術上可以同時在同一類別/成員上標註 @deprecated 及 @experimental，但這不符合慣例，不建議這麼做。

BBCode 與類別參考

Godot 的類別參考支援類似 BBCode 的標籤，可讓文字有更好格式，同樣能用於腳本說明文件。詳見 類別參考 BBCode。注意這與 RichTextLabel 的 BBCode 用法略有不同。

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

可用標籤如下：

標籤與說明	範例	結果
[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 作為尺寸。
[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.
[color] [/color] 顏色	[color=red]Error![/color]	Error!
[font] [/font] 字型	[font=res://mono.ttf]LICENSE[/font]	LICENSE
[img] [/img] 圖片	[img width=32]res://icon.svg[/img]
[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。
[codeblock] [/codeblock] 多行程式碼區塊	見下方。	見下方。

備註

1. 目前僅 @GDScript 有註解。

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

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

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

警告

請使用 [codeblock] 來標註預格式化程式碼區塊。在 [codeblock] 內請統一使用**四個空白**縮排（解析器會刪除 Tab）。

## Do something for this plugin. Before using the method
## you first have to [method initialize] [MyPlugin].[br]
## [color=yellow]Warning:[/color] Always [method clean] after use.[br]
## Usage:
## [codeblock]
## func _ready():
##     the_plugin.initialize()
##     the_plugin.do_something()
##     the_plugin.clean()
## [/codeblock]
func do_something():
    pass

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

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

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

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