godot/doc/classes/Spatial.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Spatial" inherits="Node" category="Core" version="3.1">
	<brief_description>
		Most basic 3D game object, parent of all 3D related nodes.
	</brief_description>
	<description>
		Most basic 3D game object, with a 3D [Transform] and visibility settings. All other 3D game objects inherit from Spatial. Use [code]Spatial[/code] as a parent node to move, scale, rotate and show/hide children in a 3D project.
		Affine operations (rotate, scale, translate) happen in parent's local coordinate system, unless the [code]Spatial[/code] object is set as top level. Affine operations in this coordinate system correspond to direct affine operations on the [code]Spatial[/code]'s transform. The word local below refers to this coordinate system. The coordinate system that is attached to the [code]Spatial[/code] object itself is referred to as object-local coordinate system.
	</description>
	<tutorials>
		<link>https://docs.godotengine.org/en/latest/tutorials/3d/introduction_to_3d.html</link>
	</tutorials>
	<demos>
	</demos>
	<methods>
		<method name="force_update_transform">
			<return type="void">
			</return>
			<description>
			</description>
		</method>
		<method name="get_parent_spatial" qualifiers="const">
			<return type="Spatial">
			</return>
			<description>
				Returns the parent [code]Spatial[/code], or an empty [Object] if no parent exists or parent is not of type [code]Spatial[/code].
			</description>
		</method>
		<method name="get_world" qualifiers="const">
			<return type="World">
			</return>
			<description>
				Returns the current [World] resource this [code]Spatial[/code] node is registered to.
			</description>
		</method>
		<method name="global_rotate">
			<return type="void">
			</return>
			<argument index="0" name="axis" type="Vector3">
			</argument>
			<argument index="1" name="angle" type="float">
			</argument>
			<description>
				Rotates the global (world) transformation around axis, a unit [Vector3], by specified angle in radians. The rotation axis is in global coordinate system.
			</description>
		</method>
		<method name="global_scale">
			<return type="void">
			</return>
			<argument index="0" name="scale" type="Vector3">
			</argument>
			<description>
			</description>
		</method>
		<method name="global_translate">
			<return type="void">
			</return>
			<argument index="0" name="offset" type="Vector3">
			</argument>
			<description>
				Moves the global (world) transformation by [Vector3] offset. The offset is in global coordinate system.
			</description>
		</method>
		<method name="hide">
			<return type="void">
			</return>
			<description>
				Disables rendering of this node. Changes [member visible] to [code]false[/code].
			</description>
		</method>
		<method name="is_local_transform_notification_enabled" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns whether node notifies about its local transformation changes. [code]Spatial[/code] will not propagate this by default.
			</description>
		</method>
		<method name="is_scale_disabled" qualifiers="const">
			<return type="bool">
			</return>
			<description>
			</description>
		</method>
		<method name="is_set_as_toplevel" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns whether this node is set as Toplevel, that is whether it ignores its parent nodes transformations.
			</description>
		</method>
		<method name="is_transform_notification_enabled" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns whether the node notifies about its global and local transformation changes. [code]Spatial[/code] will not propagate this by default.
			</description>
		</method>
		<method name="is_visible_in_tree" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns whether the node is visible, taking into consideration that its parents visibility.
			</description>
		</method>
		<method name="look_at">
			<return type="void">
			</return>
			<argument index="0" name="target" type="Vector3">
			</argument>
			<argument index="1" name="up" type="Vector3">
			</argument>
			<description>
				Rotates itself so that the local -Z axis points towards the [code]target[/code] position.
				The transform will first be rotated around the given [code]up[/code] vector, and then fully aligned to the target by a further rotation around an axis perpendicular to both the [code]target[/code] and [code]up[/code] vectors.
				Operations take place in global space.
			</description>
		</method>
		<method name="look_at_from_position">
			<return type="void">
			</return>
			<argument index="0" name="position" type="Vector3">
			</argument>
			<argument index="1" name="target" type="Vector3">
			</argument>
			<argument index="2" name="up" type="Vector3">
			</argument>
			<description>
				Moves the node to the specified [code]position[/code], and then rotates itself to point toward the [code]target[/code] as per [method look_at]. Operations take place in global space.
			</description>
		</method>
		<method name="orthonormalize">
			<return type="void">
			</return>
			<description>
				Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation by performing Gram-Schmidt orthonormalization on this node's [Transform].
			</description>
		</method>
		<method name="rotate">
			<return type="void">
			</return>
			<argument index="0" name="axis" type="Vector3">
			</argument>
			<argument index="1" name="angle" type="float">
			</argument>
			<description>
				Rotates the local transformation around axis, a unit [Vector3], by specified angle in radians.
			</description>
		</method>
		<method name="rotate_object_local">
			<return type="void">
			</return>
			<argument index="0" name="axis" type="Vector3">
			</argument>
			<argument index="1" name="angle" type="float">
			</argument>
			<description>
				Rotates the local transformation around axis, a unit [Vector3], by specified angle in radians. The rotation axis is in object-local coordinate system.
			</description>
		</method>
		<method name="rotate_x">
			<return type="void">
			</return>
			<argument index="0" name="angle" type="float">
			</argument>
			<description>
				Rotates the local transformation around the X axis by angle in radians
			</description>
		</method>
		<method name="rotate_y">
			<return type="void">
			</return>
			<argument index="0" name="angle" type="float">
			</argument>
			<description>
				Rotates the local transformation around the Y axis by angle in radians.
			</description>
		</method>
		<method name="rotate_z">
			<return type="void">
			</return>
			<argument index="0" name="angle" type="float">
			</argument>
			<description>
				Rotates the local transformation around the Z axis by angle in radians.
			</description>
		</method>
		<method name="scale_object_local">
			<return type="void">
			</return>
			<argument index="0" name="scale" type="Vector3">
			</argument>
			<description>
				Scales the local transformation by given 3D scale factors in object-local coordinate system.
			</description>
		</method>
		<method name="set_as_toplevel">
			<return type="void">
			</return>
			<argument index="0" name="enable" type="bool">
			</argument>
			<description>
				Makes the node ignore its parents transformations. Node transformations are only in global space.
			</description>
		</method>
		<method name="set_disable_scale">
			<return type="void">
			</return>
			<argument index="0" name="disable" type="bool">
			</argument>
			<description>
			</description>
		</method>
		<method name="set_identity">
			<return type="void">
			</return>
			<description>
				Reset all transformations for this node. Set its [Transform] to identity matrix.
			</description>
		</method>
		<method name="set_ignore_transform_notification">
			<return type="void">
			</return>
			<argument index="0" name="enabled" type="bool">
			</argument>
			<description>
				Set whether the node ignores notification that its transformation (global or local) changed.
			</description>
		</method>
		<method name="set_notify_local_transform">
			<return type="void">
			</return>
			<argument index="0" name="enable" type="bool">
			</argument>
			<description>
				Set whether the node notifies about its local transformation changes. [code]Spatial[/code] will not propagate this by default.
			</description>
		</method>
		<method name="set_notify_transform">
			<return type="void">
			</return>
			<argument index="0" name="enable" type="bool">
			</argument>
			<description>
				Set whether the node notifies about its global and local transformation changes. [code]Spatial[/code] will not propagate this by default.
			</description>
		</method>
		<method name="show">
			<return type="void">
			</return>
			<description>
				Enables rendering of this node. Changes [member visible] to [code]true[/code].
			</description>
		</method>
		<method name="to_global" qualifiers="const">
			<return type="Vector3">
			</return>
			<argument index="0" name="local_point" type="Vector3">
			</argument>
			<description>
				Transforms [Vector3] "local_point" from this node's local space to world space.
			</description>
		</method>
		<method name="to_local" qualifiers="const">
			<return type="Vector3">
			</return>
			<argument index="0" name="global_point" type="Vector3">
			</argument>
			<description>
				Transforms [Vector3] "global_point" from world space to this node's local space.
			</description>
		</method>
		<method name="translate">
			<return type="void">
			</return>
			<argument index="0" name="offset" type="Vector3">
			</argument>
			<description>
				Changes the node's position by given offset [Vector3].
			</description>
		</method>
		<method name="translate_object_local">
			<return type="void">
			</return>
			<argument index="0" name="offset" type="Vector3">
			</argument>
			<description>
			</description>
		</method>
		<method name="update_gizmo">
			<return type="void">
			</return>
			<description>
				Updates the [SpatialGizmo] of this node.
			</description>
		</method>
	</methods>
	<members>
		<member name="gizmo" type="SpatialGizmo" setter="set_gizmo" getter="get_gizmo">
			The [SpatialGizmo] for this node. Used for example in [EditorSpatialGizmo] as custom visualization and editing handles in Editor.
		</member>
		<member name="global_transform" type="Transform" setter="set_global_transform" getter="get_global_transform">
			World space (global) [Transform] of this node.
		</member>
		<member name="rotation" type="Vector3" setter="set_rotation" getter="get_rotation">
			Rotation part of the local transformation in radians, specified in terms of YXZ-Euler angles in the format (X-angle, Y-angle, Z-angle).
			Note that in the mathematical sense, rotation is a matrix and not a vector. The three Euler angles, which are the three independent parameters of the Euler-angle parametrization of the rotation matrix, are stored in a [Vector3] data structure not because the rotation is a vector, but only because [Vector3] exists as a convenient data-structure to store 3 floating point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.
		</member>
		<member name="rotation_degrees" type="Vector3" setter="set_rotation_degrees" getter="get_rotation_degrees">
			Rotation part of the local transformation in degrees, specified in terms of YXZ-Euler angles in the format (X-angle, Y-angle, Z-angle).
		</member>
		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale">
			Scale part of the local transformation.
		</member>
		<member name="transform" type="Transform" setter="set_transform" getter="get_transform">
			Local space [Transform] of this node, with respect to the parent node.
		</member>
		<member name="translation" type="Vector3" setter="set_translation" getter="get_translation">
			Local translation of this node.
		</member>
		<member name="visible" type="bool" setter="set_visible" getter="is_visible">
			If [code]true[/code], this node is drawn. Default value: [code]true[/code].
		</member>
	</members>
	<signals>
		<signal name="visibility_changed">
			<description>
				Emitted when node visibility changes.
			</description>
		</signal>
	</signals>
	<constants>
		<constant name="NOTIFICATION_TRANSFORM_CHANGED" value="29">
			Spatial nodes receives this notification when their global transform changes. This means that either the current or a parent node changed its transform.
			In order for [code]NOTIFICATION_TRANSFORM_CHANGED[/code] to work, users first need to ask for it, with [method set_notify_transform].
		</constant>
		<constant name="NOTIFICATION_ENTER_WORLD" value="41">
			Spatial nodes receives this notification when they are registered to new [World] resource.
		</constant>
		<constant name="NOTIFICATION_EXIT_WORLD" value="42">
			Spatial nodes receives this notification when they are unregistered from current [World] resource.
		</constant>
		<constant name="NOTIFICATION_VISIBILITY_CHANGED" value="43">
			Spatial nodes receives this notification when their visibility changes.
		</constant>
	</constants>
</class>