:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/4.3/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/4.3/modules/gdscript/doc_classes/@GDScript.xml. .. _class_@GDScript: @GDScript ========= 内置 GDScript 常量、函数、注解。 .. rst-class:: classref-introduction-group 描述 ---- GDScript 专用的实用函数及注解列表，可在任何脚本中访问。 全局函数和常量的列表见 :ref:`@GlobalScope`\ 。 .. rst-class:: classref-introduction-group 教程 ---- - :doc:`GDScript 的导出 <../tutorials/scripting/gdscript/gdscript_exports>` .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`Color8`\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`assert`\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`char`\ (\ char\: :ref:`int`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`dict_to_inst`\ (\ dictionary\: :ref:`Dictionary`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`get_stack`\ (\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`inst_to_dict`\ (\ instance\: :ref:`Object`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_instance_of`\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`len`\ (\ var\: :ref:`Variant`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`load`\ (\ path\: :ref:`String`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`preload`\ (\ path\: :ref:`String`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`print_debug`\ (\ ...\ ) |vararg| | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`print_stack`\ (\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`range`\ (\ ...\ ) |vararg| | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`type_exists`\ (\ type\: :ref:`StringName`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 常量 ---- .. _class_@GDScript_constant_PI: .. rst-class:: classref-constant **PI** = ``3.14159265358979`` :ref:`🔗` 常量，表示圆的周长是直径的多少倍。相当于 ``TAU / 2``\ ，即 180 度旋转。 .. _class_@GDScript_constant_TAU: .. rst-class:: classref-constant **TAU** = ``6.28318530717959`` :ref:`🔗` 圆常量，单位圆的周长，单位为弧度。相当于 ``PI * 2``\ ，即 360 度旋转。 .. _class_@GDScript_constant_INF: .. rst-class:: classref-constant **INF** = ``inf`` :ref:`🔗` 正浮点无穷大。这是除数为 ``0.0`` 时浮点除法的结果。对于负无穷大，使用 ``-INF``\ 。如果分子为正，除以 ``-0.0`` 将导致负无穷大，因此除以 ``0.0`` 与除以 ``-0.0`` 不同（尽管 ``0.0 == -0.0`` 返回 ``true``\ ）。 \ **警告：**\ 数值无穷大只是浮点数的一个概念，对于整数来说没有对应的概念。将整数除以 ``0`` 不会产生 :ref:`INF`\ ，而是会产生一个运行时错误。 .. _class_@GDScript_constant_NAN: .. rst-class:: classref-constant **NAN** = ``nan`` :ref:`🔗` “Not a Number”（非数），一个无效的浮点数值。\ :ref:`NAN` 有许多特殊的性质，比如 ``!=`` 始终返回 ``true``\ ，而其他比较运算符都始终返回 ``false``\ 。即便是和自己比较也是如此（\ ``NAN == NAN`` 返回 ``false``\ ，而 ``NAN != NAN`` 返回 ``true``\ ）。部分无效运算会返回这个值，例如将浮点数 ``0.0`` 除以 ``0.0``\ 。 \ **警告：**\ “非数”只是浮点数的概念，整数中没有对应的概念。将整数 ``0`` 除以 ``0`` 不会得到 :ref:`NAN`\ ，而是会产生运行时错误。 .. rst-class:: classref-section-separator ---- 注解 ---- .. _class_@GDScript_annotation_@export: .. rst-class:: classref-annotation **@export**\ (\ ) :ref:`🔗` 将后续的属性标记为导出属性（可以在检查器面板中编辑并保存至磁盘）。要控制导出属性的类型，请使用类型提示标记。 :: 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`` 注册为全局类，因为属性检查器目前仅支持全局类。否则，将导出不太具体的类型。 \ **注意：**\ 节点的导出只有派生自 :ref:`Node` 的类才支持，并且还有一些其他限制。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_category: .. rst-class:: classref-annotation **@export_category**\ (\ name\: :ref:`String`\ ) :ref:`🔗` 为后续导出属性定义一个新类别，方便在检查器面板中组织属性。 另见 :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY`\ 。 :: @export_category("Statistics") @export var hp = 30 @export var speed = 1.25 \ **注意：**\ 检查器面板中的列表通常会按类别将来自不同类（如 Node、Node2D、Sprite 等）的属性分隔开来。为了让属性组织更明确，推荐改用 :ref:`@export_group` 和 :ref:`@export_subgroup`\ 。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_color_no_alpha: .. rst-class:: classref-annotation **@export_color_no_alpha**\ (\ ) :ref:`🔗` 导出 :ref:`Color`\ 、\ :ref:`Array`\ \[:ref:`Color`\ \] 或 :ref:`PackedColorArray` 属性，不允许编辑透明度（\ :ref:`Color.a`\ ）。 另见 :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA`\ 。 :: @export_color_no_alpha var dye_color: Color @export_color_no_alpha var dye_colors: Array[Color] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_custom: .. rst-class:: classref-annotation **@export_custom**\ (\ hint\: :ref:`PropertyHint`, hint_string\: :ref:`String`, usage\: |bitfield|\[:ref:`PropertyUsageFlags`\] = 6\ ) :ref:`🔗` 允许为导出的属性设置自定义提示、提示字符串、和使用标志。请注意，GDScript 中没有进行任何验证，它只是将参数传递给编辑器。 :: @export_custom(PROPERTY_HINT_NONE, "suffix:m") var suffix: Vector3 \ **注意：**\ 无论 ``usage`` 值如何，总会添加 :ref:`@GlobalScope.PROPERTY_USAGE_SCRIPT_VARIABLE` 标志，就像和任何显式声明的脚本变量一样。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_dir: .. rst-class:: classref-annotation **@export_dir**\ (\ ) :ref:`🔗` 导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \] 或 :ref:`PackedStringArray` 属性，用作指向目录的路径。该路径会被限制在项目文件夹及其子文件夹中，要允许在整个文件系统中选取，见 :ref:`@export_global_dir`\ 。 另见 :ref:`@GlobalScope.PROPERTY_HINT_DIR`\ 。 :: @export_dir var sprite_folder_path: String @export_dir var sprite_folder_paths: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_enum: .. rst-class:: classref-annotation **@export_enum**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` 导出 :ref:`int`\ 、\ :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`int`\ \]、\ :ref:`Array`\ \[:ref:`String`\ \]、\ :ref:`PackedByteArray`\ 、\ :ref:`PackedInt32Array`\ 、\ :ref:`PackedInt64Array` 或 :ref:`PackedStringArray` 属性，用作枚举选项列表（或选项的数组）。如果属性为 :ref:`int`\ ，则存储的是值的索引，与值的顺序相同。你可以使用冒号来显式添加枚举项的取值。如果属性为 :ref:`String`\ ，则存储的是值。 另见 :ref:`@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("Sword", "Spear", "Mace") var character_items: Array[int] @export_enum("double_jump", "climb", "dash") var character_skills: Array[String] 如果需要设置初始值，则必须显式指定： :: @export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca" 如果需要使用具名 GDScript 枚举，请改用 :ref:`@export`\ ： :: enum CharacterName {REBECCA, MARY, LEAH} @export var character_name: CharacterName enum CharacterItem {SWORD, SPEAR, MACE} @export var character_items: Array[CharacterItem] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_exp_easing: .. rst-class:: classref-annotation **@export_exp_easing**\ (\ hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` 使用缓动编辑器小部件导出浮点属性。可以提供额外的提示来调整小部件的行为。通过使用\ ``"attenuation"`` 提示来翻转曲线，使编辑衰减属性更加直观；通过使用\ ``"positive_only"`` 提示来将取值范围限制为仅大于等于零。 另见 :ref:`@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_exp_easing var speeds: Array[float] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_file: .. rst-class:: classref-annotation **@export_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` 导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \[ 或 :ref:`PackedStringArray` 属性，用作指向文件的路径。该路径会被限制在项目文件夹及其子文件夹中。要允许在整个文件系统中选取，见 :ref:`@export_global_file`\ 。 如果提供了 ``filter``\ ，则只有匹配的文件可供选取。 另见 :ref:`@GlobalScope.PROPERTY_HINT_FILE`\ 。 :: @export_file var sound_effect_path: String @export_file("*.txt") var notes_path: String @export_file var level_paths: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags: .. rst-class:: classref-annotation **@export_flags**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` 将整数属性导出为位标志字段，能够在单个属性中保存多个“勾选项”（即 ``true`` 值），可以很方便地在检查器面板中进行选择。 另见 :ref:`@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``\ 。 \ **注意：**\ 与 :ref:`@export_enum` 不同，位标志不会考虑其前一个位标志的显式值。下面的例子中，A 为 16、B 为 2、C 为 4。 :: @export_flags("A:16", "B", "C") var x 还可以对 :ref:`Array`\ \[:ref:`int`\ \]、\ :ref:`PackedByteArray`\ 、\ :ref:`PackedInt32Array` 和 :ref:`PackedInt64Array` 使用该注解。 :: @export_flags("Fire", "Water", "Earth", "Wind") var phase_elements: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_2d_navigation: .. rst-class:: classref-annotation **@export_flags_2d_navigation**\ (\ ) :ref:`🔗` 将整数属性导出为 2D 导航层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/2d_navigation/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION`\ 。 :: @export_flags_2d_navigation var navigation_layers: int @export_flags_2d_navigation var navigation_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_2d_physics: .. rst-class:: classref-annotation **@export_flags_2d_physics**\ (\ ) :ref:`🔗` 将整数属性导出为 2D 物理层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/2d_physics/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS`\ 。 :: @export_flags_2d_physics var physics_layers: int @export_flags_2d_physics var physics_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_2d_render: .. rst-class:: classref-annotation **@export_flags_2d_render**\ (\ ) :ref:`🔗` 将整数属性导出为 2D 渲染层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/2d_render/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER`\ 。 :: @export_flags_2d_render var render_layers: int @export_flags_2d_render var render_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_3d_navigation: .. rst-class:: classref-annotation **@export_flags_3d_navigation**\ (\ ) :ref:`🔗` 将整数属性导出为 3D 导航层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/3d_navigation/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION`\ 。 :: @export_flags_3d_navigation var navigation_layers: int @export_flags_3d_navigation var navigation_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_3d_physics: .. rst-class:: classref-annotation **@export_flags_3d_physics**\ (\ ) :ref:`🔗` 将整数属性导出为 3D 物理层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/3d_physics/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS`\ 。 :: @export_flags_3d_physics var physics_layers: int @export_flags_3d_physics var physics_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_3d_render: .. rst-class:: classref-annotation **@export_flags_3d_render**\ (\ ) :ref:`🔗` 将整数属性导出为 3D 渲染层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/3d_render/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER`\ 。 :: @export_flags_3d_render var render_layers: int @export_flags_3d_render var render_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_flags_avoidance: .. rst-class:: classref-annotation **@export_flags_avoidance**\ (\ ) :ref:`🔗` 将整数属性导出为导航避障层的位标志字段。检查器面板中对应的部件会使用在 :ref:`ProjectSettings.layer_names/avoidance/layer_1` 中定义的层名称。 另见 :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE`\ 。 :: @export_flags_avoidance var avoidance_layers: int @export_flags_avoidance var avoidance_layers_array: Array[int] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_global_dir: .. rst-class:: classref-annotation **@export_global_dir**\ (\ ) :ref:`🔗` 导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \] 或 :ref:`PackedStringArray` 属性，用作指向目录的绝对路径，该路径可以从整个文件系统中选取。要限制为项目文件夹及其子文件夹，见 :ref:`@export_dir`\ 。 另见 :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR`\ 。 :: @export_global_dir var sprite_folder_path: String @export_global_dir var sprite_folder_paths: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_global_file: .. rst-class:: classref-annotation **@export_global_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` 导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \] 或 :ref:`PackedStringArray` 属性，用作指向文件的绝对路径，该路径可以从整个文件系统中选取。要限制为项目文件夹及其子文件夹，见 :ref:`@export_file`\ 。 如果提供了 ``filter``\ ，则只有匹配的文件可供选取。 另见 :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE`\ 。 :: @export_global_file var sound_effect_path: String @export_global_file("*.txt") var notes_path: String @export_global_file var multiple_paths: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_group: .. rst-class:: classref-annotation **@export_group**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` 为以下导出的属性定义一个新分组，分组有助于在检查器面板中组织属性。添加新分组时可以选择性地提供 ``prefix`` 前缀，此时分组将仅考虑具有此前缀的属性。分组将在第一个没有该前缀的属性处结束，前缀也将从检查器面板中的属性名称当中移除。 如果未提供 ``prefix``\ ，则该注解后续的每个属性都将添加到该分组中，在定义下一个分组或类别时，该分组结束。你还可以通过将此注解与空字符串的参数一起使用来强制结束分组：\ ``@export_group("", "")``\ 。 分组不能嵌套使用，请使用 :ref:`@export_subgroup` 在分组内添加子分组。 另见 :ref:`@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 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_multiline: .. rst-class:: classref-annotation **@export_multiline**\ (\ ) :ref:`🔗` 代替普通的 :ref:`LineEdit` 组件，并使用较大的 :ref:`TextEdit` 组件来导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \]、\ :ref:`PackedStringArray`\ 、\ :ref:`Dictionary` 或 :ref:`Array`\ \[:ref:`Dictionary`\ \] 属性，这样就能够支持编辑多行内容，便于在编辑属性中存储大量文本。 另见 :ref:`@GlobalScope.PROPERTY_HINT_MULTILINE_TEXT`\ 。 :: @export_multiline var character_biography @export_multiline var npc_dialogs: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_node_path: .. rst-class:: classref-annotation **@export_node_path**\ (\ type\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` 导出 :ref:`NodePath` 或 :ref:`Array`\ \[:ref:`NodePath`\ \] 属性，能够指定要过滤的节点类型。 另见 :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES`\ 。 :: @export_node_path("Button", "TouchScreenButton") var some_button @export_node_path("Button", "TouchScreenButton") var many_buttons: Array[NodePath] \ **注意：**\ 类型必须是原生类型或（通过使用 ``[class_name]`` 关键字）全局注册的继承自 :ref:`Node` 的脚本。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_placeholder: .. rst-class:: classref-annotation **@export_placeholder**\ (\ placeholder\: :ref:`String`\ ) :ref:`🔗` 导出 :ref:`String`\ 、\ :ref:`Array`\ \[:ref:`String`\ \] 或 :ref:`PackedStringArray` 属性，当值不存在时会在编辑器小部件中显示占位文本。 另见 :ref:`@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT`\ 。 :: @export_placeholder("Name in lowercase") var character_id: String @export_placeholder("Name in lowercase") var friend_ids: Array[String] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_range: .. rst-class:: classref-annotation **@export_range**\ (\ min\: :ref:`float`, max\: :ref:`float`, step\: :ref:`float` = 1.0, extra_hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` 导出 :ref:`int`\ 、\ :ref:`float`\ 、\ :ref:`Array`\ \[:ref:`int`\ \]、\ :ref:`Array`\ \[:ref:`float`\ \]、\ :ref:`PackedByteArray`\ 、\ :ref:`PackedInt32Array`\ 、\ :ref:`PackedInt64Array`\ 、\ :ref:`PackedFloat32Array` 或 :ref:`PackedFloat64Array` 属性，能够指定取值范围。范围必须由最小值提示 ``min`` 和最大值提示 ``max`` 定义，还有一个可选的步长提示 ``step`` 和各种额外的提示。对于整数属性，\ ``step`` 的默认值是 ``1`` 。对于浮点数，这个值取决于你的 :ref:`EditorSettings.interface/inspector/default_float_step` 所设置的值。 如果提供了 ``"or_greater"`` 和 ``"or_less"`` 提示，则编辑器部件将不会在其范围边界处对数值进行限制。\ ``"exp"`` 提示将使范围内的编辑值以指数形式变化。\ ``"hide_slider"`` 提示可将编辑器部件中的滑块隐藏。 提示还允许指示编辑的值的单位。通过使用 ``"radians_as_degrees"`` 提示，你可以指定实际值以弧度为单位，在检查器中以角度为单位显示的值（其范围值也使用角度）。\ ``"degrees"`` 提示允许添加一个角度符号作为单位后缀。最后，还可以使用 ``"suffix:单位"`` 这种提示来提供一个自定义后缀，其中“单位”可以是任意字符串。 另见 :ref:`@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, 20) var numbers: Array[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(-180, 180, 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 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_storage: .. rst-class:: classref-annotation **@export_storage**\ (\ ) :ref:`🔗` 使用 :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` 标志导出属性，让该属性不会在编辑器中显示，但是会将其序列化并存储到场景或资源文件中。常用于 :ref:`@tool` 脚本当中。调用 :ref:`Resource.duplicate` 和 :ref:`Node.duplicate` 时也会复制该属性的值，而其他非导出变量则不会。 :: var a # 不保存进文件，不在编辑器中显示。 @export_storage var b # 保存进文件，不在编辑器中显示。 @export var c: int # 保存进文件，在编辑器中显示。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@export_subgroup: .. rst-class:: classref-annotation **@export_subgroup**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` 为接下来的导出属性定义一个新的子分组，有助于在检查器面板中组织属性。子分组的运作方式与分组类似，不过需要依赖于一个父级分组。见 :ref:`@export_group`\ 。 另见 :ref:`@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 \ **注意：**\ 子分组不能嵌套，仅提供一层额外的分组深度。新的分组会结束前一个分组，类似地，后续的子分组也会打断之前的子分组。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@icon: .. rst-class:: classref-annotation **@icon**\ (\ icon_path\: :ref:`String`\ ) :ref:`🔗` 为当前脚本添加自定义图标。\ ``icon_path`` 所指向的图标会在“场景”面板中该类的所有节点上显示，也会显示在各种编辑器对话框当中。 :: @icon("res://path/to/class/icon.svg") \ **注意：**\ 只有脚本可以带有自定义图标，不支持内部类。 \ **注意：**\ 由于注解描述的是它们的对象，因此 :ref:`@icon` 注解必须放在类定义语句和继承语句之前。 \ **注意：**\ 与其他注解不同，\ :ref:`@icon` 注解的参数必须是字符串字面量（不支持常量表达式）。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@onready: .. rst-class:: classref-annotation **@onready**\ (\ ) :ref:`🔗` 标记后续属性会在 :ref:`Node` 就绪时赋值。节点初始化（\ :ref:`Object._init`\ ）时不会立即对这些属性赋值，而是会在即将调用 :ref:`Node._ready` 之前进行计算与储存。 :: @onready var character_name: Label = $Label .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@rpc: .. rst-class:: classref-annotation **@rpc**\ (\ mode\: :ref:`String` = "authority", sync\: :ref:`String` = "call_remote", transfer_mode\: :ref:`String` = "unreliable", transfer_channel\: :ref:`int` = 0\ ) :ref:`🔗` 将后续方法标记为远程过程调用。见\ :doc:`《高阶多人游戏》 <../tutorials/networking/high_level_multiplayer>`\ 。 如果将 ``mode`` 提示设为 ``"any_peer"``\ ，则会允许所有对等体调用该 RPC 函数。若只允许该对等体的控制方调用，则应该让 ``mode`` 提示保持为 ``"authority"``\ 。使用 :ref:`Node.rpc_config` 将函数配置为 RPC 时，这些模式分别对应的是 RPC 模式 :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER` 和 :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY` 。如果非控制方的对等体尝试调用仅限控制方调用的函数，则不会执行该函数，且如果本地能够检测到错误（本地与远程对等体的 RPC 配置一致），则发送方对等体会显示错误消息，否则该对等体会检测到该错误并将其输出。 如果将 ``sync`` 提示设为 ``"call_remote"``\ ，则该函数只会在远程对等体上执行，不会在本地执行。要让这个函数在本地也能够执行，请将 ``sync`` 设置为 ``"call_local"``\ ，使用 :ref:`Node.rpc_config` 将函数配置为 RPC 时，等价于将 ``call_local`` 设置为 ``true``\ 。 \ ``transfer_mode`` 提示能够接受的值为 ``"unreliable"``\ 、\ ``"unreliable_ordered"``\ 、\ ``"reliable"``\ ，会设置底层 :ref:`MultiplayerPeer` 的传输模式。见 :ref:`MultiplayerPeer.transfer_mode`\ 。 \ ``transfer_channel`` 定义的是底层 :ref:`MultiplayerPeer` 的通道。见 :ref:`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 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@static_unload: .. rst-class:: classref-annotation **@static_unload**\ (\ ) :ref:`🔗` 使具有静态变量的脚本在所有引用丢失后不持久化。如果再次加载脚本，静态变量将恢复为默认值。 \ **注意：**\ 因为注解需要描述对象，所以 :ref:`@static_unload` 注解必须放在类定义和继承之前。 \ **警告：**\ 目前由于一个 bug，即使使用了\ :ref:`@static_unload` 注解，脚本也永远不会释放。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@tool: .. rst-class:: classref-annotation **@tool**\ (\ ) :ref:`🔗` 将当前脚本标记为工具脚本，允许该脚本由编辑器所加载与执行。见\ :doc:`《在编辑器中运行代码》 <../tutorials/plugins/running_code_in_the_editor>`\ 。 :: @tool extends Node \ **注意：**\ 因为注解描述对象的关系，必须把 :ref:`@tool` 注解放在类定义和继承之前。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@warning_ignore: .. rst-class:: classref-annotation **@warning_ignore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` 将后续语句标记为忽略指定的 ``warning`` 警告。见\ :doc:`《GDScript 警告系统》 <../tutorials/scripting/gdscript/warning_system>`\ 。 :: func test(): print("你好") return @warning_ignore("unreachable_code") print("无法到达") .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法说明 -------- .. _class_@GDScript_method_Color8: .. rst-class:: classref-method :ref:`Color` **Color8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) :ref:`🔗` 返回一个由整数红通道（\ ``r8``\ ）、整数绿通道（\ ``g8``\ ）、整数蓝通道（\ ``b8``\ ）和可选的整数 Alpha 通道（\ ``a8``\ ）构造的 :ref:`Color`\ ，每个通道的最终值都会除以 ``255.0``\ 。如果你需要精确匹配 :ref:`Image` 中的颜色值，\ :ref:`Color8` 比标准的 :ref:`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) 相同。 \ **注意：**\ 由于 :ref:`Color8` 比标准 :ref:`Color` 构造函数精度更低，故使用 :ref:`Color8` 创建的颜色通常与使用标准 :ref:`Color` 构造函数创建的相同颜色不相等。请使用 :ref:`Color.is_equal_approx` 进行比较，避免浮点数精度误差。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_assert: .. rst-class:: classref-method |void| **assert**\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) :ref:`🔗` 断言条件 ``condition`` 为 ``true``\ 。如果条件 ``condition`` 为 ``false`` ，则会生成错误。如果是从编辑器运行的断言，正在运行的项目还会被暂停，需要手动恢复。该函数可以作为 :ref:`@GlobalScope.push_error` 的加强版使用，用于向项目开发者和插件用户报错。 如果给出了可选的 ``message`` 参数，该信息会和通用的“Assertion failed”消息一起显示。你可以使用它来提供关于断言失败原因等详细信息。 \ **警告：**\ 出于对性能的考虑，\ :ref:`assert` 中的代码只会在调试版本或者从编辑器运行项目时执行。请勿在 :ref:`assert` 调用中加入具有副作用的代码。否则，项目在以发布模式导出后将会出现行为不一致的现象。 :: # 比如说我们希望 speed 始终在 0 和 20 之间。 speed = -10 assert(speed < 20) # True，程序会继续执行 assert(speed >= 0) # False，程序会停止 assert(speed >= 0 and speed < 20) # 你还可以在单次检查中合并两个条件语句 assert(speed < 20, "限速为 20") # 显示消息。 \ **注意：**\ :ref:`assert` 是关键字而非函数，无法作为 :ref:`Callable` 访问，也无法在表达式中使用。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_char: .. rst-class:: classref-method :ref:`String` **char**\ (\ char\: :ref:`int`\ ) :ref:`🔗` 返回给定的 Unicode 码位（与ASCII码兼容）的单字符字符串（作为一个\ :ref:`String`\ ）。 :: a = char(65) # a 是“A” a = char(65 + 32) # a 是“a” a = char(8364) # a 是“€” .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_convert: .. rst-class:: classref-method :ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) :ref:`🔗` **已弃用：** Use :ref:`@GlobalScope.type_convert` instead. 在可能的情况下将 ``what`` 转换为 ``type`` 类型的值， ``type`` 使用 :ref:`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 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_dict_to_inst: .. rst-class:: classref-method :ref:`Object` **dict_to_inst**\ (\ dictionary\: :ref:`Dictionary`\ ) :ref:`🔗` 将一个 ``dictionary`` （用 :ref:`inst_to_dict` 创建的）转换回为一个 Object 实例。在反序列化时可能会很有用。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_get_stack: .. rst-class:: classref-method :ref:`Array` **get_stack**\ (\ ) :ref:`🔗` 返回一个表示当前调用堆栈的字典数组，另请参阅 :ref:`print_stack`\ 。 :: func _ready(): foo() func foo(): bar() func bar(): print(get_stack()) 从 ``_ready()`` 开始，\ ``bar()`` 将打印： .. code:: text [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] \ **注意：**\ 只有在运行的实例连接到调试服务器（即编辑器实例）后，该函数才有效。\ :ref:`get_stack` 不适用于以发布模式导出的项目；或者在未连接到调试服务器的情况下，以调试模式导出的项目。 \ **注意：**\ 不支持从 :ref:`Thread` 调用此函数，这样做将返回一个空数组。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_inst_to_dict: .. rst-class:: classref-method :ref:`Dictionary` **inst_to_dict**\ (\ instance\: :ref:`Object`\ ) :ref:`🔗` 将传入的 ``instance`` 转换为字典，并将该字典返回，可用于序列化。 \ **注意：**\ 不能用于序列化附加了内置脚本的对象，也不能用于序列化在内置脚本中分配的对象。 :: var foo = "bar" func _ready(): var d = inst_to_dict(self) print(d.keys()) print(d.values()) 输出： .. code:: text [@subpath, @path, foo] [, res://test.gd, bar] .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_is_instance_of: .. rst-class:: classref-method :ref:`bool` **is_instance_of**\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) :ref:`🔗` 如果 ``value`` 为 ``type`` 类型的实例，则返回 ``true``\ 。\ ``type`` 的值必须为下列值之一： - :ref:`Variant.Type` 枚举常量，如 :ref:`@GlobalScope.TYPE_INT`\ 。 - :ref:`ClassDB` 中存在的派生自 :ref:`Object` 的类，如 :ref:`Node`\ 。 - :ref:`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`` 为已释放的对象（见 :ref:`@GlobalScope.is_instance_valid`\ ），或者 ``type`` 的数值不为以上选项中的任何一项，则此方法会报运行时错误。 另见 :ref:`@GlobalScope.typeof`\ 、\ :ref:`type_exists`\ 、\ :ref:`Array.is_same_typed`\ （以及其他 :ref:`Array` 方法）。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_len: .. rst-class:: classref-method :ref:`int` **len**\ (\ var\: :ref:`Variant`\ ) :ref:`🔗` 返回给定 Variant ``var`` 的长度，该长度可以是 :ref:`String` 或 :ref:`StringName` 的字符数，也可以是任意数组类型的元素数或 :ref:`Dictionary` 的大小等。对于所有其他 Variant 类型，都会生成运行时错误并停止执行。 :: a = [1, 2, 3, 4] len(a) # 返回 4 b = "Hello!" len(b) # 返回 6 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_load: .. rst-class:: classref-method :ref:`Resource` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` 返回一个位于文件系统绝对路径 ``path`` 下的 :ref:`Resource`\ 。该资源除非已在其他地方引用（例如在另一个脚本或场景中），否则将在函数调用时从磁盘加载，可能会导致轻微的延迟，尤其是在加载大型场景时。为避免在多次加载某些内容时出现不必要的延迟，可以将资源存储在变量中，也可使用预加载 :ref:`preload` 方法加载，该方法相当于使用 :ref:`ResourceLoader.CACHE_MODE_REUSE` 模式调用 :ref:`ResourceLoader.load`\ 。 \ **注意：**\ 资源路径可以通过右键单击文件系统停靠面板中的资源并选择“复制路径”，或将文件从文件系统停靠面板拖到脚本中获得。 :: # 加载位于项目根目录的一个名为“main”的场景，并将其缓存在一个变量中。 var main = load("res://main.tscn") # main 将包含一个 PackedScene 资源。 \ **重要：**\ 相对路径相对的\ *不是*\ 调用该方法的脚本，而是会使用 ``"res://"`` 前缀。加载时使用相对路径可能与预期行为不符。 这个方法是 :ref:`ResourceLoader.load` 的简化版，原方法可以用于更高级的场景。 \ **注意：**\ 必须先将文件导入引擎才能使用此函数加载它们。如果你想在运行时加载 :ref:`Image`\ ，你可以使用 :ref:`Image.load`\ 。如果要导入音频文件，可以使用 :ref:`AudioStreamMP3.data` 中描述的代码片段。 \ **注意：**\ 如果 :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` 为 ``true``\ ，则 :ref:`load` 无法在导出后的项目中读取已转换的文件。如果你需要在运行时加载存在于 PCK 中的文件，请将 :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` 设置为 ``false``\ 。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_preload: .. rst-class:: classref-method :ref:`Resource` **preload**\ (\ path\: :ref:`String`\ ) :ref:`🔗` 返回一个位于文件系统绝对路径 ``path`` 的 :ref:`Resource`\ 。运行时，该资源将在解析脚本时加载，实际上可以将这个函数视作对该资源的引用。请注意：此函数要求 ``path`` 为 :ref:`String` 常量。如果要动态/可变的路径加载资源，请使用 :ref:`load`\ 。 \ **注意：**\ 资源路径可以通过右键单击资产面板中的资源并选择“复制路径”，或通过将文件从文件系统停靠面板拖到脚本中来获得。 :: # 创建场景的实例。 var diamond = preload("res://diamond.tscn").instantiate() \ **注意：**\ :ref:`preload` 是关键字而非函数，无法作为 :ref:`Callable` 访问。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_print_debug: .. rst-class:: classref-method |void| **print_debug**\ (\ ...\ ) |vararg| :ref:`🔗` 与 :ref:`@GlobalScope.print` 类似，但在打开调试器运行时还会包含当前栈帧。 控制台中的输出应该是类似这样的： .. code:: text Test print At: res://test.gd:15:_process() \ **注意：**\ 不支持从 :ref:`Thread` 中调用此方法，这样做会输出线程 ID。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_print_stack: .. rst-class:: classref-method |void| **print_stack**\ (\ ) :ref:`🔗` 输出当前代码位置的栈追踪。另请参阅 :ref:`get_stack`\ 。 控制台中的输出是类似这样的： .. code:: text Frame 0 - res://test.gd:16 in function '_process' \ **注意：**\ 只有在运行的实例连接到调试服务器（即编辑器实例）后，该函数才有效。\ :ref:`print_stack` 不适用于以发布模式导出的项目；或者在未连接到调试服务器的情况下，以调试模式导出的项目。 \ **注意：**\ 不支持从 :ref:`Thread` 调用此函数，这样做将改为打印线程 ID。 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_range: .. rst-class:: classref-method :ref:`Array` **range**\ (\ ...\ ) |vararg| :ref:`🔗` 返回具有给定范围的数组。\ :ref:`range` 可以通过三种方式调用： \ ``range(n: int)``\ ：从 0 开始，每次加 1，在到达 ``n`` *之前*\ 停止。\ **不包含**\ 参数 ``n``\ 。 \ ``range(b: int, n: int)``\ ：从 ``b`` 开始，每次加 1，在到达 ``n`` *之前*\ 停止。\ **包含**\ 参数 ``b``\ ，\ **不包含**\ 参数 ``n``\ 。 \ ``range(b: int, n: int, s: int)``\ ：从 ``b`` 开始，以 ``s`` 为步长递增/递减，在到达 ``n`` *之前*\ 停止。\ **包含**\ 参数 ``b``\ ，\ **不包含**\ 参数 ``n``\ 。参数 ``s`` **可以**\ 为负数，但不能为 ``0``\ 。如果 ``s`` 为 ``0``\ ，则会输出一条错误消息。 \ :ref:`range` 会先将所有参数转换为 :ref:`int` 再进行处理。 \ **注意：**\ 如果没有满足条件的值，则返回空数组（例如 ``range(2, 5, -1)`` 和 ``range(5, 5, 1)``\ ）。 示例： :: print(range(4)) # 输出 [0, 1, 2, 3] print(range(2, 5)) # 输出 [2, 3, 4] print(range(0, 6, 2)) # 输出 [0, 2, 4] print(range(4, 1, -1)) # 输出 [4, 3, 2] 要反向遍历 :ref:`Array`\ ，请使用： :: var array = [3, 6, 9] for i in range(array.size() - 1, -1, -1): print(array[i]) 输出： .. code:: text 9 6 3 要遍历 :ref:`float`\ ，请在循环中进行转换。 :: for i in range (3, 0, -1): print(i / 10.0) 输出： .. code:: text 0.3 0.2 0.1 .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_type_exists: .. rst-class:: classref-method :ref:`bool` **type_exists**\ (\ type\: :ref:`StringName`\ ) :ref:`🔗` 如果 :ref:`ClassDB` 中存在给定的 :ref:`Object` 派生类，则返回 ``true``\ 。请注意，\ :ref:`Variant` 数据类型未在 :ref:`ClassDB` 中注册。 :: type_exists("Sprite2D") # 返回 true type_exists("NonExistentClass") # 返回 false .. |virtual| replace:: :abbr:`virtual (本方法通常需要用户覆盖才能生效。)` .. |const| replace:: :abbr:`const (本方法无副作用，不会修改该实例的任何成员变量。)` .. |vararg| replace:: :abbr:`vararg (本方法除了能接受在此处描述的参数外，还能够继续接受任意数量的参数。)` .. |constructor| replace:: :abbr:`constructor (本方法用于构造某个类型。)` .. |static| replace:: :abbr:`static (调用本方法无需实例，可直接使用类名进行调用。)` .. |operator| replace:: :abbr:`operator (本方法描述的是使用本类型作为左操作数的有效运算符。)` .. |bitfield| replace:: :abbr:`BitField (这个值是由下列位标志构成位掩码的整数。)` .. |void| replace:: :abbr:`void (无返回值。)`