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:
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.
Emitted when notify_property_list_changed is called.
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.
CONNECT_DEFERRED = 1
Deferred connections trigger their Callables on idle time (at the end of the frame), rather than instantly.
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.
CONNECT_ONE_SHOT = 4
One-shot connections disconnect themselves after emission.
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.
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.
Override this method to provide a custom list of additional properties to handle 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.
You can use _property_can_revert and _property_get_revert to customize the default values of the properties added by this method.
The example below displays a list of numbers shown as words going from ZERO
to FIVE
, with number_count
controlling the size of the list:
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. If you want to customize exported properties, use _validate_property.
Note: If the object's script is not @GDScript.@tool, this method will not be called in the editor.
Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through Object.new()
in GDScript, or new GodotObject
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.
Called when the object receives a notification, which can be identified in what
by comparing it with a constant. See also notification.
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.
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
.
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.
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.
Override this method to customize the return value of to_string, and therefore the object's representation as a String.
Override this method to customize existing properties. Every property info goes through this method, except properties added with _get_property_list. The dictionary contents is the same as in _get_property_list.
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.
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.
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.
Calls the method
on the object during idle time. Always returns null, not the method's result.
Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. If not done carefully, this can result in infinite recursion without causing a stack overflow, which will hang the game similarly to an infinite loop.
This method supports a variable number of arguments, so parameters can be passed as a comma separated list.
See also Callable.call_deferred.
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.
Note: If you're looking to delay the function call by a frame, refer to the SceneTree.process_frame and SceneTree.physics_frame signals.
Calls the method
on the object and returns the result. Unlike call, this method expects all parameters to be contained inside arg_array
.
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.
Returns true
if the object is allowed to translate messages with tr and tr_n. See also set_message_translation.
If this method is called during NOTIFICATION_PREDELETE, this object will reject being freed and will remain allocated. This is mostly an internal function used for error handling to avoid the user from freeing objects when they are not intended to.
Connects a signal
by name to a callable
. Optional flags
can be also added to configure the connection's behavior (see ConnectFlags constants).
A signal can only be connected once to the same Callable. If the signal is already connected, this method returns @GlobalScope.ERR_INVALID_PARAMETER and pushes an error message, unless the signal is connected with CONNECT_REFERENCE_COUNTED. To prevent this, use is_connected first to check for existing connections.
If the callable
's object is freed, the connection will be lost.
Examples with recommended syntax:
Connecting signals is one of the most common operations in Godot and the API gives many options to do so, which are described further down. The code block below shows the recommended approach.
``Object.connect()`` or ``Signal.connect()``?
As seen above, the recommended method to connect signals is not connect. The code block below shows the four options for connecting signals, using either this legacy method or the recommended Signal.connect, and using either an implicit Callable or a manually defined one.
While all options have the same outcome (button
's BaseButton.button_down signal will be connected to _on_button_down
), option 3 offers the best validation: it will print a compile-time error if either the button_down
Signal or the _on_button_down
Callable are not defined. On the other hand, option 2 only relies on string names and will only be able to validate either names at runtime: it will print a runtime error if "button_down"
doesn't correspond to a signal, or if "_on_button_down"
is not a registered method in the object self
. The main reason for using options 1, 2, or 4 would be if you actually need to use strings (e.g. to connect signals programmatically based on strings read from a configuration file). Otherwise, option 3 is the recommended (and fastest) method.
Binding and passing parameters:
The syntax to bind parameters is through Callable.bind, which returns a copy of the Callable with its parameters bound.
When calling emit_signal, the signal parameters can be also passed. The examples below show the relationship between these signal parameters and bound parameters.
Disconnects a signal
by name from a given callable
. If the connection does not exist, generates an error. Use is_connected to make sure that the connection exists.
Emits the given signal
by name. The signal must exist, so it should be a built-in signal of this class or one of its inherited classes, or a user-defined signal (see add_user_signal). This method supports a variable number of arguments, so parameters can be passed as a comma separated list.
Returns @GlobalScope.ERR_UNAVAILABLE if signal
does not exist or the parameters are invalid.
Note: In C#, signal
must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the SignalName
class to avoid allocating a new StringName on each call.
Deletes the object from memory. Pre-existing references to the object become invalid, and any attempt to access them will result in a run-time error. Checking the references with @GlobalScope.is_instance_valid will return false
.
Returns the Variant value of the given property
. If the property
does not exist, this method returns null
.
Note: In C#, property
must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName
class to avoid allocating a new StringName on each call.
Returns the object's built-in class name, as a String. See also is_class.
Note: This method ignores class_name
declarations. If this object's script has defined a class_name
, the base, built-in class name is returned instead.
Returns an Array of signal connections received by this object. Each connection is represented as a Dictionary that contains three entries:
signal
is a reference to the Signal;
callable
is a reference to the Callable;
flags
is a combination of ConnectFlags.
Gets the object's property indexed by the given property_path
. The path should be a NodePath relative to the current object and can use the colon character (:
) to access nested properties.
Examples: "position:x"
or "material:next_pass:blend_mode"
.
Note: In C#, property_path
must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName
class to avoid allocating a new StringName on each call.
Note: This method does not support actual paths to nodes in the SceneTree, only sub-property paths. In the context of nodes, use Node.get_node_and_resource instead.
Returns the object's unique instance ID. This ID can be saved in EncodedObjectAsID, and can be used to retrieve this object instance with @GlobalScope.instance_from_id.
Returns the object's metadata value for the given entry name
. If the entry does not exist, returns default
. If default
is null
, an error is also generated.
Note: A metadata's name must be a valid identifier as per StringName.is_valid_identifier method.
Note: Metadata that has a name starting with an underscore (_
) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method.
Returns the object's metadata entry names as a PackedStringArray.
Returns this object's methods and their signatures as an Array of dictionaries. Each Dictionary contains the following entries:
name
is the name of the method, as a String;
args
is an Array of dictionaries representing the arguments;
default_args
is the default arguments as an Array of variants;
flags
is a combination of MethodFlags;
id
is the method's internal identifier int;
return
is the returned value, as a Dictionary;
Note: The dictionaries of args
and return
are formatted identically to the results of get_property_list, although not all entries are used.
Returns the object's property list as an Array of dictionaries. Each Dictionary contains the following entries:
name
is the property's name, as a String;
class_name
is an empty StringName, unless the property is @GlobalScope.TYPE_OBJECT and it inherits from a class;
type
is the property's type, as an int (see Variant.Type);
hint
is how the property is meant to be edited (see PropertyHint);
hint_string
depends on the hint (see PropertyHint);
usage
is a combination of PropertyUsageFlags.
Note: In GDScript, all class members are treated as properties. In C# and GDExtension, it may be necessary to explicitly mark class members as Godot properties using decorators or attributes.
Returns the object's Script instance, or null
if no script is attached.
Returns an Array of connections for the given signal
name. Each connection is represented as a Dictionary that contains three entries:
signal
is a reference to the Signal;
callable
is a reference to the connected Callable;
flags
is a combination of ConnectFlags.
Returns the list of existing signals as an Array of dictionaries.
Note: Due of the implementation, each Dictionary is formatted very similarly to the returned values of get_method_list.
Returns true
if a metadata entry is found with the given name
. See also get_meta, set_meta and remove_meta.
Note: A metadata's name must be a valid identifier as per StringName.is_valid_identifier method.
Note: Metadata that has a name starting with an underscore (_
) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method.
Returns true
if the given method
name exists in the object.
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.
Returns true
if the given signal
name exists in the object.
Note: In C#, signal
must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the SignalName
class to avoid allocating a new StringName on each call.
Returns true
if the given user-defined signal
name exists. Only signals added with add_user_signal are included.
Returns true
if the object is blocking its signals from being emitted. See set_block_signals.
Returns true
if the object inherits from the given class
. See also get_class.
Note: This method ignores class_name
declarations in the object's script.
Returns true
if a connection exists between the given signal
name and callable
.
Note: In C#, signal
must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the SignalName
class to avoid allocating a new StringName on each call.
Returns true
if the Node.queue_free method was called for the object.
Sends the given what
notification to all classes inherited by the object, triggering calls to _notification, starting from the highest ancestor (the Object class) and going down to the object's script.
If reversed
is true
, the call order is reversed.
Emits the property_list_changed signal. This is mainly used to refresh the editor, so that the Inspector and editor plugins are properly updated.
Returns true
if the given property
has a custom default value. Use property_get_revert to get the property
's default value.
Note: This method is used by the Inspector dock to display a revert icon. The object must implement _property_can_revert to customize the default value. If _property_can_revert is not implemented, this method returns false
.
Returns the custom default value of the given property
. Use property_can_revert to check if the property
has a custom default value.
Note: This method is used by the Inspector dock to display a revert icon. The object must implement _property_get_revert to customize the default value. If _property_get_revert is not implemented, this method returns null
.
Removes the given entry name
from the object's metadata. See also has_meta, get_meta and set_meta.
Note: A metadata's name must be a valid identifier as per StringName.is_valid_identifier method.
Note: Metadata that has a name starting with an underscore (_
) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method.
Assigns value
to the given property
. If the property does not exist or the given value
's type doesn't match, nothing happens.
Note: In C#, property
must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName
class to avoid allocating a new StringName on each call.
If set to true
, the object becomes unable to emit signals. As such, emit_signal and signal connections will not work, until it is set to false
.
Assigns value
to the given property
, at the end of the current frame. This is equivalent to calling set through call_deferred.
Note: In C#, property
must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName
class to avoid allocating a new StringName on each call.
Assigns a new value
to the property identified by the property_path
. The path should be a NodePath relative to this object, and can use the colon character (:
) to access nested properties.
Note: In C#, property_path
must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName
class to avoid allocating a new StringName on each call.
If set to true
, allows the object to translate messages with tr and tr_n. Enabled by default. See also can_translate_messages.
Adds or changes the entry name
inside the object's metadata. The metadata value
can be any Variant, although some types cannot be serialized correctly.
If value
is null
, the entry is removed. This is the equivalent of using remove_meta. See also has_meta and get_meta.
Note: A metadata's name must be a valid identifier as per StringName.is_valid_identifier method.
Note: Metadata that has a name starting with an underscore (_
) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method.
Attaches script
to the object, and instantiates it. As a result, the script's _init is called. A Script is used to extend the object's functionality.
If a script already exists, its instance is detached, and its property values and state are lost. Built-in property values are still kept.
Returns a String representing the object. Defaults to "<ClassName#RID>"
. Override _to_string to customize the string representation of the object.
Translates a message
, using the translation catalogs configured in the Project Settings. Further context
can be specified to help with the translation.
If can_translate_messages is false
, or no translation is available, this method returns the message
without changes. See set_message_translation.
For detailed examples, see Internationalizing games.
Translates a message
or plural_message
, using the translation catalogs configured in the Project Settings. Further context
can be specified to help with the translation.
If can_translate_messages is false
, or no translation is available, this method returns message
or plural_message
, without changes. See set_message_translation.
The n
is the number, or amount, of the message's subject. It is used by the translation system to fetch the correct plural form for the current language.
For detailed examples, see Localization using gettext.
Note: Negative and float numbers may not properly apply to some countable subjects. It's recommended handling these cases with tr.