738f6ea221
This closes https://github.com/godotengine/godot-docs/issues/4010.
(cherry picked from commit cba4d73b71)
530 lines
24 KiB
XML
530 lines
24 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="Object" 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.
|
|
Property membership can be tested directly in GDScript using [code]in[/code]:
|
|
[codeblock]
|
|
var n = Node2D.new()
|
|
print("position" in n) # Prints "True".
|
|
print("other_property" in n) # Prints "False".
|
|
[/codeblock]
|
|
The [code]in[/code] operator will evaluate to [code]true[/code] as long as the key exists, even if the value is [code]null[/code].
|
|
Objects also receive notifications. Notifications are a simple way to notify the object about different events, so they can all be handled together. See [method _notification].
|
|
[b]Note:[/b] Unlike references to a [Reference], references to an Object stored in a variable can become invalid without warning. Therefore, it's recommended to use [Reference] for data classes instead of [Object].
|
|
</description>
|
|
<tutorials>
|
|
<link title="When and how to avoid using nodes for everything">https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="_get" qualifiers="virtual">
|
|
<return type="Variant">
|
|
</return>
|
|
<argument index="0" name="property" type="String">
|
|
</argument>
|
|
<description>
|
|
Virtual method which can be overridden to customize the return value of [method get].
|
|
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>
|
|
Virtual method which can be overridden to customize the return value of [method get_property_list].
|
|
Returns the object's property list as an [Array] of dictionaries.
|
|
Each property's [Dictionary] must contain at least [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries. Optionally, it can also include [code]hint: int[/code] (see [enum PropertyHint]), [code]hint_string: String[/code], and [code]usage: int[/code] (see [enum PropertyUsageFlags]).
|
|
</description>
|
|
</method>
|
|
<method name="_init" qualifiers="virtual">
|
|
<return type="void">
|
|
</return>
|
|
<description>
|
|
Called when the object is initialized.
|
|
</description>
|
|
</method>
|
|
<method name="_notification" qualifiers="virtual">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="what" type="int">
|
|
</argument>
|
|
<description>
|
|
Called whenever the object receives a notification, which is identified in [code]what[/code] by a constant. The base [Object] has two constants [constant NOTIFICATION_POSTINITIALIZE] and [constant NOTIFICATION_PREDELETE], but subclasses such as [Node] define a lot more notifications which are also received by this method.
|
|
</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>
|
|
Virtual method which can be overridden to customize the return value of [method set].
|
|
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>
|
|
Virtual method which can be overridden to customize the return value of [method to_string], and thus the object's representation where it is converted to a string, e.g. with [code]print(obj)[/code].
|
|
Returns a [String] representing the object. If not overridden, defaults to [code]"[ClassName:RID]"[/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 [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries.
|
|
</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 the result. This method supports a variable number of arguments, so parameters are passed as a comma separated list. Example:
|
|
[codeblock]
|
|
call("set", "position", Vector2(42.0, 0.0))
|
|
[/codeblock]
|
|
[b]Note:[/b] In C#, the method name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined methods where you should use the same convention as in the C# source (typically PascalCase).
|
|
</description>
|
|
</method>
|
|
<method name="call_deferred" qualifiers="vararg">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="method" type="String">
|
|
</argument>
|
|
<description>
|
|
Calls the [code]method[/code] on the object during idle time. This method supports a variable number of arguments, so parameters are passed as a comma separated list. Example:
|
|
[codeblock]
|
|
call_deferred("set", "position", Vector2(42.0, 0.0))
|
|
[/codeblock]
|
|
[b]Note:[/b] In C#, the method name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined methods where you should use the same convention as in the C# source (typically PascalCase).
|
|
</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 the result. Contrarily to [method call], this method does not support a variable number of arguments but expects all parameters to be via a single [Array].
|
|
[codeblock]
|
|
callv("set", [ "position", Vector2(42.0, 0.0) ])
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="can_translate_messages" qualifiers="const">
|
|
<return type="bool">
|
|
</return>
|
|
<description>
|
|
Returns [code]true[/code] if the object can translate strings. See [method set_message_translation] and [method tr].
|
|
</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 as an [Array] of parameters. These parameters will be passed to the method after any parameter used in the call to [method emit_signal]. Use [code]flags[/code] to set deferred or one-shot connections. See [enum ConnectFlags] constants.
|
|
A [code]signal[/code] can only be connected once to a [code]method[/code]. It will throw an error if already connected, unless the signal was connected with [constant CONNECT_REFERENCE_COUNTED]. 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.
|
|
Examples:
|
|
[codeblock]
|
|
connect("pressed", self, "_on_Button_pressed") # BaseButton signal
|
|
connect("text_entered", self, "_on_LineEdit_text_entered") # LineEdit signal
|
|
connect("hit", self, "_on_Player_hit", [ weapon_type, damage ]) # User-defined signal
|
|
[/codeblock]
|
|
An example of the relationship between [code]binds[/code] passed to [method connect] and parameters used when calling [method emit_signal]:
|
|
[codeblock]
|
|
connect("hit", self, "_on_Player_hit", [ weapon_type, damage ]) # weapon_type and damage are passed last
|
|
emit_signal("hit", "Dark lord", 5) # "Dark lord" and 5 are passed first
|
|
func _on_Player_hit(hit_by, level, weapon_type, damage):
|
|
print("Hit by %s (lvl %d) with weapon %s for %d damage" % [hit_by, level, weapon_type, damage])
|
|
[/codeblock]
|
|
</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="void">
|
|
</return>
|
|
<argument index="0" name="signal" type="String">
|
|
</argument>
|
|
<description>
|
|
Emits the given [code]signal[/code]. The signal must exist, so it should be a built-in signal of this class or one of its parent classes, or a user-defined signal. This method supports a variable number of arguments, so parameters are passed as a comma separated list. Example:
|
|
[codeblock]
|
|
emit_signal("hit", weapon_type, damage)
|
|
emit_signal("game_over")
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="free">
|
|
<return type="void">
|
|
</return>
|
|
<description>
|
|
Deletes the object from memory. Any pre-existing reference to the freed object will become invalid, e.g. [code]is_instance_valid(object)[/code] will return [code]false[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get" qualifiers="const">
|
|
<return type="Variant">
|
|
</return>
|
|
<argument index="0" name="property" type="String">
|
|
</argument>
|
|
<description>
|
|
Returns the [Variant] value of the given [code]property[/code]. If the [code]property[/code] doesn't exist, this will return [code]null[/code].
|
|
[b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase).
|
|
</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.
|
|
Each [Dictionary] contains three String entries:
|
|
- [code]source[/code] is a reference to the signal emitter.
|
|
- [code]signal_name[/code] is the name of the connected signal.
|
|
- [code]method_name[/code] is the name of the method to which the signal is connected.
|
|
</description>
|
|
</method>
|
|
<method name="get_indexed" qualifiers="const">
|
|
<return type="Variant">
|
|
</return>
|
|
<argument index="0" name="property" type="NodePath">
|
|
</argument>
|
|
<description>
|
|
Gets the object's property indexed by the given [NodePath]. The node path should be relative to the current object and can use the colon character ([code]:[/code]) to access nested properties. Examples: [code]"position:x"[/code] or [code]"material:next_pass:blend_mode"[/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 entry 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 object's property list as an [Array] of dictionaries.
|
|
Each property's [Dictionary] contain at least [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries. Optionally, it can also include [code]hint: int[/code] (see [enum PropertyHint]), [code]hint_string: String[/code], and [code]usage: int[/code] (see [enum PropertyUsageFlags]).
|
|
</description>
|
|
</method>
|
|
<method name="get_script" qualifiers="const">
|
|
<return type="Reference">
|
|
</return>
|
|
<description>
|
|
Returns the object's [Script] instance, or [code]null[/code] if none is assigned.
|
|
</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 entry 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_signal" qualifiers="const">
|
|
<return type="bool">
|
|
</return>
|
|
<argument index="0" name="signal" type="String">
|
|
</argument>
|
|
<description>
|
|
Returns [code]true[/code] if the given [code]signal[/code] exists.
|
|
</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. Only signals added using [method add_user_signal] are taken into account.
|
|
</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="class" type="String">
|
|
</argument>
|
|
<description>
|
|
Returns [code]true[/code] if the object inherits from the given [code]class[/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 [method Node.queue_free] 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>
|
|
Send a given notification to the object, which will also trigger a call to the [method _notification] method of all classes that the object inherits from.
|
|
If [code]reversed[/code] is [code]true[/code], [method _notification] is called first on the object's own class, and then up to its successive parent classes. If [code]reversed[/code] is [code]false[/code], [method _notification] is called first on the highest ancestor ([Object] itself), and then down to its successive inheriting classes.
|
|
</description>
|
|
</method>
|
|
<method name="property_list_changed_notify">
|
|
<return type="void">
|
|
</return>
|
|
<description>
|
|
Notify the editor that the property list has changed, so that editor plugins can take the new values into account. Does nothing on export builds.
|
|
</description>
|
|
</method>
|
|
<method name="remove_meta">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="name" type="String">
|
|
</argument>
|
|
<description>
|
|
Removes a given entry from the object's metadata. See also [method set_meta].
|
|
</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>
|
|
Assigns a new value to the given property. If the [code]property[/code] does not exist, nothing will happen.
|
|
[b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase).
|
|
</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>
|
|
Assigns a new value to the given property, 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].
|
|
[b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase).
|
|
</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>
|
|
Assigns a new value to the property identified by the [NodePath]. The node path should be relative to the current object and can use the colon character ([code]:[/code]) to access nested properties. Example:
|
|
[codeblock]
|
|
set_indexed("position", Vector2(42, 0))
|
|
set_indexed("position:y", -10)
|
|
print(position) # (42, -10)
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="set_message_translation">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="enable" type="bool">
|
|
</argument>
|
|
<description>
|
|
Defines whether the object can translate strings (with calls to [method tr]). Enabled by default.
|
|
</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>
|
|
Adds, changes or removes a given entry in the object's metadata. Metadata are serialized and can take any [Variant] value.
|
|
To remove a given entry from the object's metadata, use [method remove_meta]. Metadata is also removed if its value is set to [code]null[/code]. This means you can also use [code]set_meta("name", null)[/code] to remove metadata for [code]"name"[/code].
|
|
</description>
|
|
</method>
|
|
<method name="set_script">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="script" type="Reference">
|
|
</argument>
|
|
<description>
|
|
Assigns a script to the object. Each object can have a single script assigned to it, which are used to extend its functionality.
|
|
If the object already had a script, the previous script instance will be freed and its variables and state will be lost. The new script's [method _init] method will be called.
|
|
</description>
|
|
</method>
|
|
<method name="to_string">
|
|
<return type="String">
|
|
</return>
|
|
<description>
|
|
Returns a [String] representing the object. If not overridden, defaults to [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>
|
|
Translates a message using translation catalogs configured in the Project Settings.
|
|
Only works if message translation is enabled (which it is by default), otherwise it returns the [code]message[/code] unchanged. See [method set_message_translation].
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<signals>
|
|
<signal name="script_changed">
|
|
<description>
|
|
Emitted whenever the object's script 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">
|
|
Connects 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">
|
|
Connect a signal as reference-counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left.
|
|
</constant>
|
|
</constants>
|
|
</class>
|