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 常量、函数、注解。

描述

GDScript 专用的实用函数及注解列表，可在任何脚本中访问。

全局函数和常量的列表见 @GlobalScope。

教程

• GDScript的导出

方法

Color	Color8 ( int r8, int g8, int b8, int a8=255 )
void	assert ( bool condition, String message="" )
String	char ( int char )
Variant	convert ( Variant what, int type )
Object	dict_to_inst ( Dictionary dictionary )
Array	get_stack ( )
Dictionary	inst_to_dict ( Object instance )
bool	is_instance_of ( Variant value, Variant type )
int	len ( Variant var )
Resource	load ( String path )
Resource	preload ( String path )
void	print_debug ( ... ) vararg
void	print_stack ( )
Array	range ( ... ) vararg
bool	type_exists ( StringName type )

---

常量

PI = 3.14159265358979

常量，表示圆的周长是直径的多少倍。相当于 TAU / 2，或以弧度表示的180度。

TAU = 6.28318530717959

圆常量，单位圆的周长，单位为弧度。相当于 PI * 2，即 360 度的弧度值。

INF = inf

正浮点无穷大。这是除数为 0.0 时浮点除法的结果。对于负无穷大，使用 -INF。如果分子为正，除以 -0.0 将导致负无穷大，因此除以 0.0 与除以 -0.0 不同（尽管 0.0 == -0.0 返回 true）。

警告：数值无穷大只是浮点数的一个概念，对于整数来说没有对应的概念。将整数除以 0 不会产生 INF，而是会产生一个运行时错误。

NAN = nan

“Not a Number”（非数），一个无效的浮点数值。NAN 有许多特殊的性质，比如 != 始终返回 true，而其他比较运算符都始终返回 false。即便是和自己比较也是如此（NAN == NAN 返回 false，而 NAN != NAN 返回 true）。部分无效运算会返回这个值，例如将浮点数 0.0 除以 0.0。

警告：“非数”只是浮点数的概念，整数中没有对应的概念。将整数 0 除以 0 不会得到 NAN，而是会产生运行时错误。

---

Annotations

@export ( )

将后续的属性标记为导出属性（可以在检查器面板中编辑并保存至磁盘）。要控制导出属性的类型，请使用类型提示标记。

extends Node

enum Direction {LEFT, RIGHT, UP, DOWN}

# 内置类型。
@export var string = ""
@export var int_number = 5
@export var float_number: float = 5

# 枚举。
@export var type: Variant.Type
@export var format: Image.Format
@export var direction: Direction

# 资源。
@export var image: Image
@export var custom_resource: CustomResource

# 节点。
@export var node: Node
@export var custom_node: CustomNode

# 类型数组。
@export var int_array: Array[int]
@export var direction_array: Array[Direction]
@export var image_array: Array[Image]
@export var node_array: Array[Node]

注意：自定义资源和自定义节点必须使用 class_name 注册为全局类。

注意：节点的导出只有派生自 Node 的类才支持，并且还有一些其他限制。

---

@export_category ( String name )

为后续导出属性定义一个新类别。方便在检查器面板中组织属性。

另见 @GlobalScope.PROPERTY_USAGE_CATEGORY。

@export_category("Statistics")
@export var hp = 30
@export var speed = 1.25

注意：检查器面板中的列表通常会按类别将来自不同类（如 Node、Node2D、Sprite 等）的属性分隔开来。为了更明确，推荐改用 @export_group 和 @export_subgroup。

---

@export_color_no_alpha ( )

导出一个 Color 属性，不允许编辑其透明度 (Color.a)。

另请参阅 @GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA 。

@export_color_no_alpha var dye_color: Color

---

@export_dir ( )

将 String 属性作为目录路径导出。该路径仅限于项目文件夹及其子文件夹。要允许在整个文件系统中进行选择，见 @export_global_dir。

另见 @GlobalScope.PROPERTY_HINT_DIR。

@export_dir var sprite_folder_path: String

---

@export_enum ( String names, ... ) vararg

将 int 或 String 导出为枚举选项列表。如果属性为 int，则保存的是值的索引，与值的顺序一致。你可以通过冒号添加显式值。如果属性为 String，则保存的是值。

另见 @GlobalScope.PROPERTY_HINT_ENUM。

@export_enum("Warrior", "Magician", "Thief") var character_class: int
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
@export_enum("Rebecca", "Mary", "Leah") var character_name: String

如果想要设置初始值，你必须进行显式指定：

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

如果想要使用 GDScript 枚举，请改用 @export：

enum CharacterName {REBECCA, MARY, LEAH}
@export var character_name: CharacterName

---

@export_exp_easing ( String hints="", ... ) vararg

使用缓动编辑器小部件导出浮点属性。可以提供额外的提示来调整小部件的行为。"attenuation" 翻转曲线，使编辑衰减属性更加直观。"positive_only" 将值限制为仅大于或等于零。

另请参见 @GlobalScope.PROPERTY_HINT_EXP_EASING。

@export_exp_easing var transition_speed
@export_exp_easing("attenuation") var fading_attenuation
@export_exp_easing("positive_only") var effect_power

---

@export_file ( String filter="", ... ) vararg

将 String 属性导出为文件路径。该路径仅限于项目文件夹及其子文件夹。若要允许从整个文件系统中进行选择，请参阅 @export_global_file。

如果提供了 filter，则只有匹配的文件可供选择。

另请参见 @GlobalScope.PROPERTY_HINT_FILE。

@export_file var sound_effect_file: String
@export_file("*.txt") var notes_file: String

---

@export_flags ( String names, ... ) vararg

将整数属性导出为位标志字段。能够在单个属性中保存若干“勾选”或者说 true 值，可以很方便地在检查器面板中进行选择。

另见 @GlobalScope.PROPERTY_HINT_FLAGS。

@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

你可以通过冒号来添加显式值：

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

你还可以对标志进行组合：

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

注意：标志值最多为 1，最多为 2 ** 32 - 1。

注意：与 @export_enum 不同，不会考虑前一个显式值。下面的例子中，A 为 16、B 为 2、C 为 4。

@export_flags("A:16", "B", "C") var x

---

@export_flags_2d_navigation ( )

将整数属性导出为 2D 导航层的位标志字段。检查器停靠面板中的小部件，将使用在 ProjectSettings.layer_names/2d_navigation/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION。

@export_flags_2d_navigation var navigation_layers: int

---

@export_flags_2d_physics ( )

将整数属性导出为 2D 物理层的位标志字段。检查器停靠面板中的小工具，将使用在 ProjectSettings.layer_names/2d_physics/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS。

@export_flags_2d_physics var physics_layers: int

---

@export_flags_2d_render ( )

将整数属性导出为 2D 渲染层的位标志字段。检查器停靠面板中的小工具将使用在 ProjectSettings.layer_names/2d_render/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER。

@export_flags_2d_render var render_layers: int

---

@export_flags_3d_navigation ( )

将整数属性导出为 3D 导航层的位标志字段。检查器停靠面板中的小工具将使用在 ProjectSettings.layer_names/3d_navigation/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION。

@export_flags_3d_navigation var navigation_layers: int

---

@export_flags_3d_physics ( )

将整数属性导出为 3D 物理层的位标志字段。检查器停靠面板中的小工具将使用在 ProjectSettings.layer_names/3d_physics/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS。

@export_flags_3d_physics var physics_layers: int

---

@export_flags_3d_render ( )

将整数属性导出为 3D 渲染层的位标志字段。检查器停靠面板中的小工具将使用在 ProjectSettings.layer_names/3d_render/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER。

@export_flags_3d_render var render_layers: int

---

@export_flags_avoidance ( )

将整数属性导出为导航避障层的位标志字段。检查器停靠面板中的小工具，将使用在 ProjectSettings.layer_names/avoidance/layer_1 中定义的层名称。

另请参见 @GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE。

@export_flags_avoidance var avoidance_layers: int

---

@export_global_dir ( )

将 String 属性导出为目录路径。该路径可以从整个文件系统中选择。请参阅 @export_dir 以将其限制为项目文件夹及其子文件夹。

另请参见 @GlobalScope.PROPERTY_HINT_GLOBAL_DIR。

@export_global_dir var sprite_folder_path: String

---

@export_global_file ( String filter="", ... ) vararg

将 String 属性作为文件路径导出。该路径可以在整个文件系统中进行选择。要将其限制为项目文件夹及其子文件夹，见 @export_file。

如果提供了 filter，则只有匹配的文件可供选择。

另见 @GlobalScope.PROPERTY_HINT_GLOBAL_FILE。

@export_global_file var sound_effect_path: String
@export_global_file("*.txt") var notes_path: String

---

@export_group ( String name, String prefix="" )

为以下导出的属性定义一个新分组。分组有助于在检查器面板中组织属性。添加新分组时可以选择性地提供 prefix 前缀，分组将仅考虑具有此前缀的属性。分组将在第一个没有该前缀的属性处结束。前缀也将从检查器面板中的属性名称中移除。

如果未提供 prefix，后续的每个属性都将添加到该分组中。定义下一个分组或类别时，该分组结束。你还可以通过将此注解与空字符串的参数一起使用来强制结束分组，@export_group("", "")。

分组不能嵌套，请使用 @export_subgroup 在分组内添加子分组。

另见 @GlobalScope.PROPERTY_USAGE_GROUP。

@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26

@export_group("Car Properties", "car_")
@export var car_label = "Speedy"
@export var car_number = 3

@export_group("", "")
@export var ungrouped_number = 3

---

@export_multiline ( )

用一个大的 TextEdit 部件而不是 LineEdit 导出一个 String 属性。这增加了对多行内容的支持，使其更容易编辑存储在属性中的大量文本。

参见 @GlobalScope.PROPERTY_HINT_MULTILINE_TEXT。

@export_multiline var character_biography

---

@export_node_path ( String type="", ... ) vararg

导出具有过滤器，并允许节点类型为 NodePath 的属性。

参见 @GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES。

@export_node_path("Button", "TouchScreenButton") var some_button

注意: 类型必须是本地类或全局注册的脚本（使用[class_name]关键字）且继承自 Node 。

---

@export_placeholder ( String placeholder )

导出一个带有一个占位符文本的 String 属性，当没有值时，编辑器小部件中会显示该占位符文本。

另请参见 @GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT。

@export_placeholder("Name in lowercase") var character_id: String

---

@export_range ( float min, float max, float step=1.0, String extra_hints="", ... ) vararg

将 int 或 float 属性导出为范围值。范围必须由 min 和 max 定义，还有一个可选的 step 和各种额外的提示。对于整数属性，step 的默认值是 1 。对于浮点数，这个值取决于你的 EditorSettings.interface/inspector/default_float_step 设置。

如果提供了提示 "or_greater" 和 "or_less" ，那么编辑器部件将不会在范围边界处对数值进行限制。"exp" 提示将使范围内的编辑值以指数形式变化。"hide_slider" 提示将隐藏编辑器部件中的滑块。

提示还允许指示编辑的值的单位。使用 "radians_as_degrees" ，你可以指定实际值以弧度为单位，但在检查器中会以角度为单位显示（范围值也使用度数）。"degrees" 允许添加一个角度符号作为单位后缀。最后，可以使用 "suffix:单位" 提供一个自定义后缀，其中“单位”可以是任何字符串。

另见 @GlobalScope.PROPERTY_HINT_RANGE。

@export_range(0, 20) var number
@export_range(-10, 20) var number
@export_range(-10, 20, 0.2) var number: float

@export_range(0, 100, 1, "or_greater") var power_percent
@export_range(0, 100, 1, "or_greater", "or_less") var health_delta

@export_range(-3.14, 3.14, 0.001, "radians_as_degrees") var angle_radians
@export_range(0, 360, 1, "degrees") var angle_degrees
@export_range(-8, 8, 2, "suffix:px") var target_offset

---

@export_subgroup ( String name, String prefix="" )

为接下来的导出属性定义一个新的子分组。有助于组织检查器面板中的属性。子分组的工作方式与分组类似，只是它们依赖于一个父级分组。见 @export_group。

另见 @GlobalScope.PROPERTY_USAGE_SUBGROUP。

@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26

@export_subgroup("Car Properties", "car_")
@export var car_label = "Speedy"
@export var car_number = 3

注意：子分组不能嵌套，它们只提供一层额外的深度。新的分组会结束前一个分组，类似地，后续的子分组也会打断之前的子分组。

---

@icon ( String icon_path )

为当前脚本添加自定义图标。icon_path 所指定的图标会在“场景”面板中该类的所有节点上显示，也会显示在各种编辑器对话框中。

@icon("res://path/to/class/icon.svg")

注意：只有脚本可以有自定义的图标。不支持内部类。

注意：由于注解描述的是它们的对象，@icon 注解必须放在类定义和继承之前。

注意：不同于其他注解，@icon 注解的参数必须是字符串字面量（不支持常量表达式）。

---

@onready ( )

标记后续属性会在 Node 的就绪状态时赋值。节点初始化（Object._init）时不会立即对这些属性赋值，而是会在即将调用 Node._ready 之前进行计算和保存。

@onready var character_name: Label = $Label

---

@rpc ( String mode="authority", String sync="call_remote", String transfer_mode="unreliable", int transfer_channel=0 )

将后续方法标记为远程过程调用。见《高阶多人游戏》。

如果将 mode 设为 "any_peer"，则会允许所有对等体调用该 RPC 函数。否则就只允许该对等体的控制方调用，此时应该让 mode 保持为 "authority"。使用 Node.rpc_config 将函数配置为 RPC 时，这些模式对应的是 RPC 模式 MultiplayerAPI.RPC_MODE_AUTHORITY 和 MultiplayerAPI.RPC_MODE_ANY_PEER。如果非控制方的对等体尝试调用仅限控制方调用的函数，则不会执行该函数。如果本地能够检测到错误（本地与远程对等体的 RPC 配置一致），则发送方对等体会显示错误消息。否则远程对等体会检测到该错误并输出错误。

如果将 sync 设为 "call_remote"，则该函数只会在远程对等体上执行，不会在本地执行。要让这个函数在本地也执行，请将 sync 设置为 "call_local"。使用 Node.rpc_config 将函数配置为 RPC 时，等价于将 call_local 设置为 true。

transfer_mode 能够接受的值为 "unreliable"、"unreliable_ordered"、"reliable"，会设置底层 MultiplayerPeer 的传输模式。见 MultiplayerPeer.transfer_mode。

transfer_channel 定义的是底层 MultiplayerPeer 的通道。见 MultiplayerPeer.transfer_channel。

mode、sync 和 transfer_mode 的顺序是无关的，但是相同参数的取值不能出现多次。transfer_channel 必须始终为第四个参数（前三个参数必须指定）。

@rpc
func fn(): pass

@rpc("any_peer", "unreliable_ordered")
func fn_update_pos(): pass

@rpc("authority", "call_remote", "unreliable", 0) # 等价于 @rpc
func fn_default(): pass

---

@static_unload ( )

使具有静态变量的脚本在所有引用丢失之后不会持久化。当该脚本再次加载时，这些静态变量将恢复为默认值。

---

@tool ( )

将当前脚本标记为工具脚本，允许它被编辑器加载和执行。见《在编辑器中运行代码》。

@tool
extends Node

注意：因为注解描述对象的关系，必须把 @tool 注解放在类定义和继承之前。

---

@warning_ignore ( String warning, ... ) vararg

将后续语句标记为忽略指定的 warning 警告。见《GDScript 警告系统》。

func test():
    print("你好")
    return
    @warning_ignore("unreachable_code")
    print("无法到达")

---

方法说明

Color Color8 ( int r8, int g8, int b8, int a8=255 )

返回一个由整数红通道（r8）、绿通道（g8）、蓝通道（b8）和可选的 Alpha 通道（a8）构造的 Color，每个通道的最终值都会除以 255.0。如果你需要精确匹配 Image 中的颜色值，Color8 比标准的 Color 构造函数更有用。

var red = Color8(255, 0, 0)             # 与 Color(1, 0, 0) 相同
var dark_blue = Color8(0, 0, 51)        # 与 Color(0, 0, 0.2) 相同。
var my_color = Color8(306, 255, 0, 102) # 与 Color(1.2, 1, 0, 0.4) 相同。

注意：因为 Color8 比标准 Color 构造函数精度更低，所以使用 Color8 创建的颜色通常与使用标准 Color 构造函数创建的相同颜色不相等。请使用 Color.is_equal_approx 进行比较，避免浮点数精度误差。

---

void assert ( bool condition, String message="" )

断言条件 condition 为 true。如果条件 condition 为 false ，则会生成错误。如果是从编辑器运行的，正在运行的项目还会被暂停，直到手动恢复。该函数可以作为 @GlobalScope.push_error 的加强版，用于向项目开发者和插件用户报错。

如果给出了可选的 message 参数，该信息会和通用的“Assertion failed”消息一起显示。你可以使用它来提供关于断言失败原因的其他详细信息。

警告：出于对性能的考虑，assert 中的代码只会在调试版本或者从编辑器运行项目时执行。请勿在 assert 调用中加入具有副作用的代码。否则，项目在以发布模式导出后将有不一致的行为。

# 比如说我们希望 speed 始终在 0 和 20 之间。
speed = -10
assert(speed < 20) # True，程序会继续执行
assert(speed >= 0) # False，程序会停止
assert(speed >= 0 and speed < 20) # 你还可以在单次检查中合并两个条件语句
assert(speed < 20, "限速为 20") # 显示消息。

---

String char ( int char )

返回给定的 Unicode 码位（与ASCII码兼容）的单字符字符串（作为一个String）。

a = char(65)      # a 是“A”
a = char(65 + 32) # a 是“a”
a = char(8364)    # a 是“€”

---

Variant convert ( Variant what, int type )

已弃用。请改用 @GlobalScope.type_convert。

在可能的情况下将 what 转换为 type 。 type 使用 Variant.Type 值。

var a = [4, 2.5, 1.2]
print(a is Array) # 输出 true

var b = convert(a, TYPE_PACKED_BYTE_ARRAY)
print(b)          # 输出 [4, 2, 1]
print(b is Array) # 输出 false

---

Object dict_to_inst ( Dictionary dictionary )

将一个 dictionary （用 inst_to_dict 创建的）转换回为一个 Object 实例。在反序列化时可能很有用。

---

Array get_stack ( )

返回一个表示当前调用堆栈的字典数组。另请参阅 print_stack。

func _ready():
    foo()

func foo():
    bar()

func bar():
    print(get_stack())

从 _ready() 开始，bar() 将打印：

[{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]

注意：只有在运行的实例连接到调试服务器（即编辑器实例）后，该函数才有效。get_stack 不适用于以发布模式导出的项目；或者在未连接到调试服务器的情况下，以调试模式导出的项目。

注意：不支持从 Thread 调用此函数。这样做将返回一个空数组。

---

Dictionary inst_to_dict ( Object instance )

返回传入的 instance 转换为的字典。可用于序列化。

注意：不能用于序列化附加了内置脚本的对象，或在内置脚本中分配的对象。

var foo = "bar"
func _ready():
    var d = inst_to_dict(self)
    print(d.keys())
    print(d.values())

输出：

[@subpath, @path, foo]
[, res://test.gd, bar]

---

bool is_instance_of ( Variant value, Variant type )

如果 value 为 type 类型的实例，则返回 true。type 的值必须为下列值之一：

• Variant.Type 枚举常量，例如 @GlobalScope.TYPE_INT。

• ClassDB 中存在的派生自 Object 的类，例如 Node。

• Script（可以用任何类，包括内部类）。

type 可以不是常量，这一点与 is 的右操作数不同。is 运算符支持的功能更多（例如类型化数组），性能也更高。如果你不需要动态类型检查，请使用该运算符，不要使用此方法。

示例：

print(is_instance_of(a, TYPE_INT))
print(is_instance_of(a, Node))
print(is_instance_of(a, MyClass))
print(is_instance_of(a, MyClass.InnerClass))

注意：如果 value 和/或 type 为已释放的对象（见 @GlobalScope.is_instance_valid），或者 type 不是以上选项之一，则此方法会报运行时错误。

另见 @GlobalScope.typeof、type_exists、Array.is_same_typed（以及其他 Array 方法）。

---

int len ( Variant var )

返回给定 Variant var 的长度。长度可以是 String 的字符数、任意数组类型的元素数、或 Dictionary 的大小等。对于所有其他 Variant 类型，都会生成运行时错误并停止执行。

a = [1, 2, 3, 4]
len(a) # 返回 4

b = "Hello!"
len(b) # 返回 6

---

Resource load ( String path )

返回一个位于文件系统绝对路径 path 的 Resource。除非该资源已在其他地方引用（例如在另一个脚本或场景中），否则资源是在函数调用时从磁盘加载的——这可能会导致轻微的延迟，尤其是在加载大型场景时。为避免在多次加载某些内容时出现不必要的延迟，可以将资源存储在变量中或使用预加载 preload。

注意：资源路径可以通过右键单击文件系统停靠面板中的资源并选择“复制路径”，或将文件从文件系统停靠面板拖到脚本中获得。

# 加载位于项目根目录的一个名为“main”的场景，并将其缓存在一个变量中。
var main = load("res://main.tscn") # main 将包含一个 PackedScene 资源。

重要提示：路径必须是绝对路径。相对路径将始终返回 null。

这个方法是 ResourceLoader.load 的简化版，原方法可以用于更高级的场景。

注意：必须先将文件导入引擎才能使用此函数加载它们。如果你想在运行时加载 Image，你可以使用 Image.load。如果要导入音频文件，可以使用 AudioStreamMP3.data 中描述的代码片段。

注意：如果 ProjectSettings.editor/export/convert_text_resources_to_binary 为 true，则 load 无法在导出后的项目中读取已转换的文件。如果你需要在运行时加载存在于 PCK 中的文件，请将 ProjectSettings.editor/export/convert_text_resources_to_binary 设置为 false。

---

Resource preload ( String path )

返回一个位于文件系统绝对路径path 的 Resource。在运行时，该资源将在解析脚本时加载。实际可以将这个函数视作对该资源的引用。请注意，此函数要求 path 为 String常量。如果要从动态、可变路径加载资源，请使用 load。

注意：资源路径可以通过右键单击资产面板中的资源并选择“复制路径”，或通过将文件从文件系统停靠面板拖到脚本中来获得。

# 创建场景的实例。
var diamond = preload("res://diamond.tscn").instantiate()

---

void print_debug ( ... ) vararg

与 @GlobalSco