Up to date

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

Object

Inherited By: 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, 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

Base class for all other classes in the engine.

Description

An advanced Variant type. All classes in the engine inherit from Object. Each class may define new properties, methods or signals, which are available to all inheriting classes. For example, a Sprite2D instance is able to call Node.add_child because it inherits from Node.

You can create new instances, using Object.new() in GDScript, or new GodotObject in C#.

To delete an Object instance, call free. This is necessary for most classes inheriting Object, because they do not manage memory on their own, and will otherwise cause memory leaks when no longer in use. There are a few classes that perform memory management. For example, RefCounted (and by extension Resource) deletes itself when no longer referenced, and Node deletes its children when freed.

Objects can have a Script attached to them. Once the Script is instantiated, it effectively acts as an extension to the base class, allowing it to define and inherit new properties, methods and signals.

Inside a Script, _get_property_list may be overridden to customize properties in several ways. This allows them to be available to the editor, display as lists of options, sub-divide into groups, save on disk, etc. Scripting languages offer easier ways to customize properties, such as with the @GDScript.@export annotation.

Godot is very dynamic. An object's script, and therefore its properties, methods and signals, can be changed at run-time. Because of this, there can be occasions where, for example, a property required by a method may not exist. To prevent run-time errors, see methods such as set, get, call, has_method, has_signal, etc. Note that these methods are much slower than direct references.

In GDScript, you can also check if a given property, method, or signal name exists in an object with the in operator:

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

Notifications are int constants commonly sent and received by objects. For example, on every rendered frame, the SceneTree notifies nodes inside the tree with a Node.NOTIFICATION_PROCESS. The nodes receive it and may call Node._process to update. To make use of notifications, see notification and _notification.

Lastly, every object can also contain metadata (data about data). set_meta can be useful to store information that the object itself does not depend on. To keep your code clean, making excessive use of metadata is discouraged.

Note: Unlike references to a RefCounted, references to an object stored in a variable can become invalid without being set to null. To check if an object has been deleted, do not compare it against null. Instead, use @GlobalScope.is_instance_valid. It's also recommended to inherit from RefCounted for classes storing data instead of Object.

Note: The script is not exposed like most properties. To set or get an object's Script in code, use set_script and get_script, respectively.

Tutorials

Methods

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

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


Signals

property_list_changed ( )

Emitted when notify_property_list_changed is called.


script_changed ( )

Emitted when the object's script is changed.

Note: When this signal is emitted, the new script is not initialized yet. If you need to access the new script, defer connections to this signal with CONNECT_DEFERRED.


Enumerations

enum ConnectFlags:

ConnectFlags CONNECT_DEFERRED = 1

Deferred connections trigger their Callables on idle time (at the end of the frame), rather than instantly.

ConnectFlags CONNECT_PERSIST = 2

Persisting connections are stored when the object is serialized (such as when using PackedScene.pack). In the editor, connections created through the Node dock are always persisting.

ConnectFlags CONNECT_ONE_SHOT = 4

One-shot connections disconnect themselves after emission.

ConnectFlags CONNECT_REFERENCE_COUNTED = 8

Reference-counted connections can be assigned to the same Callable multiple times. Each disconnection decreases the internal counter. The signal fully disconnects only when the counter reaches 0.


Constants

NOTIFICATION_POSTINITIALIZE = 0

Notification received when the object is initialized, before its script is attached. Used internally.

NOTIFICATION_PREDELETE = 1

Notification received when the object is about to be deleted. Can act as the deconstructor of some programming languages.


Method Descriptions

Variant _get ( StringName property ) virtual

Override this method to customize the behavior of get. Should return the given property's value, or null if the property should be handled normally.

Combined with _set and _get_property_list, this method allows defining custom properties, which is particularly useful for editor plugins. Note that a property must be present in get_property_list, otherwise this method will not be called.

func _get(property):
    if property == "fake_property":
        print("Getting my property!")
        return 4

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

Dictionary[] _get_property_list ( ) virtual

Override this method to customize how script properties should be handled by the engine.

Should return a property list, as an Array of dictionaries. The result is added to the array of get_property_list, and should be formatted in the same way. Each Dictionary must at least contain the name and type entries.

The example below displays hammer_type in the Inspector dock, only if holding_hammer is true:

@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():
    # By default, `hammer_type` is not visible in the editor.
    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, # See above assignment.
        "hint": PROPERTY_HINT_ENUM,
        "hint_string": "Wooden,Iron,Golden,Enchanted"
    })

    return properties