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 中，註解可用於記錄程式碼並為腳本成員新增描述。普通註釋和文件註釋之間有兩個區別。首先，文件註解應以雙散列符號「##」開頭。其次，它必須緊接在腳本成員之前，或者對於腳本描述，應放置在腳本的頂部。如果記錄了匯出的變量，則其描述將用作編輯器中的工具提示。該檔案可以由編輯器產生為 XML 檔案。

執行腳本

記錄腳本的註解必須位於任何成員檔案之前。腳本檔案的建議格式可以分為三個部分。

• 資源的文字描述.

• 說明

• 教學和已放棄使用/實驗標記。

為了將它們彼此分開，檔案註釋使用特殊標籤。標記必須位於行的開頭（忽略前面的空格），並且必須採用格式“@”，後面跟著關鍵字。

標籤

Brief description	沒有標籤。位於文件部分的開頭。
說明	沒有標籤。使用一個空白行將描述與摘要分開。
文字教學	@tutorial: https://example.com @tutorial(The Title Here): https://example.com
重複	@deprecated @deprecated: Use [AnotherClass] instead.
實驗性	@experimental @experimental: This class is unstable.

如：

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 和類別參考”。

建立腳本樣板

適用於檔案的成員：

• 訊號

• Enum 列舉型別

• 列舉值

• 常數

• 變數

• 函式

• 內類別

腳本成員的文件必須緊接在該成員或其註解（如果有）之前。描述可以有多於一行，但每一行必須以雙井號「##」開頭才能被視為檔案的一部分。

標籤

說明	沒有標籤。
重複	@deprecated @deprecated: Use [member another] instead.
實驗性	@experimental @experimental: This method is incomplete.

如：

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

Alternatively, you can use inline documentation comments:

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

每次更新腳本時，腳本檔案都會在編輯器說明視窗中更新。如果任何成員變數或函式名稱以下劃線開頭，它將被視為私有。它不會出現在檔案中，並且在說明視窗中將被忽略。

GDScript 範例

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

You can mark a class or any of its members as deprecated or experimental. This will add the corresponding indicator in the built-in documentation viewer. Optionally, you can provide a short message explaining why the API is not recommended. This can be especially useful for plugin and library creators.

• 已放棄使用 標記不建議的 API，可能會在未來的主要版本中刪除或進行不相容的更改。通常保留 API 是為了向後相容。

• **實驗性**旗標著一個新的不穩定 API，可能會在目前主要分支中變更或刪除。不建議在生產程式碼中使用此 API。

備註

雖然從技術上講，您可以在同一類/成員上使用“@deprecated”和“@experimental”標籤，但不建議這樣做，因為它違反了常見約定。

類別參照手冊

Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also be used in the documentation. See also class reference bbcode. Note that this is slightly different from the RichTextLabel BBCode.

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

有六種搜尋模式：

說明	範例	結果
[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 類別.成員名稱] Link to member (property)	取得 [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”作為尺寸。
[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.
[color] [/color] 顏色	[color=red]Error![/color]	Error!
[font] [/font] Font	[font=res://mono.ttf]LICENSE[/font]	LICENSE
[img] [/img] Image	[img width=32]res://icon.svg[/img]
[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.
[codeblock] [/codeblock] Multiline code block	參見下方。	參見下方。

備註

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

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