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¶

Inherited By: AudioServer, CameraServer, ClassDB, DisplayServer, EditorFileSystemDirectory, EditorPaths, EditorSelection, EditorUndoRedoManager, EditorVCSInterface, Engine, EngineDebugger, GDExtensionManager, Geometry2D, Geometry3D, GodotSharp, Input, InputMap, IP, JavaClassWrapper, JavaScriptBridge, JNISingleton, JSONRPC, MainLoop, Marshalls, MovieWriter, NavigationMeshGenerator, NavigationServer2D, NavigationServer3D, Node, 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 Object 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
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
PackedStringArray	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, 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 }
    ]

public override Variant _Get(StringName property)
{
    if (property == "FakeProperty")
    {
        GD.Print("Getting my property!");
        return 4;
    }
    return default;
}

public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList()
{
    return new Godot.Collections.Array<Godot.Collections.Dictionary>()
    {
        new Godot.Collections.Dictionary()
        {
            { "name", "FakeProperty" },
            { "type", (int)Variant.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

[Tool]
public partial class MyNode2D : Node2D
{
    private bool _holdingHammer;

    [Export]
    public bool HoldingHammer
    {
        get => _holdingHammer;
        set
        {
            _holdingHammer = value;
            NotifyPropertyListChanged();
        }
    }

    public int HammerType { get; set; }

    public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList()
    {
        // By default, `HammerType` is not visible in the editor.
        var propertyUsage = PropertyUsageFlags.NoEditor;

        if (HoldingHammer)
        {
            propertyUsage = PropertyUsageFlags.Default;
        }

        var properties = new Godot.Collections.Array<Godot.Collections.Dictionary>();
        properties.Add(new Godot.Collections.Dictionary()
        {
            { "name", "HammerType" },
            { "type", (int)Variant.Type.Int },
            { "usage", (int)propertyUsage }, // See above assignment.
            { "hint", (int)PropertyHint.Enum },
            { "hint_string", "Wooden,Iron,Golden,Enchanted" }
        });

        return properties;
    }
}

Note: This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See @GDScript.@export, @GDScript.@export_enum, @GDScript.@export_group, etc.

Note: If the object's script is not @GDScript.@tool, this method will not be called in the editor.

void _init ( ) virtual

Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through Object.new() in GDScript, or new Object in C#). It can be also defined to take in parameters. This method is similar to a constructor in most programming languages.

Note: If _init is defined with required parameters, the Object with script may only be created directly. If any other means (such as PackedScene.instantiate or Node.duplicate) are used, the script's initialization will fail.

void _notification ( int what ) virtual

Called when the object receives a notification, which can be identified in what by comparing it with a constant. See also notification.

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

public override void _Notification(long what)
{
    if (what == NotificationPredelete)
    {
        GD.Print("Goodbye!");
    }
}

Note: The base Object defines a few notifications (NOTIFICATION_POSTINITIALIZE and NOTIFICATION_PREDELETE). Inheriting classes such as Node define a lot more notifications, which are also received by this method.

bool _property_can_revert ( StringName property ) virtual

Override this method to customize the given property's revert behavior. Should return true if the property can be reverted in the Inspector dock. Use _property_get_revert to specify the property's default value.

Note: This method must return consistently, regardless of the current value of the property.

Variant _property_get_revert ( StringName property ) virtual

Override this method to customize the given property's revert behavior. Should return the default value for the property. If the default value differs from the property's current value, a revert icon is displayed in the Inspector dock.

Note: _property_can_revert must also be overridden for this method to be called.

bool _set ( StringName property, Variant value ) virtual

Override this method to customize the behavior of set. Should set the property to value and return true, or false if the property should be handled normally. The exact way to set the property is up to this method's implementation.

Combined with _get 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 _set(property, value):
    if (property == "fake_property"):
        print("Setting my property to ", value)

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

public override void _Set(StringName property, Variant value)
{
    if (property == "FakeProperty")
    {
        GD.Print($"Setting my property to {value}");
        return true;
    }

    return false;
}

public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList()
{
    return new Godot.Collections.Array<Godot.Collections.Dictionary>()
    {
        new Godot.Collections.Dictionary()
        {
            { "name", "FakeProperty" },
            { "type", (int)Variant.Type.Int }
        }
    };
}

String _to_string ( ) virtual

Override this method to customize the return value of to_string, and therefore the object's representation as a String.

func _to_string():
    return "Welcome to Godot 4!"

func _init():
    print(self)       # Prints Welcome to Godot 4!"
    var a = str(self) # a is "Welcome to Godot 4!"

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

Adds a user-defined signal. Optional arguments for the signal can be added as an Array of dictionaries, each defining a name String and a type int (see Variant.Type). See also has_user_signal.

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

AddUserSignal("Hurt", new Godot.Collections.Array()
{
    new Godot.Collections.Dictionary()
    {
        { "name", "damage" },
        { "type", (int)Variant.Type.Int }
    },
    new Godot.Collections.Dictionary()
    {
        { "name", "source" },
        { "type", (int)Variant.Type.Object }
    }
});

Variant call ( StringName method, ... ) vararg

Calls the method on the object and returns the result. This method supports a variable number of arguments, so parameters can be passed as a comma separated list.

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

var node = new Node3D();
node.Call(Node3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f);

Note: In C#, method must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

Variant call_deferred ( StringName method, ... ) vararg

Calls the method on the object during idle time. This method supports a variable number of arguments, so parameters can be passed as a comma separated list.