path: root/doc/classes/Object.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Object" category="Core" version="3.2">
	<brief_description>
		Base class for all non built-in types.
	</brief_description>
	<description>
		Every class which is not a built-in type inherits from this class.
		You can construct Objects from scripting languages, using [code]Object.new()[/code] in GDScript, [code]new Object[/code] in C#, or the "Construct Object" node in VisualScript.
		Objects do not manage memory. If a class inherits from Object, you will have to delete instances of it manually. To do so, call the [method free] method from your script or delete the instance from C++.
		Some classes that extend Object add memory management. This is the case of [Reference], which counts references and deletes itself automatically when no longer referenced. [Node], another fundamental type, deletes all its children when freed from memory.
		Objects export properties, which are mainly useful for storage and editing, but not really so much in programming. Properties are exported in [method _get_property_list] and handled in [method _get] and [method _set]. However, scripting languages and C++ have simpler means to export them.
		Objects also receive notifications. Notifications are a simple way to notify the object about simple events, so they can all be handled together. See [method _notification].
	</description>
	<tutorials>
	</tutorials>
	<methods>
		<method name="_get" qualifiers="virtual">
			<return type="Variant">
			</return>
			<argument index="0" name="property" type="String">
			</argument>
			<description>
				Returns the given property. Returns [code]null[/code] if the [code]property[/code] does not exist.
			</description>
		</method>
		<method name="_get_property_list" qualifiers="virtual">
			<return type="Array">
			</return>
			<description>
				Returns the object's property list as an [Array] of dictionaries. Dictionaries must contain: name:String, type:int (see TYPE_* enum in [@GlobalScope]) and optionally: hint:int (see PROPERTY_HINT_* in [@GlobalScope]), hint_string:String, usage:int (see PROPERTY_USAGE_* in [@GlobalScope]).
			</description>
		</method>
		<method name="_init" qualifiers="virtual">
			<return type="void">
			</return>
			<description>
				The virtual method called upon initialization.
			</description>
		</method>
		<method name="_notification" qualifiers="virtual">
			<return type="void">
			</return>
			<argument index="0" name="what" type="int">
			</argument>
			<description>
				Notify the object internally using an ID.
			</description>
		</method>
		<method name="_set" qualifiers="virtual">
			<return type="bool">
			</return>
			<argument index="0" name="property" type="String">
			</argument>
			<argument index="1" name="value" type="Variant">
			</argument>
			<description>
				Sets a property. Returns [code]true[/code] if the [code]property[/code] exists.
			</description>
		</method>
		<method name="_to_string" qualifiers="virtual">
			<return type="String">
			</return>
			<description>
				Returns a [String] representing the object. Default is [code]"[ClassName:RID]"[/code].
				Override this method to customize the [String] representation of the object when it's being converted to a string, for example: [code]print(obj)[/code].
			</description>
		</method>
		<method name="add_user_signal">
			<return type="void">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<argument index="1" name="arguments" type="Array" default="[  ]">
			</argument>
			<description>
				Adds a user-defined [code]signal[/code]. Arguments are optional, but can be added as an [Array] of dictionaries, each containing "name" and "type" (from [@GlobalScope] TYPE_*).
			</description>
		</method>
		<method name="call" qualifiers="vararg">
			<return type="Variant">
			</return>
			<argument index="0" name="method" type="String">
			</argument>
			<description>
				Calls the [code]method[/code] on the object and returns a result. Pass parameters as a comma separated list.
			</description>
		</method>
		<method name="call_deferred" qualifiers="vararg">
			<return type="Variant">
			</return>
			<argument index="0" name="method" type="String">
			</argument>
			<description>
				Calls the [code]method[/code] on the object during idle time and returns a result. Pass parameters as a comma separated list.
			</description>
		</method>
		<method name="callv">
			<return type="Variant">
			</return>
			<argument index="0" name="method" type="String">
			</argument>
			<argument index="1" name="arg_array" type="Array">
			</argument>
			<description>
				Calls the [code]method[/code] on the object and returns a result. Pass parameters as an [Array].
			</description>
		</method>
		<method name="can_translate_messages" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if the object can translate strings.
			</description>
		</method>
		<method name="connect">
			<return type="int" enum="Error">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<argument index="1" name="target" type="Object">
			</argument>
			<argument index="2" name="method" type="String">
			</argument>
			<argument index="3" name="binds" type="Array" default="[  ]">
			</argument>
			<argument index="4" name="flags" type="int" default="0">
			</argument>
			<description>
				Connects a [code]signal[/code] to a [code]method[/code] on a [code]target[/code] object. Pass optional [code]binds[/code] to the call. Use [code]flags[/code] to set deferred or one shot connections. See [code]CONNECT_*[/code] constants.
				A [code]signal[/code] can only be connected once to a [code]method[/code]. It will throw an error if already connected. To avoid this, first, use [method is_connected] to check for existing connections.
				If the [code]target[/code] is destroyed in the game's lifecycle, the connection will be lost.
			</description>
		</method>
		<method name="disconnect">
			<return type="void">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<argument index="1" name="target" type="Object">
			</argument>
			<argument index="2" name="method" type="String">
			</argument>
			<description>
				Disconnects a [code]signal[/code] from a [code]method[/code] on the given [code]target[/code].
				If you try to disconnect a connection that does not exist, the method will throw an error. Use [method is_connected] to ensure that the connection exists.
			</description>
		</method>
		<method name="emit_signal" qualifiers="vararg">
			<return type="Variant">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<description>
				Emits the given [code]signal[/code].
			</description>
		</method>
		<method name="free">
			<return type="void">
			</return>
			<description>
				Deletes the object from memory.
			</description>
		</method>
		<method name="get" qualifiers="const">
			<return type="Variant">
			</return>
			<argument index="0" name="property" type="String">
			</argument>
			<description>
				Returns a [Variant] for a [code]property[/code].
			</description>
		</method>
		<method name="get_class" qualifiers="const">
			<return type="String">
			</return>
			<description>
				Returns the object's class as a [String].
			</description>
		</method>
		<method name="get_incoming_connections" qualifiers="const">
			<return type="Array">
			</return>
			<description>
				Returns an [Array] of dictionaries with information about signals that are connected to the object.
				Inside each [Dictionary] there are 3 fields:
				- "source" is a reference to signal emitter.
				- "signal_name" is name of connected signal.
				- "method_name" is a name of method to which signal is connected.
			</description>
		</method>
		<method name="get_indexed" qualifiers="const">
			<return type="Variant">
			</return>
			<argument index="0" name="property" type="NodePath">
			</argument>
			<description>
				Get indexed object property by String.
				Property indices get accessed with colon separation, for example: [code]position:x[/code]
			</description>
		</method>
		<method name="get_instance_id" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Returns the object's unique instance ID.
				This ID can be saved in [EncodedObjectAsID], and can be used to retrieve the object instance with [method @GDScript.instance_from_id].
			</description>
		</method>
		<method name="get_meta" qualifiers="const">
			<return type="Variant">
			</return>
			<argument index="0" name="name" type="String">
			</argument>
			<description>
				Returns the object's metadata for the given [code]name[/code].
			</description>
		</method>
		<method name="get_meta_list" qualifiers="const">
			<return type="PoolStringArray">
			</return>
			<description>
				Returns the object's metadata as a [PoolStringArray].
			</description>
		</method>
		<method name="get_method_list" qualifiers="const">
			<return type="Array">
			</return>
			<description>
				Returns the object's methods and their signatures as an [Array].
			</description>
		</method>
		<method name="get_property_list" qualifiers="const">
			<return type="Array">
			</return>
			<description>
				Returns the list of properties as an [Array] of dictionaries. Dictionaries contain: name:String, type:int (see TYPE_* enum in [@GlobalScope]) and optionally: hint:int (see PROPERTY_HINT_* in [@GlobalScope]), hint_string:String, usage:int (see PROPERTY_USAGE_* in [@GlobalScope]).
			</description>
		</method>
		<method name="get_script" qualifiers="const">
			<return type="Reference">
			</return>
			<description>
				Returns the object's [Script] or [code]null[/code] if one doesn't exist.
			</description>
		</method>
		<method name="get_signal_connection_list" qualifiers="const">
			<return type="Array">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<description>
				Returns an [Array] of connections for the given [code]signal[/code].
			</description>
		</method>
		<method name="get_signal_list" qualifiers="const">
			<return type="Array">
			</return>
			<description>
				Returns the list of signals as an [Array] of dictionaries.
			</description>
		</method>
		<method name="has_meta" qualifiers="const">
			<return type="bool">
			</return>
			<argument index="0" name="name" type="String">
			</argument>
			<description>
				Returns [code]true[/code] if a metadata is found with the given [code]name[/code].
			</description>
		</method>
		<method name="has_method" qualifiers="const">
			<return type="bool">
			</return>
			<argument index="0" name="method" type="String">
			</argument>
			<description>
				Returns [code]true[/code] if the object contains the given [code]method[/code].
			</description>
		</method>
		<method name="has_user_signal" qualifiers="const">
			<return type="bool">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<description>
				Returns [code]true[/code] if the given user-defined [code]signal[/code] exists.
			</description>
		</method>
		<method name="is_blocking_signals" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if signal emission blocking is enabled.
			</description>
		</method>
		<method name="is_class" qualifiers="const">
			<return type="bool">
			</return>
			<argument index="0" name="type" type="String">
			</argument>
			<description>
				Returns [code]true[/code] if the object inherits from the given [code]type[/code].
			</description>
		</method>
		<method name="is_connected" qualifiers="const">
			<return type="bool">
			</return>
			<argument index="0" name="signal" type="String">
			</argument>
			<argument index="1" name="target" type="Object">
			</argument>
			<argument index="2" name="method" type="String">
			</argument>
			<description>
				Returns [code]true[/code] if a connection exists for a given [code]signal[/code], [code]target[/code], and [code]method[/code].
			</description>
		</method>
		<method name="is_queued_for_deletion" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if the [code]queue_free[/code] method was called for the object.
			</description>
		</method>
		<method name="notification">
			<return type="void">
			</return>
			<argument index="0" name="what" type="int">
			</argument>
			<argument index="1" name="reversed" type="bool" default="false">
			</argument>
			<description>
				Notify the object of something.
			</description>
		</method>
		<method name="property_list_changed_notify">
			<return type="void">
			</return>
			<description>
			</description>
		</method>
		<method name="remove_meta">
			<return type="void">
			</return>
			<argument index="0" name="name" type="String">
			</argument>
			<description>
			</description>
		</method>
		<method name="set">
			<return type="void">
			</return>
			<argument index="0" name="property" type="String">
			</argument>
			<argument index="1" name="value" type="Variant">
			</argument>
			<description>
				Set property into the object.
			</description>
		</method>
		<method name="set_block_signals">
			<return type="void">
			</return>
			<argument index="0" name="enable" type="bool">
			</argument>
			<description>
				If set to [code]true[/code], signal emission is blocked.
			</description>
		</method>
		<method name="set_deferred">
			<return type="void">
			</return>
			<argument index="0" name="property" type="String">
			</argument>
			<argument index="1" name="value" type="Variant">
			</argument>
			<description>
				Set property into the object, after the current frame's physics step. This is equivalent to calling [method set] via [method call_deferred], i.e. [code]call_deferred("set", [property, value])[/code].
			</description>
		</method>
		<method name="set_indexed">
			<return type="void">
			</return>
			<argument index="0" name="property" type="NodePath">
			</argument>
			<argument index="1" name="value" type="Variant">
			</argument>
			<description>
			</description>
		</method>
		<method name="set_message_translation">
			<return type="void">
			</return>
			<argument index="0" name="enable" type="bool">
			</argument>
			<description>
				Define whether the object can translate strings (with calls to [method tr]). Default is [code]true[/code].
			</description>
		</method>
		<method name="set_meta">
			<return type="void">
			</return>
			<argument index="0" name="name" type="String">
			</argument>
			<argument index="1" name="value" type="Variant">
			</argument>
			<description>
				Set a metadata into the object. Metadata is serialized. Metadata can be [i]anything[/i].
			</description>
		</method>
		<method name="set_script">
			<return type="void">
			</return>
			<argument index="0" name="script" type="Reference">
			</argument>
			<description>
				Set a script into the object, scripts extend the object functionality.
			</description>
		</method>
		<method name="to_string">
			<return type="String">
			</return>
			<description>
				Returns a [String] representing the object. Default is [code]"[ClassName:RID]"[/code].
				Override the method [method _to_string] to customize the [String] representation.
			</description>
		</method>
		<method name="tr" qualifiers="const">
			<return type="String">
			</return>
			<argument index="0" name="message" type="String">
			</argument>
			<description>
				Translate a message. Only works if message translation is enabled (which it is by default). See [method set_message_translation].
			</description>
		</method>
	</methods>
	<signals>
		<signal name="script_changed">
			<description>
				Emitted whenever the script of the Object is changed.
			</description>
		</signal>
	</signals>
	<constants>
		<constant name="NOTIFICATION_POSTINITIALIZE" value="0">
			Called right when the object is initialized. Not available in script.
		</constant>
		<constant name="NOTIFICATION_PREDELETE" value="1">
			Called before the object is about to be deleted.
		</constant>
		<constant name="CONNECT_DEFERRED" value="1" enum="ConnectFlags">
			Connect a signal in deferred mode. This way, signal emissions are stored in a queue, then set on idle time.
		</constant>
		<constant name="CONNECT_PERSIST" value="2" enum="ConnectFlags">
			Persisting connections are saved when the object is serialized to file.
		</constant>
		<constant name="CONNECT_ONESHOT" value="4" enum="ConnectFlags">
			One shot connections disconnect themselves after emission.
		</constant>
		<constant name="CONNECT_REFERENCE_COUNTED" value="8" enum="ConnectFlags">
		</constant>
	</constants>
</class>