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.

Object

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

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

描述

一种高级的 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(property: StringName) virtual

Array[Dictionary]

_get_property_list() virtual

void

_init() virtual

void

_notification(what: int) virtual

bool

_property_can_revert(property: StringName) virtual

Variant

_property_get_revert(property: StringName) virtual

bool

_set(property: StringName, value: Variant) virtual

String

_to_string() virtual

void

_validate_property(property: Dictionary) virtual

void

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

Variant

call(method: StringName, ...) vararg

Variant

call_deferred(method: StringName, ...) vararg

Variant

callv(method: StringName, arg_array: Array)

bool

can_translate_messages() const

void

cancel_free()

Error

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

void

disconnect(signal: StringName, callable: Callable)

Error

emit_signal(signal: StringName, ...) vararg

void

free()

Variant

get(property: StringName) const

String

get_class() const

Array[Dictionary]

get_incoming_connections() const

Variant

get_indexed(property_path: NodePath) const

int

get_instance_id() const

Variant

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

Array[StringName]

get_meta_list() const

int

get_method_argument_count(method: StringName) const

Array[Dictionary]

get_method_list() const

Array[Dictionary]

get_property_list() const

Variant

get_script() const

Array[Dictionary]

get_signal_connection_list(signal: StringName) const

Array[Dictionary]

get_signal_list() const

bool

has_meta(name: StringName) const

bool

has_method(method: StringName) const

bool

has_signal(signal: StringName) const

bool

has_user_signal(signal: StringName) const

bool

is_blocking_signals() const

bool

is_class(class: String) const

bool

is_connected(signal: StringName, callable: Callable) const

bool

is_queued_for_deletion() const

void

notification(what: int, reversed: bool = false)

void

notify_property_list_changed()

bool

property_can_revert(property: StringName) const

Variant

property_get_revert(property: StringName) const

void

remove_meta(name: StringName)

void

remove_user_signal(signal: StringName)

void

set(property: StringName, value: Variant)

void

set_block_signals(enable: bool)

void

set_deferred(property: StringName, value: Variant)

void

set_indexed(property_path: NodePath, value: Variant)

void

set_message_translation(enable: bool)

void

set_meta(name: StringName, value: Variant)

void

set_script(script: Variant)

String

to_string()

String

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

String

tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") 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 🔗

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

NOTIFICATION_EXTENSION_RELOADED = 2 🔗

当对象完成热重加载时收到的通知。该通知仅针对扩展类和派生类发送。


方法说明

Variant _get(property: StringName) 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 }
    ]

Array[Dictionary] _get_property_list() virtual 🔗

覆盖该方法以提供由引擎处理的额外属性的自定义列表。

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

你可以使用 _property_can_revert_property_get_revert 自定义该方法添加的属性的默认值。

下面的示例显示了一个数字列表,该列表显示为从 ZEROFIVE 的单词,其中 number_count 控制列表的大小:

@tool
extends Node

@export var number_count = 3:
    set(nc):
        number_count = nc
        numbers.resize(number_count)
        notify_property_list_changed()

var numbers = PackedInt32Array([0, 0, 0])

func _get_property_list():
    var properties = []

    for i in range(number_count):
        properties.append({
            "name": "number_%d" % i,
            "type": TYPE_INT,
            "hint": PROPERTY_HINT_ENUM,
            "hint_string": "ZERO,ONE,TWO,THREE,FOUR,FIVE",
        })

    return properties

func _get(property):
    if property<