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