godot-docs/classes/class_spatial.rst

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the Spatial.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_Spatial:

Spatial
=======

**Inherits:** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

**Inherited By:** :ref:`ARVRAnchor<class_ARVRAnchor>`, :ref:`ARVRController<class_ARVRController>`, :ref:`ARVROrigin<class_ARVROrigin>`, :ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>`, :ref:`BoneAttachment<class_BoneAttachment>`, :ref:`Camera<class_Camera>`, :ref:`CollisionObject<class_CollisionObject>`, :ref:`CollisionPolygon<class_CollisionPolygon>`, :ref:`CollisionShape<class_CollisionShape>`, :ref:`GridMap<class_GridMap>`, :ref:`Joint<class_Joint>`, :ref:`Listener<class_Listener>`, :ref:`Navigation<class_Navigation>`, :ref:`NavigationMeshInstance<class_NavigationMeshInstance>`, :ref:`Path<class_Path>`, :ref:`PathFollow<class_PathFollow>`, :ref:`Position3D<class_Position3D>`, :ref:`ProximityGroup<class_ProximityGroup>`, :ref:`RayCast<class_RayCast>`, :ref:`RemoteTransform<class_RemoteTransform>`, :ref:`Skeleton<class_Skeleton>`, :ref:`SpringArm<class_SpringArm>`, :ref:`VehicleWheel<class_VehicleWheel>`, :ref:`VisibilityNotifier<class_VisibilityNotifier>`, :ref:`VisualInstance<class_VisualInstance>`

**Category:** Core

Brief Description
-----------------

Most basic 3D game object, parent of all 3D related nodes.

Properties
----------

+-----------------------------------------+------------------------------------------------------------------+
| :ref:`SpatialGizmo<class_SpatialGizmo>` | :ref:`gizmo<class_Spatial_property_gizmo>`                       |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Transform<class_Transform>`       | :ref:`global_transform<class_Spatial_property_global_transform>` |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>`           | :ref:`rotation<class_Spatial_property_rotation>`                 |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>`           | :ref:`rotation_degrees<class_Spatial_property_rotation_degrees>` |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>`           | :ref:`scale<class_Spatial_property_scale>`                       |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Transform<class_Transform>`       | :ref:`transform<class_Spatial_property_transform>`               |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>`           | :ref:`translation<class_Spatial_property_translation>`           |
+-----------------------------------------+------------------------------------------------------------------+
| :ref:`bool<class_bool>`                 | :ref:`visible<class_Spatial_property_visible>`                   |
+-----------------------------------------+------------------------------------------------------------------+

Methods
-------

+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`force_update_transform<class_Spatial_method_force_update_transform>` **(** **)**                                                                                                              |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Spatial<class_Spatial>` | :ref:`get_parent_spatial<class_Spatial_method_get_parent_spatial>` **(** **)** const                                                                                                                |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`World<class_World>`     | :ref:`get_world<class_Spatial_method_get_world>` **(** **)** const                                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`global_rotate<class_Spatial_method_global_rotate>` **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**                                                            |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`global_scale<class_Spatial_method_global_scale>` **(** :ref:`Vector3<class_Vector3>` scale **)**                                                                                              |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`global_translate<class_Spatial_method_global_translate>` **(** :ref:`Vector3<class_Vector3>` offset **)**                                                                                     |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`hide<class_Spatial_method_hide>` **(** **)**                                                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`       | :ref:`is_local_transform_notification_enabled<class_Spatial_method_is_local_transform_notification_enabled>` **(** **)** const                                                                      |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`       | :ref:`is_scale_disabled<class_Spatial_method_is_scale_disabled>` **(** **)** const                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`       | :ref:`is_set_as_toplevel<class_Spatial_method_is_set_as_toplevel>` **(** **)** const                                                                                                                |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`       | :ref:`is_transform_notification_enabled<class_Spatial_method_is_transform_notification_enabled>` **(** **)** const                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`       | :ref:`is_visible_in_tree<class_Spatial_method_is_visible_in_tree>` **(** **)** const                                                                                                                |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`look_at<class_Spatial_method_look_at>` **(** :ref:`Vector3<class_Vector3>` target, :ref:`Vector3<class_Vector3>` up **)**                                                                     |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`look_at_from_position<class_Spatial_method_look_at_from_position>` **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` target, :ref:`Vector3<class_Vector3>` up **)** |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`orthonormalize<class_Spatial_method_orthonormalize>` **(** **)**                                                                                                                              |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`rotate<class_Spatial_method_rotate>` **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**                                                                          |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`rotate_object_local<class_Spatial_method_rotate_object_local>` **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**                                                |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`rotate_x<class_Spatial_method_rotate_x>` **(** :ref:`float<class_float>` angle **)**                                                                                                          |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`rotate_y<class_Spatial_method_rotate_y>` **(** :ref:`float<class_float>` angle **)**                                                                                                          |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`rotate_z<class_Spatial_method_rotate_z>` **(** :ref:`float<class_float>` angle **)**                                                                                                          |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`scale_object_local<class_Spatial_method_scale_object_local>` **(** :ref:`Vector3<class_Vector3>` scale **)**                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_as_toplevel<class_Spatial_method_set_as_toplevel>` **(** :ref:`bool<class_bool>` enable **)**                                                                                             |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_disable_scale<class_Spatial_method_set_disable_scale>` **(** :ref:`bool<class_bool>` disable **)**                                                                                        |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_identity<class_Spatial_method_set_identity>` **(** **)**                                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_ignore_transform_notification<class_Spatial_method_set_ignore_transform_notification>` **(** :ref:`bool<class_bool>` enabled **)**                                                        |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_notify_local_transform<class_Spatial_method_set_notify_local_transform>` **(** :ref:`bool<class_bool>` enable **)**                                                                       |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_notify_transform<class_Spatial_method_set_notify_transform>` **(** :ref:`bool<class_bool>` enable **)**                                                                                   |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`show<class_Spatial_method_show>` **(** **)**                                                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>` | :ref:`to_global<class_Spatial_method_to_global>` **(** :ref:`Vector3<class_Vector3>` local_point **)** const                                                                                        |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_Vector3>` | :ref:`to_local<class_Spatial_method_to_local>` **(** :ref:`Vector3<class_Vector3>` global_point **)** const                                                                                         |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`translate<class_Spatial_method_translate>` **(** :ref:`Vector3<class_Vector3>` offset **)**                                                                                                   |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`translate_object_local<class_Spatial_method_translate_object_local>` **(** :ref:`Vector3<class_Vector3>` offset **)**                                                                         |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`update_gizmo<class_Spatial_method_update_gizmo>` **(** **)**                                                                                                                                  |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_Spatial_signal_visibility_changed:

- **visibility_changed** **(** **)**

Emitted when node visibility changes.

Constants
---------

.. _class_Spatial_constant_NOTIFICATION_TRANSFORM_CHANGED:

.. _class_Spatial_constant_NOTIFICATION_ENTER_WORLD:

.. _class_Spatial_constant_NOTIFICATION_EXIT_WORLD:

.. _class_Spatial_constant_NOTIFICATION_VISIBILITY_CHANGED:

- **NOTIFICATION_TRANSFORM_CHANGED** = **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 ``NOTIFICATION_TRANSFORM_CHANGED`` to work, users first need to ask for it, with :ref:`set_notify_transform<class_Spatial_method_set_notify_transform>`.

- **NOTIFICATION_ENTER_WORLD** = **41** --- Spatial nodes receives this notification when they are registered to new :ref:`World<class_World>` resource.

- **NOTIFICATION_EXIT_WORLD** = **42** --- Spatial nodes receives this notification when they are unregistered from current :ref:`World<class_World>` resource.

- **NOTIFICATION_VISIBILITY_CHANGED** = **43** --- Spatial nodes receives this notification when their visibility changes.

Description
-----------

Most basic 3D game object, with a 3D :ref:`Transform<class_Transform>` and visibility settings. All other 3D game objects inherit from Spatial. Use ``Spatial`` 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 ``Spatial`` object is set as top level. Affine operations in this coordinate system correspond to direct affine operations on the ``Spatial``'s transform. The word local below refers to this coordinate system. The coordinate system that is attached to the ``Spatial`` object itself is referred to as object-local coordinate system.

Tutorials
---------

- :doc:`../tutorials/3d/introduction_to_3d`

Property Descriptions
---------------------

.. _class_Spatial_property_gizmo:

- :ref:`SpatialGizmo<class_SpatialGizmo>` **gizmo**

+----------+------------------+
| *Setter* | set_gizmo(value) |
+----------+------------------+
| *Getter* | get_gizmo()      |
+----------+------------------+

The :ref:`SpatialGizmo<class_SpatialGizmo>` for this node. Used for example in :ref:`EditorSpatialGizmo<class_EditorSpatialGizmo>` as custom visualization and editing handles in Editor.

.. _class_Spatial_property_global_transform:

- :ref:`Transform<class_Transform>` **global_transform**

+----------+-----------------------------+
| *Setter* | set_global_transform(value) |
+----------+-----------------------------+
| *Getter* | get_global_transform()      |
+----------+-----------------------------+

World space (global) :ref:`Transform<class_Transform>` of this node.

.. _class_Spatial_property_rotation:

- :ref:`Vector3<class_Vector3>` **rotation**

+----------+---------------------+
| *Setter* | set_rotation(value) |
+----------+---------------------+
| *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 :ref:`Vector3<class_Vector3>` data structure not because the rotation is a vector, but only because :ref:`Vector3<class_Vector3>` exists as a convenient data-structure to store 3 floating point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.

.. _class_Spatial_property_rotation_degrees:

- :ref:`Vector3<class_Vector3>` **rotation_degrees**

+----------+-----------------------------+
| *Setter* | set_rotation_degrees(value) |
+----------+-----------------------------+
| *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).

.. _class_Spatial_property_scale:

- :ref:`Vector3<class_Vector3>` **scale**

+----------+------------------+
| *Setter* | set_scale(value) |
+----------+------------------+
| *Getter* | get_scale()      |
+----------+------------------+

Scale part of the local transformation.

.. _class_Spatial_property_transform:

- :ref:`Transform<class_Transform>` **transform**

+----------+----------------------+
| *Setter* | set_transform(value) |
+----------+----------------------+
| *Getter* | get_transform()      |
+----------+----------------------+

Local space :ref:`Transform<class_Transform>` of this node, with respect to the parent node.

.. _class_Spatial_property_translation:

- :ref:`Vector3<class_Vector3>` **translation**

+----------+------------------------+
| *Setter* | set_translation(value) |
+----------+------------------------+
| *Getter* | get_translation()      |
+----------+------------------------+

Local translation of this node.

.. _class_Spatial_property_visible:

- :ref:`bool<class_bool>` **visible**

+----------+--------------------+
| *Setter* | set_visible(value) |
+----------+--------------------+
| *Getter* | is_visible()       |
+----------+--------------------+

If ``true``, this node is drawn. Default value: ``true``.

Method Descriptions
-------------------

.. _class_Spatial_method_force_update_transform:

- void **force_update_transform** **(** **)**

.. _class_Spatial_method_get_parent_spatial:

- :ref:`Spatial<class_Spatial>` **get_parent_spatial** **(** **)** const

Returns the parent ``Spatial``, or an empty :ref:`Object<class_Object>` if no parent exists or parent is not of type ``Spatial``.

.. _class_Spatial_method_get_world:

- :ref:`World<class_World>` **get_world** **(** **)** const

Returns the current :ref:`World<class_World>` resource this ``Spatial`` node is registered to.

.. _class_Spatial_method_global_rotate:

- void **global_rotate** **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**

Rotates the global (world) transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians. The rotation axis is in global coordinate system.

.. _class_Spatial_method_global_scale:

- void **global_scale** **(** :ref:`Vector3<class_Vector3>` scale **)**

.. _class_Spatial_method_global_translate:

- void **global_translate** **(** :ref:`Vector3<class_Vector3>` offset **)**

Moves the global (world) transformation by :ref:`Vector3<class_Vector3>` offset. The offset is in global coordinate system.

.. _class_Spatial_method_hide:

- void **hide** **(** **)**

Disables rendering of this node. Changes :ref:`visible<class_Spatial_property_visible>` to ``false``.

.. _class_Spatial_method_is_local_transform_notification_enabled:

- :ref:`bool<class_bool>` **is_local_transform_notification_enabled** **(** **)** const

Returns whether node notifies about its local transformation changes. ``Spatial`` will not propagate this by default.

.. _class_Spatial_method_is_scale_disabled:

- :ref:`bool<class_bool>` **is_scale_disabled** **(** **)** const

.. _class_Spatial_method_is_set_as_toplevel:

- :ref:`bool<class_bool>` **is_set_as_toplevel** **(** **)** const

Returns whether this node is set as Toplevel, that is whether it ignores its parent nodes transformations.

.. _class_Spatial_method_is_transform_notification_enabled:

- :ref:`bool<class_bool>` **is_transform_notification_enabled** **(** **)** const

Returns whether the node notifies about its global and local transformation changes. ``Spatial`` will not propagate this by default.

.. _class_Spatial_method_is_visible_in_tree:

- :ref:`bool<class_bool>` **is_visible_in_tree** **(** **)** const

Returns whether the node is visible, taking into consideration that its parents visibility.

.. _class_Spatial_method_look_at:

- void **look_at** **(** :ref:`Vector3<class_Vector3>` target, :ref:`Vector3<class_Vector3>` up **)**

Rotates itself so that the local -Z axis points towards the ``target`` position.

The transform will first be rotated around the given ``up`` vector, and then fully aligned to the target by a further rotation around an axis perpendicular to both the ``target`` and ``up`` vectors.

Operations take place in global space.

.. _class_Spatial_method_look_at_from_position:

- void **look_at_from_position** **(** :ref:`Vector3<class_Vector3>` position, :ref:`Vector3<class_Vector3>` target, :ref:`Vector3<class_Vector3>` up **)**

Moves the node to the specified ``position``, and then rotates itself to point toward the ``target`` as per :ref:`look_at<class_Spatial_method_look_at>`. Operations take place in global space.

.. _class_Spatial_method_orthonormalize:

- void **orthonormalize** **(** **)**

Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation by performing Gram-Schmidt orthonormalization on this node's :ref:`Transform<class_Transform>`.

.. _class_Spatial_method_rotate:

- void **rotate** **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**

Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians.

.. _class_Spatial_method_rotate_object_local:

- void **rotate_object_local** **(** :ref:`Vector3<class_Vector3>` axis, :ref:`float<class_float>` angle **)**

Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians. The rotation axis is in object-local coordinate system.

.. _class_Spatial_method_rotate_x:

- void **rotate_x** **(** :ref:`float<class_float>` angle **)**

Rotates the local transformation around the X axis by angle in radians

.. _class_Spatial_method_rotate_y:

- void **rotate_y** **(** :ref:`float<class_float>` angle **)**

Rotates the local transformation around the Y axis by angle in radians.

.. _class_Spatial_method_rotate_z:

- void **rotate_z** **(** :ref:`float<class_float>` angle **)**

Rotates the local transformation around the Z axis by angle in radians.

.. _class_Spatial_method_scale_object_local:

- void **scale_object_local** **(** :ref:`Vector3<class_Vector3>` scale **)**

Scales the local transformation by given 3D scale factors in object-local coordinate system.

.. _class_Spatial_method_set_as_toplevel:

- void **set_as_toplevel** **(** :ref:`bool<class_bool>` enable **)**

Makes the node ignore its parents transformations. Node transformations are only in global space.

.. _class_Spatial_method_set_disable_scale:

- void **set_disable_scale** **(** :ref:`bool<class_bool>` disable **)**

.. _class_Spatial_method_set_identity:

- void **set_identity** **(** **)**

Reset all transformations for this node. Set its :ref:`Transform<class_Transform>` to identity matrix.

.. _class_Spatial_method_set_ignore_transform_notification:

- void **set_ignore_transform_notification** **(** :ref:`bool<class_bool>` enabled **)**

Set whether the node ignores notification that its transformation (global or local) changed.

.. _class_Spatial_method_set_notify_local_transform:

- void **set_notify_local_transform** **(** :ref:`bool<class_bool>` enable **)**

Set whether the node notifies about its local transformation changes. ``Spatial`` will not propagate this by default.

.. _class_Spatial_method_set_notify_transform:

- void **set_notify_transform** **(** :ref:`bool<class_bool>` enable **)**

Set whether the node notifies about its global and local transformation changes. ``Spatial`` will not propagate this by default.

.. _class_Spatial_method_show:

- void **show** **(** **)**

Enables rendering of this node. Changes :ref:`visible<class_Spatial_property_visible>` to ``true``.

.. _class_Spatial_method_to_global:

- :ref:`Vector3<class_Vector3>` **to_global** **(** :ref:`Vector3<class_Vector3>` local_point **)** const

Transforms :ref:`Vector3<class_Vector3>` "local_point" from this node's local space to world space.

.. _class_Spatial_method_to_local:

- :ref:`Vector3<class_Vector3>` **to_local** **(** :ref:`Vector3<class_Vector3>` global_point **)** const

Transforms :ref:`Vector3<class_Vector3>` "global_point" from world space to this node's local space.

.. _class_Spatial_method_translate:

- void **translate** **(** :ref:`Vector3<class_Vector3>` offset **)**

Changes the node's position by given offset :ref:`Vector3<class_Vector3>`.

.. _class_Spatial_method_translate_object_local:

- void **translate_object_local** **(** :ref:`Vector3<class_Vector3>` offset **)**

.. _class_Spatial_method_update_gizmo:

- void **update_gizmo** **(** **)**

Updates the :ref:`SpatialGizmo<class_SpatialGizmo>` of this node.