Up to date

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

Object

派生: AudioServer, CameraServer, ClassDB, DisplayServer, EditorFileSystemDirectory, EditorInterface, EditorPaths, EditorSelection, EditorUndoRedoManager, EditorVCSInterface, Engine, EngineDebugger, GDExtensionManager, Geometry2D, Geometry3D, GodotSharp, Input, InputMap, IP, JavaClassWrapper, JavaScriptBridge, JNISingleton, JSONRPC, MainLoop, Marshalls, MovieWriter, NavigationMeshGenerator, NavigationServer2D, NavigationServer3D, Node, OpenXRExtensionWrapperExtension, OpenXRInteractionProfileMetadata, OS, Performance, PhysicsDirectBodyState2D, PhysicsDirectBodyState3D, PhysicsDirectSpaceState2D, PhysicsDirectSpaceState3D, PhysicsServer2D, PhysicsServer2DManager, PhysicsServer3D, PhysicsServer3DManager, PhysicsServer3DRenderingServerHandler, ProjectSettings, RefCounted, RenderingDevice, RenderingServer, ResourceLoader, ResourceSaver, ResourceUID, ScriptLanguage, TextServerManager, ThemeDB, TileData, Time, TranslationServer, TreeItem, UndoRedo, WorkerThreadPool, XRServer

引擎中所有其他类的基类。

描述

一种高级的 Variant 类型。引擎中的所有类都继承自 Object。每个类都可以定义新的属性、方法或信号,并且这些对所有继承的类都可用。例如,一个 Sprite2D 实例能够调用 Node.add_child 因为它继承自 Node

可以使用 GDScript 中的 Object.new() 或 C# 中的 new GodotObject 来创建新实例。

要删除一个 Object 实例,请调用 free。这对于大多数继承 Object 的类来说是必须的,因为它们本身并不管理内存,如果不调用该方法的话,在不再使用时会造成内存泄漏。有几个类会执行内存管理。例如,RefCounted(以及扩展的 Resource)在不再被引用时删除自身,而 Node 在释放时会删除其子节点。

对象可以附加一个 Script。一旦该 Script 被实例化,它就有效地充当了基类的扩展,允许它定义和继承新的属性、方法和信号。

Script 中,_get_property_list 可以被可以重写,以通过多种方式自定义属性。这允许它们对编辑器可用,显示为选项列表,细分为组,保存在磁盘上,等等。脚本语言提供更简单的方式来自定义属性,例如使用 @GDScript.@export 注解。

Godot 是非常动态的。一个对象的脚本,以及它的属性、方法和信号,都可以在运行时改变。正因为如此,可能会出现这样的情况,例如,一个方法所需的属性可能不存在。为了防止运行时出错,可以参考 setgetcallhas_methodhas_signal 等方法。请注意,这些方法比直接引用慢得多

在 GDScript 中,还可以使用 in 运算符来检查对象中是否存在给定的属性、方法或信号名称:

var node = Node.new()
print("name" in node)         # 输出 true
print("get_parent" in node)   # 输出 true
print("tree_entered" in node) # 输出 true
print("unknown" in node)      # 输出 false

通知是 int 常量,通常由对象发送和接收。例如,在每个渲染帧上,SceneTree 使用 Node.NOTIFICATION_PROCESS 通知树内的节点。节点收到它后,可以调用 Node._process 进行更新。要使用通知,请参阅 notification_notification

最后,每个对象还可以包含元数据(关于数据的数据)。set_meta 可用于存储对象本身不依赖的信息。为了保持代码整洁,不鼓励过度使用元数据。

注意:与对 RefCounted 的引用不同,对存储在变量中的对象的引用,可能会在未被设置为 null 的情况下变得无效。要检查对象是否已被删除,请不要将其与 null 进行比较。而是使用 @GlobalScope.is_instance_valid。存储数据的类,建议从 RefCounted 继承而不是 Object

注意:script 不像大多数属性那样公开。要在代码中设置或获取一个对象的 Script,请分别使用 set_scriptget_script

教程

方法

Variant

_get ( StringName property ) virtual

Dictionary[]

_get_property_list ( ) virtual

void

_init ( ) virtual

void

_notification ( int what ) virtual

bool

_property_can_revert ( StringName property ) virtual

Variant

_property_get_revert ( StringName property ) virtual

bool

_set ( StringName property, Variant value ) virtual

String

_to_string ( ) virtual

void

_validate_property ( Dictionary property ) virtual

void

add_user_signal ( String signal, Array arguments=[] )

Variant

call ( StringName method, ... ) vararg

Variant

call_deferred ( StringName method, ... ) vararg

Variant

callv ( StringName method, Array arg_array )

bool

can_translate_messages ( ) const

void

cancel_free ( )

Error

connect ( StringName signal, Callable callable, int flags=0 )

void

disconnect ( StringName signal, Callable callable )

Error

emit_signal ( StringName signal, ... ) vararg

void

free ( )

Variant

get ( StringName property ) const

String

get_class ( ) const

Dictionary[]

get_incoming_connections ( ) const

Variant

get_indexed ( NodePath property_path ) const

int

get_instance_id ( ) const

Variant

get_meta ( StringName name, Variant default=null ) const

StringName[]

get_meta_list ( ) const

Dictionary[]

get_method_list ( ) const

Dictionary[]

get_property_list ( ) const

Variant

get_script ( ) const

Dictionary[]

get_signal_connection_list ( StringName signal ) const

Dictionary[]

get_signal_list ( ) const

bool

has_meta ( StringName name ) const

bool

has_method ( StringName method ) const

bool

has_signal ( StringName signal ) const

bool

has_user_signal ( StringName signal ) const

bool

is_blocking_signals ( ) const

bool

is_class ( String class ) const

bool

is_connected ( StringName signal, Callable callable ) const

bool

is_queued_for_deletion ( ) const

void

notification ( int what, bool reversed=false )

void

notify_property_list_changed ( )

bool

property_can_revert ( StringName property ) const

Variant

property_get_revert ( StringName property ) const

void

remove_meta ( StringName name )

void

set ( StringName property, Variant value )

void

set_block_signals ( bool enable )

void

set_deferred ( StringName property, Variant value )

void

set_indexed ( NodePath property_path, Variant value )

void

set_message_translation ( bool enable )

void

set_meta ( StringName name, Variant value )

void

set_script ( Variant script )

String

to_string ( )

String

tr ( StringName message, StringName context="" ) const

String

tr_n ( StringName message, StringName plural_message, int n, StringName context="" ) const


信号

property_list_changed ( )

调用 notify_property_list_changed 时发出。


script_changed ( )

该对象的脚本发生改变时发出。

注意:发出这个信号时,新脚本还没有初始化。如果你需要访问新脚本,请用 CONNECT_DEFERRED 推迟与这个信号的连接。


枚举

enum ConnectFlags:

ConnectFlags CONNECT_DEFERRED = 1

延迟连接会在空闲时触发 Callable(当前帧的末尾),不会立即触发。

ConnectFlags CONNECT_PERSIST = 2

持久连接会在序列化对象时存储(比如使用 PackedScene.pack 时)。在编辑器中,通过“节点”面板创建的连接总是持久的。

ConnectFlags CONNECT_ONE_SHOT = 4

一次性连接,会在触发后自行断开。

ConnectFlags CONNECT_REFERENCE_COUNTED = 8

引用计数连接可以多次分配给同一个 Callable。每断开一次连接会让内部计数器减一。信号会在计数器变为 0 时完全断开连接。


常量

NOTIFICATION_POSTINITIALIZE = 0

该对象初始化时收到的通知,发生在附加脚本之前。内部使用。

NOTIFICATION_PREDELETE = 1

该对象即将被删除时收到的通知。可以当作其他编程语言中的析构函数。


方法说明

Variant _get ( StringName property ) virtual

覆盖该方法以自定义 get 的行为。应该返回给定的 property 的值,或者 property 应该被正常处理时返回 null

结合 _set_get_property_list,该方法允许定义自定义属性,这对编辑器插件特别有用。请注意,属性必须存在于 get_property_list 中,否则该方法不会被调用。

func _get(property):
    if property == "fake_property":
        print("正在获取我的属性!")
        return 4

func _get_property_list():
    return [
        { "name": "fake_property", "type": TYPE_INT }
    ]

Dictionary[] _get_property_list ( ) virtual

覆盖该方法以自定义引擎处理脚本属性的方式。

应该返回一个属性列表,作为字典的 Array。该结果被添加到 get_property_list 的数组中,并且应该以相同的方式进行格式化。每个 Dictionary 必须至少包含 nametype 条目。

以下示例仅在 holding_hammertrue 时,在检查器停靠面板中显示 hammer_type

@tool
extends Node2D

@export var holding_hammer = false:
    set(value):
        holding_hammer = value
        notify_property_list_changed()
var hammer_type = 0

func _get_property_list():
    # 默认情况下,`hammer_type` 在编辑器中不可见。
    var property_usage = PROPERTY_USAGE_NO_EDITOR

    if holding_hammer:
        property_usage = PROPERTY_USAGE_DEFAULT

    var properties = []
    properties.append({
        "name": "hammer_type",
        "type": TYPE_INT,
        "usage": property_usage, # 参见上面的赋值。
        "hint": PROPERTY_HINT_ENUM,
        "hint_string": "Wooden,Iron,Golden,Enchanted"
    })

    return properties

注意:该方法旨在用于高级目的。对于大多数常见用例,脚本语言提供了更简单的方法来处理属性。参见 @GDScript.@export@GDScript.@export_enum@GDScript.@export_group、等。

注意:如果该对象的脚本不是 @GDScript.@tool,则该方法在编辑器中不会被调用。


void _init ( ) virtual

实例化对象的脚本时调用,通常是在对象在内存中初始化之后(通过 GDScript 中的 Object.new() 或 C# 中的 new GodotObject)。也可以将其定义为接受参数的形式。该方法类似于大多数编程语言中的构造函数。

注意:如果为 _init 定义了必填的参数,则带脚本的 Object 只能直接创建。使用任何其他方式(例如 PackedScene.instantiateNode.duplicate)创建时,该脚本的初始化都将失败。


void _notification ( int what ) virtual

当对象收到通知时被调用,可以通过将 what 与常量比较来识别通知。另见 notification

func _notification(what):
    if what == NOTIFICATION_PREDELETE:
        print("再见!")

注意:基类 Object 定义了一些通知(NOTIFICATION_POSTINITIALIZENOTIFICATION_PREDELETE)。Node 等继承类定义了更多通知,这些通知也由该方法接收。


bool _property_can_revert ( StringName property ) virtual

覆盖该方法以自定义给定 property 的还原行为。如果 property 可以在检查器停靠面板中恢复,则应该返回 true。使用 _property_get_revert 来指定 property 的默认值。

注意:无论 property 的当前值如何,该方法都必须始终如一地返回。


Variant _property_get_revert ( StringName property ) virtual

覆盖该方法以自定义给定 property 的还原行为。应返回 property 的默认值。如果默认值与 property 的当前值不同,则检查器停靠面板中会显示一个还原图标。

注意:_property_can_revert 也必须被覆盖,该方法才能被调用。


bool _set ( StringName property, Variant value ) virtual

覆盖该方法以自定义 set 的行为。应将 property 设置为 value 并返回 true,如果 property 正常处理则返回 false。设置 property确切方式取决于该方法的实现。

结合 _get_get_property_list,该方法允许定义自定义属性,这对编辑器插件特别有用。注意属性必须get_property_list 中存在,否则该方法将不会被调用。

var internal_data = {}

func _set(property, value):
    if property == "fake_property":
        # 在冒牌属性中存值。
        internal_data["fake_property"] = value
        return true
    return false

func _get_property_list():
    return [
        { "name": "fake_property", "type": TYPE_INT }
    ]

String _to_string ( ) virtual

覆盖该方法以自定义 to_string 的返回值,从而将对象表示为一个 String

func _to_string():
    return "欢迎来到 Godot 4!"

func _init():
    print(self)       # 输出“欢迎来到 Godot 4!”
    var a = str(self) # a 是“欢迎来到 Godot 4!”

void _validate_property ( Dictionary property ) virtual

覆盖该方法以自定义已有属性。每个属性信息都经过该方法。字典内容与 _get_property_list 中的相同。

@tool
extends Node

@export var is_number_editable: bool:
    set(value):
        is_number_editable = value
        notify_property_list_changed()
@export var number: int

func _validate_property(property: Dictionary):
    if property.name == "number" and not is_number_editable:
        property.usage |= PROPERTY_USAGE_READ_ONLY

void add_user_signal ( String signal, Array arguments=[] )

添加用户定义的信号 signal。信号的参数是可选的,以字典的 Array 形式添加,字典中定义名称 name String,类型 type int(见 Variant.Type)。另见 has_user_signal

add_user_signal("hurt", [
    { "name": "damage", "type": TYPE_INT },
    { "name": "source", "type": TYPE_OBJECT }
])

Variant call ( StringName method, ... ) vararg

在对象上调用 method 并返回结果。该方法支持可变数量的参数,因此参数可以作为逗号分隔的列表传递。

var node = Node3D.new()
node.call("rotate", Vector3(1.0, 0.0, 0.0), 1.571)

注意:在 C# 中,在引用 Godot 内置方法时,method 必须为 snake_case 格式。最好使用 MethodName 类中公开的名称,以避免在每次调用时分配新的 StringName


Variant call_deferred ( StringName method, ... ) vararg

在空闲时调用该对象的 method 方法。始终返回 null,不返回该方法的结果。

空闲时间主要出现在处理帧和物理帧的末尾。此时会执行延迟调用,直到全部调用完毕,也就是说延迟调用中也可以进行延迟调用,这种情况下就仍然是在当前空闲时间周期中执行。如果没有谨慎处理,可能导致无限递归,但不会导致栈溢出,后者会像死循环一样让游戏死机。

这个方法支持可变数量的参数,所以参数可以用逗号分隔列表的形式传递。

var node = Node3D.new()
node.call_deferred("rotate", Vector3(1.0, 0.0, 0.0), 1.571)

另见 Callable.call_deferred

注意:在 C# 中,method 引用内置的 Godot 方法时必须使用 snake_case 的形式。请优先使用 MethodName 类中暴露的名称,避免每次调用都分配一个新的 StringName

注意:如果你想要延迟一帧再调用函数,请使用 SceneTree.process_frameSceneTree.physics_frame 信号。

var node = Node3D.new()
# 制作可调用体并将参数绑定到该节点的 rotate() 调用。
var callable = node.rotate.bind(Vector3(1.0, 0.0, 0.0), 1.571)
# 将可调用体连接到 process_frame 信号,这样就能够在下一个处理帧中调用。
# CONNECT_ONE_SHOT 能够确保只调用一次,不会每帧都调用。
get_tree().process_frame.connect(callable, CONNECT_ONE_SHOT)

Variant callv ( StringName method, Array arg_array )

在对象上调用 method 并返回结果。与 call 不同,该方法期望所有参数都包含在 arg_array 中。

var node = Node3D.new()
node.callv("rotate", [Vector3(1.0, 0.0, 0.0), 1.571])

注意:在 C# 中,method 在引用 Godot 内置方法时必须是 snake_case。最好使用 MethodName 类中公开的名称,以避免在每次调用时分配新的 StringName


bool can_translate_messages ( ) const

如果允许该对象使用 trtr_n 翻译消息,则返回 true。另见 set_message_translation


void cancel_free ( )

如果在 NOTIFICATION_PREDELETE 时调用该方法,则该对象拒绝释放,仍会保持已分配的状态。主要是作为内部函数使用,用于错误处理,避免用户释放不想释放的对象。


Error connect ( StringName signal, Callable callable, int flags=0 )

按名称将 signal 连接到 callable。还可以添加可选的 flags 来配置该连接的行为(请参阅 ConnectFlags 常量)。

一个信号只能连接到同一个 Callable 一次。如果该信号已经连接,除非该信号是使用 CONNECT_REFERENCE_COUNTED 连接的,否则该方法会返回 @GlobalScope.ERR_INVALID_PARAMETER 并推送一条错误消息。为防止这种情况,请首先使用 is_connected 检查已存在的连接。

如果 callable 的对象被释放,则该连接将会丢失。

推荐语法的示例:

连接信号是 Godot 中最常见的操作之一,API 提供了许多这样做的选项,这些选项将在下面进一步介绍。下面的代码块显示了推荐的方法。

func _ready():
    var button = Button.new()
    # 这里的 `button_down` 是一个 Signal 变体类型,因此我们调用 Signal.connect() 方法,而不是 Object.connect()。
    # 请参阅下面的讨论以更深入地了解该 API。
    button.button_down.connect(_on_button_down)

    # 这假设存在一个“Player”类,它定义了一个“hit”信号。
    var player = Player.new()
    # 我们再次使用 Signal.connect() ,并且我们还使用了 Callable.bind() 方法,
    # 它返回一个带有参数绑定的新 Callable。
    player.hit.connect(_on_player_hit.bind("剑", 100))

func _on_button_down():
    print("按钮按下!")

func _on_player_hit(weapon_type, damage):
    print("用武器 %s 击中,造成 %d 伤害。" % [weapon_type, damage])

``Object.connect()`` 还是 ``Signal.connect()``?

如上所示,推荐的连接信号的方法不是 connect。下面的代码块显示了连接信号的四个选项,使用该传统方法或推荐的 Signal.connect,并使用一个隐式的 Callable 或手动定义的 Callable

func _ready():
    var button = Button.new()
    # 选项 1:Object.connect() 并使用已定义的函数的隐式 Callable。
    button.connect("button_down", _on_button_down)
    # 选项 2:Object.connect() 并使用由目标对象和方法名称构造的 Callable。
    button.connect("button_down", Callable(self, "_on_button_down"))
    # 选项 3:Signal.connect() 并使用已定义的函数的隐式 Callable。
    button.button_down.connect(_on_button_down)
    # 选项 4:Signal.connect() 并使用由目标对象和方法名称构造的 Callable。
    button.button_down.connect(Callable(self, "_on_button_down"))

func _on_button_down():
    print("按钮按下!")

虽然所有选项都有相同的结果(buttonBaseButton.button_down 信号将被连接到 _on_button_down),但选项 3 提供了最好的验证:如果 button_down Signal_on_button_down Callable 没有被定义,它将打印一个编译时错误。另一方面,选项 2 只依赖于字符串名称,并且只能在运行时验证这两个名称:如果 "button_down" 不对应于一个信号,或者如果 "_on_button_down" 不是对象 self 中的注册方法,它将打印一个运行时错误。使用选项 1、2 或 4 的主要原因,是你是否确实需要使用字符串(例如,根据从配置文件读取的字符串,以编程的方式连接信号)。否则,选项 3 是推荐的(也是最快的)方法。

绑定和传递参数:

绑定参数的语法是通过 Callable.bind,它返回一个绑定了参数的 Callable 的副本。

当调用 emit_signal 时,信号参数也可以被传递。下面的示例显示了这些信号参数和绑定参数之间的关系。

func _ready():
    # 这假设存在一个 `Player` 类,它定义了一个 `hit` 信号。
    var player = Player.new()
    # 使用 Callable.bind()。
    player.hit.connect(_on_player_hit.bind("剑", 100))

    # 发出信号时添加的参数首先被传递。
    player.emit_signal("hit", "黑暗领主", 5)

# 我们在发出时传递两个参数(`hit_by`,`level`),
# 并在连接时再绑定两个参数(`weapon_type`、`damage`)。
func _on_player_hit(hit_by, level, weapon_type, damage):
    print("被 %s(等级 %d)用武器 %s 击中,造成 %d 伤害。" % [hit_by, level, weapon_type, damage])

void disconnect ( StringName signal, Callable callable )

按名称从给定的 callable 断开 signal。如果连接不存在,则生成一个错误。使用 is_connected 确保该连接存在。


Error emit_signal ( StringName signal, ... ) vararg

按名称发出给定的 signal。该信号必须存在,所以它应该是该类或其继承类之一的内置信号,或者是用户定义的信号(参见 add_user_signal)。该方法支持可变数量的参数,所以参数可以以逗号分隔的列表形式传递。

如果 signal 不存在或参数无效,则返回 @GlobalScope.ERR_UNAVAILABLE

emit_signal("hit", "剑", 100)
emit_signal("game_over")

注意:在C#中,在引用内置 Godot 信号时,signal 必须是 snake_case。最好使用 SignalName 类中公开的名称,以避免在每次调用时分配一个新的 StringName


void free ( )

从内存中删除该对象。对该对象的预先存在的引用会变得无效,并且任何访问它们的尝试都将会产生一个运行时错误。使用 @GlobalScope.is_instance_valid 检查引用时将返回 false


Variant get ( StringName property ) const

返回给定 propertyVariant 值。如果 property 不存在,则该方法返回 null

var node = Node2D.new()
node.rotation = 1.5
var a = node.get("rotation") # a 为 1.5

注意:在 C# 中,在引用 Godot 内置属性时,property 必须是 snake_case。最好使用 PropertyName 类中公开的名称,以避免在每次调用时分配一个新的 StringName


String get_class ( ) const

返回该对象的内置类名,作为一个 String。另请参阅 is_class

注意:该方法将忽略 class_name 声明。如果该对象的脚本定义了一个 class_name,则改为返回内置基类名称。


Dictionary[] get_incoming_connections ( ) const

返回该对象接收到的信号连接的 Array。每个连接都被表示为包含三个条目的 Dictionary


Variant get_indexed ( NodePath property_path ) const

获取该对象的某个属性,该属性的属性路径由 property_path 给出。该路径应该是相对于当前对象的 NodePath,可是使用英文冒号(:)访问内嵌属性。

示例:"position:x""material:next_pass:blend_mode"

var node = Node2D.new()
node.position = Vector2(5, -10)
var a = node.get_indexed("position")   # a 为 Vector2(5, -10)
var b = node.get_indexed("position:y") # b 为 -10

注意:在 C# 中引用内置 Godot 属性时 property_path 必须为 snake_case 蛇形大小写。请优先使用 PropertyName 类中暴露的名称,避免每次调用都重新分配一个 StringName

注意:这个方法不支持指向 SceneTree 中节点的路径,仅支持子属性路径。在节点语境下,请改用 Node.get_node_and_resource


int get_instance_id ( ) const

返回该对象的唯一实例 ID。该 ID 可以保存在 EncodedObjectAsID 中,并可用于 @GlobalScope.instance_from_id,来检索该对象实例。


Variant get_meta ( StringName name, Variant default=null ) const

返回该对象的元数据中名称为 name 的条目。如果不存在该条目,则返回 default。如果 defaultnull,则还会生成错误。

注意:元数据的名称必须是符合 StringName.is_valid_identifier 的有效标识符。

注意:名称以下划线(_)开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示,虽然仍然能够被这个方法找到,但是不应该进行编辑。


StringName[] get_meta_list ( ) const

将该对象的元数据作为 PackedStringArray 返回。


Dictionary[] get_method_list ( ) const

将该对象的方法及对应签名作为字典 Array 返回。每个 Dictionary 包含以下条目:

-name 是该方法的名称,为 String

-args 是代表参数的字典 Array

-default_args 是默认参数,为变体 Array

-flagsMethodFlags 的组合;

-id 是该方法的内部标识符 int

-return 是返回值,为 Dictionary

注意:argsreturn 的字典格式与 get_property_list 的结果相同,但不会用到所有条目。


Dictionary[] get_property_list ( ) const

以字典 Array 的形式返回该对象的属性列表。每个 Dictionary 中都包含如下条目:

注意:在 GDScript 中,类的所有成员都被视为属性。在 C# 和 GDExtension 中,则需要使用装饰器或特性将类的成员显式标记为 Godot 属性。


Variant get_script ( ) const

返回该对象的 Script 实例,如果没有附加脚本,则返回 null


Dictionary[] get_signal_connection_list ( StringName signal ) const

返回给定 signal 名称的连接的 Array。每个连接都被表示为包含三个条目的 Dictionary


Dictionary[] get_signal_list ( ) const

将现有信号的列表返回为字典的一个 Array

注意:由于该实现,每个 Dictionary 被格式为与 get_method_list 的返回值非常相似。


bool has_meta ( StringName name ) const

如果找到名称为 name 的元数据条目,则返回 true。另请参阅 get_metaset_metaremove_meta

注意:元数据的名称必须是符合 StringName.is_valid_identifier 的有效标识符。

注意:名称以下划线(_)开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示,虽然仍然能够被这个方法找到,但是不应该进行编辑。


bool has_method ( StringName method ) const

如果该对象中存在给定的方法名 method,则返回 true

注意:在 C# 中引用内置 Godot 方法时 method 必须为 snake_case 蛇形大小写。请优先使用 MethodName 类中暴露的名称,避免每次调用都重新分配一个 StringName


bool has_signal ( StringName signal ) const

如果该对象中存在给定的信号名 signal,则返回 true

注意:在 C# 中引用内置 Godot 信号时 signal 必须为 snake_case 蛇形大小写。请优先使用 SignalName 类中暴露的名称,避免每次调用都重新分配一个 StringName


bool has_user_signal ( StringName signal ) const

如果存在给定的用户定义信号名称 signal,则返回 true。仅包含通过 add_user_signal 添加的信号。


bool is_blocking_signals ( ) const

如果该对象正在阻止发出信号,则返回 true。见 set_block_signals


bool is_class ( String class ) const

如果该对象继承自给定的 class 则返回 true。另见 get_class

var sprite2d = Sprite2D.new()
sprite2d.is_class("Sprite2D") # 返回 true
sprite2d.is_class("Node")     # 返回 true
sprite2d.is_class("Node3D")   # 返回 false

注意:此方法忽略对象脚本中的 class_name 声明。


bool is_connected ( StringName signal, Callable callable ) const

如果给定的 signal 名称和 callable 之间存在连接,则返回 true

注意:在 C# 中,在引用 Godot 内置方法时,signal 必须是 snake_case。最好使用 SignalName 类中公开的名称,以避免在每次调用时分配一个新的 StringName


bool is_queued_for_deletion ( ) const

如果为该对象调用了 Node.queue_free 方法,则返回 true


void notification ( int what, bool reversed=false )

将给定的 what 通知发送给对象继承的所有类,触发对 _notification 的调用,从最高祖先(Object 类)开始,向下一直到对象的脚本。

如果 reversedtrue,则调用顺序会被颠倒。

var player = Node2D.new()
player.set_script(load("res://player.gd"))

player.notification(NOTIFICATION_ENTER_TREE)
# 调用顺序是 Object -> Node -> Node2D -> player.gd。

player.notification(NOTIFICATION_ENTER_TREE, true)
# 调用顺序是 player.gd -> Node2D -> Node -> Object。

void notify_property_list_changed ( )

发出 property_list_changed 信号。这主要是用来刷新编辑器,以让检查器和编辑器插件被正确更新。


bool property_can_revert ( StringName property ) const

如果给定的属性 property 有自定义的默认值,则返回 true。请使用 property_get_revert 获取 property 的默认值。

注意:“检查器”面板会使用这个方法来显示恢复图标。该对象必须实现 _property_can_revert 来自定义默认值。如果未实现 _property_can_revert,则这个方法返回 false


Variant property_get_revert ( StringName property ) const

返回给定的属性 property 的自定义默认值。请使用 property_can_revert 检查 property 是否有自定义的默认值。

注意:“检查器”面板会使用这个方法来显示恢复图标。该对象必须实现 _property_get_revert 来自定义默认值。如果未实现 _property_get_revert,则这个方法返回 null


void remove_meta ( StringName name )

从对象的元数据中移除名称为 name 的条目。另请参阅 has_metaget_meta、和 set_meta

注意:元数据的名称必须是符合 StringName.is_valid_identifier 的有效标识符。

注意:名称以下划线(_)开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示,虽然仍然能够被这个方法找到,但是不应该进行编辑。


void set ( StringName property, Variant value )

将给定属性 property 的值分配为 value。如果该属性不存在,或者给定 value 的类型不匹配,则不会发生任何事情。

var node = Node2D.new()
node.set("global_scale", Vector2(8, 2.5))
print(node.global_scale) # 输出 (8, 2.5)

注意:在 C# 中引用内置 Godot 属性时 property 必须为 snake_case 蛇形大小写。请优先使用 PropertyName 类中暴露的名称,避免每次调用都重新分配一个 StringName


void set_block_signals ( bool enable )

如果设置为 true,这该对象将无法发出信号。因此,emit_signal 和信号连接将不起作用,直到该属性被设置为 false


void set_deferred ( StringName property, Variant value )

在当前帧的末尾,将给定属性 property 的值分配为 value。等价于通过 call_deferred 调用 set

var node = Node2D.new()
add_child(node)

node.rotation = 45.0
node.set_deferred("rotation", 90.0)
print(node.rotation) # 输出 45.0

await get_tree().process_frame
print(node.rotation) # 输出 90.0

注意:在 C# 中引用内置 Godot 属性时 property 必须为 snake_case 蛇形大小写。请优先使用 PropertyName 类中暴露的名称,避免每次调用都重新分配一个 StringName


void set_indexed ( NodePath property_path, Variant value )

将由属性路径 property_path 标识的属性的值分配为 value。该路径应为相对于这个对象的 NodePath,可以使用英文冒号(:)访问内嵌属性。

var node = Node2D.new()
node.set_indexed("position", Vector2(42, 0))
node.set_indexed("position:y", -10)
print(node.position) # 输出 (42, -10)

注意:在 C# 中引用内置 Godot 属性时 property_path 必须为 snake_case 蛇形大小写。请优先使用 PropertyName 类中暴露的名称,避免每次调用都重新分配一个 StringName


void set_message_translation ( bool enable )

如果设置为 true,则允许对象使用 trtr_n 翻译消息。该属性默认启用。另请参阅 can_translate_messages


void set_meta ( StringName name, Variant value )

添加或更改对象元数据中名称为 name 的条目。元数据值 value 可以是任何 Variant,尽管某些类型无法正确序列化。

如果 valuenull,则该条目被移除。等价于使用 remove_meta。另见 has_metaget_meta

注意:元数据的名称必须是符合 StringName.is_valid_identifier 的有效标识符。

注意:名称以下划线(_)开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示,虽然仍然能够被这个方法找到,但是不应该进行编辑。


void set_script ( Variant script )

将脚本 script 附加至该对象,并进行实例化。因此会调用该脚本的 _initScript 可用于扩展对象的功能。

如果已存在脚本,则该脚本的实例会被分离,其属性值和状态会丢失。仍会保留内置属性的值。


String to_string ( )

返回表示对象的 String。默认为 "<ClassName#RID>"。覆盖 _to_string 以自定义对象的字符串表示形式。


String tr ( StringName message, StringName context="" ) const

使用项目设置中配置的翻译目录,翻译一个 message。可以进一步指定 context 来帮助翻译。

如果 can_translate_messagesfalse,或者没有翻译可用,则该方法将返回 message 而不做任何更改。请参阅 set_message_translation

有关详细示例,请参阅《国际化游戏》


String tr_n ( StringName message, StringName plural_message, int n, StringName context="" ) const

使用项目设置中配置的翻译目录,翻译一个 messageplural_message。可以进一步指定 context 来帮助翻译。

如果 can_translate_messagesfalse,或者没有翻译可用,则该方法将返回 messageplural_message,而不做任何更改。请参阅 set_message_translation

n 是消息主题的数字或数量。它被翻译系统用来获取当前语言的正确复数形式。

有关详细示例,请参阅《使用 gettext 进行本地化》

注意:负数和 float 数字可能不适用于某些可数科目。建议使用 tr 处理这些情况。