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

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 是非常动态的。一个对象的脚本，以及它的属性、方法和信号，都可以在运行时改变。正因为如此，可能会出现这样的情况，例如，一个方法所需的属性可能不存在。为了防止运行时出错，可以参考 set、get、call、has_method、has_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_script 和 get_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 必须至少包含 name 和 type 条目。

以下示例仅在 holding_hammer 为 true 时，在检查器停靠面板中显示 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.instantiate 或 Node.duplicate）创建时，该脚本的初始化都将失败。

void _notification ( int what ) virtual

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

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

注意：基类 Object 定义了一些通知（NOTIFICATION_POSTINITIALIZE 和 NOTIFICATION_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 类中公开的名称，以避免在每次调用时分配新的