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:`Joint<class_joint>`, :ref:`RayCast<class_raycast>`, :ref:`Camera<class_camera>`, :ref:`BoneAttachment<class_boneattachment>`, :ref:`CollisionShape<class_collisionshape>`, :ref:`AudioStreamPlayer3D<class_audiostreamplayer3d>`, :ref:`Path<class_path>`, :ref:`ARVRController<class_arvrcontroller>`, :ref:`VisualInstance<class_visualinstance>`, :ref:`VehicleWheel<class_vehiclewheel>`, :ref:`Position3D<class_position3d>`, :ref:`ProximityGroup<class_proximitygroup>`, :ref:`ARVRAnchor<class_arvranchor>`, :ref:`RemoteTransform<class_remotetransform>`, :ref:`CollisionObject<class_collisionobject>`, :ref:`PathFollow<class_pathfollow>`, :ref:`NavigationMeshInstance<class_navigationmeshinstance>`, :ref:`Listener<class_listener>`, :ref:`VisibilityNotifier<class_visibilitynotifier>`, :ref:`Navigation<class_navigation>`, :ref:`CollisionPolygon<class_collisionpolygon>`, :ref:`GridMap<class_gridmap>`, :ref:`Skeleton<class_skeleton>`, :ref:`ARVROrigin<class_arvrorigin>`

**Category:** Core

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

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

Member Functions
----------------

+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`SpatialGizmo<class_spatialgizmo>`  | :ref:`get_gizmo<class_Spatial_get_gizmo>` **(** **)** const                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Transform<class_transform>`        | :ref:`get_global_transform<class_Spatial_get_global_transform>` **(** **)** const                                                                                                            |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Spatial<class_spatial>`            | :ref:`get_parent_spatial<class_Spatial_get_parent_spatial>` **(** **)** const                                                                                                                |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`get_rotation<class_Spatial_get_rotation>` **(** **)** const                                                                                                                            |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`get_rotation_deg<class_Spatial_get_rotation_deg>` **(** **)** const                                                                                                                    |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`get_scale<class_Spatial_get_scale>` **(** **)** const                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Transform<class_transform>`        | :ref:`get_transform<class_Spatial_get_transform>` **(** **)** const                                                                                                                          |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`get_translation<class_Spatial_get_translation>` **(** **)** const                                                                                                                      |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`World<class_world>`                | :ref:`get_world<class_Spatial_get_world>` **(** **)** const                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`global_rotate<class_Spatial_global_rotate>` **(** :ref:`Vector3<class_vector3>` normal, :ref:`float<class_float>` radians **)**                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`global_translate<class_Spatial_global_translate>` **(** :ref:`Vector3<class_vector3>` offset **)**                                                                                     |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`hide<class_Spatial_hide>` **(** **)**                                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                  | :ref:`is_local_transform_notification_enabled<class_Spatial_is_local_transform_notification_enabled>` **(** **)** const                                                                      |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                  | :ref:`is_set_as_toplevel<class_Spatial_is_set_as_toplevel>` **(** **)** const                                                                                                                |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                  | :ref:`is_transform_notification_enabled<class_Spatial_is_transform_notification_enabled>` **(** **)** const                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                  | :ref:`is_visible<class_Spatial_is_visible>` **(** **)** const                                                                                                                                |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                  | :ref:`is_visible_in_tree<class_Spatial_is_visible_in_tree>` **(** **)** const                                                                                                                |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`look_at<class_Spatial_look_at>` **(** :ref:`Vector3<class_vector3>` target, :ref:`Vector3<class_vector3>` up **)**                                                                     |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`look_at_from_position<class_Spatial_look_at_from_position>` **(** :ref:`Vector3<class_vector3>` position, :ref:`Vector3<class_vector3>` target, :ref:`Vector3<class_vector3>` up **)** |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`orthonormalize<class_Spatial_orthonormalize>` **(** **)**                                                                                                                              |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`rotate<class_Spatial_rotate>` **(** :ref:`Vector3<class_vector3>` normal, :ref:`float<class_float>` radians **)**                                                                      |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`rotate_x<class_Spatial_rotate_x>` **(** :ref:`float<class_float>` radians **)**                                                                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`rotate_y<class_Spatial_rotate_y>` **(** :ref:`float<class_float>` radians **)**                                                                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`rotate_z<class_Spatial_rotate_z>` **(** :ref:`float<class_float>` radians **)**                                                                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_as_toplevel<class_Spatial_set_as_toplevel>` **(** :ref:`bool<class_bool>` enable **)**                                                                                             |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_gizmo<class_Spatial_set_gizmo>` **(** :ref:`SpatialGizmo<class_spatialgizmo>` gizmo **)**                                                                                          |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_global_transform<class_Spatial_set_global_transform>` **(** :ref:`Transform<class_transform>` global **)**                                                                         |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_identity<class_Spatial_set_identity>` **(** **)**                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_ignore_transform_notification<class_Spatial_set_ignore_transform_notification>` **(** :ref:`bool<class_bool>` enabled **)**                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_notify_local_transform<class_Spatial_set_notify_local_transform>` **(** :ref:`bool<class_bool>` enable **)**                                                                       |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_notify_transform<class_Spatial_set_notify_transform>` **(** :ref:`bool<class_bool>` enable **)**                                                                                   |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_rotation<class_Spatial_set_rotation>` **(** :ref:`Vector3<class_vector3>` rotation_rad **)**                                                                                       |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_rotation_deg<class_Spatial_set_rotation_deg>` **(** :ref:`Vector3<class_vector3>` rotation_deg **)**                                                                               |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_scale<class_Spatial_set_scale>` **(** :ref:`Vector3<class_vector3>` scale **)**                                                                                                    |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_transform<class_Spatial_set_transform>` **(** :ref:`Transform<class_transform>` local **)**                                                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_translation<class_Spatial_set_translation>` **(** :ref:`Vector3<class_vector3>` translation **)**                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`set_visible<class_Spatial_set_visible>` **(** :ref:`bool<class_bool>` visible **)**                                                                                                    |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`show<class_Spatial_show>` **(** **)**                                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`to_global<class_Spatial_to_global>` **(** :ref:`Vector3<class_vector3>` local_point **)** const                                                                                        |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Vector3<class_vector3>`            | :ref:`to_local<class_Spatial_to_local>` **(** :ref:`Vector3<class_vector3>` global_point **)** const                                                                                         |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`translate<class_Spatial_translate>` **(** :ref:`Vector3<class_vector3>` offset **)**                                                                                                   |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                     | :ref:`update_gizmo<class_Spatial_update_gizmo>` **(** **)**                                                                                                                                  |
+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_Spatial_visibility_changed:

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

Emitted when node visibility changes.


Member Variables
----------------

  .. _class_Spatial_global_transform:

- :ref:`Transform<class_transform>` **global_transform** - World space (global) :ref:`Transform<class_transform>` of this node.

  .. _class_Spatial_rotation:

- :ref:`Vector3<class_vector3>` **rotation** - Local euler rotation in radians of this node.

  .. _class_Spatial_rotation_deg:

- :ref:`Vector3<class_vector3>` **rotation_deg** - Local euler rotation in degrees of this node.

  .. _class_Spatial_scale:

- :ref:`Vector3<class_vector3>` **scale** - Local scale of this node.

  .. _class_Spatial_transform:

- :ref:`Transform<class_transform>` **transform** - Local space :ref:`Transform<class_transform>` of this node.

  .. _class_Spatial_translation:

- :ref:`Vector3<class_vector3>` **translation** - Local translation of this node.

  .. _class_Spatial_visible:

- :ref:`bool<class_bool>` **visible** - Visibility of this node. Toggles if this node is rendered.


Numeric Constants
-----------------

- **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 user first needs to ask for it, with set_notify_transform(true).
- **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.

Member Function Description
---------------------------

.. _class_Spatial_get_gizmo:

- :ref:`SpatialGizmo<class_spatialgizmo>` **get_gizmo** **(** **)** const

Returns the SpatialGizmo for this node. Used for example in :ref:`EditorSpatialGizmo<class_editorspatialgizmo>` as custom visualization and editing handles in Editor.

.. _class_Spatial_get_global_transform:

- :ref:`Transform<class_transform>` **get_global_transform** **(** **)** const

Returns the global transform, relative to worldspace.

.. _class_Spatial_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_get_rotation:

- :ref:`Vector3<class_vector3>` **get_rotation** **(** **)** const

Returns the rotation (in radians).

.. _class_Spatial_get_rotation_deg:

- :ref:`Vector3<class_vector3>` **get_rotation_deg** **(** **)** const

Returns the rotation (in degrees).

.. _class_Spatial_get_scale:

- :ref:`Vector3<class_vector3>` **get_scale** **(** **)** const

.. _class_Spatial_get_transform:

- :ref:`Transform<class_transform>` **get_transform** **(** **)** const

Returns the local transform, relative to the bone parent.

.. _class_Spatial_get_translation:

- :ref:`Vector3<class_vector3>` **get_translation** **(** **)** const

.. _class_Spatial_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_global_rotate:

- void **global_rotate** **(** :ref:`Vector3<class_vector3>` normal, :ref:`float<class_float>` radians **)**

Rotates the current node along normal :ref:`Vector3<class_vector3>` by angle in radians in Global space.

.. _class_Spatial_global_translate:

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

Moves the node by :ref:`Vector3<class_vector3>` offset in Global space.

.. _class_Spatial_hide:

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

Disables rendering of this node. Change Spatial Visible property to false.

.. _class_Spatial_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_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_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_is_visible:

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

Returns whether the node is set to be visible.

.. _class_Spatial_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_look_at:

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

Rotates itself to point into direction of target position. Operations take place in global space.

.. _class_Spatial_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 specified position and then rotates itself to point into direction of target position. Operations take place in global space.

.. _class_Spatial_orthonormalize:

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

Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation. Performs orthonormalization on this node Transform3D.

.. _class_Spatial_rotate:

- void **rotate** **(** :ref:`Vector3<class_vector3>` normal, :ref:`float<class_float>` radians **)**

Rotates the node in local space on given normal :ref:`Vector3<class_vector3>` by angle in radians.

.. _class_Spatial_rotate_x:

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

Rotates the node in local space on X axis by angle in radians.

.. _class_Spatial_rotate_y:

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

Rotates the node in local space on Y axis by angle in radians.

.. _class_Spatial_rotate_z:

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

Rotates the node in local space on Z axis by angle in radians.

.. _class_Spatial_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_set_gizmo:

- void **set_gizmo** **(** :ref:`SpatialGizmo<class_spatialgizmo>` gizmo **)**

Set :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_set_global_transform:

- void **set_global_transform** **(** :ref:`Transform<class_transform>` global **)**

Set the transform globally, relative to world space.

.. _class_Spatial_set_identity:

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

Reset all transformations for this node. Set its Transform3D to identity matrix.

.. _class_Spatial_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_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_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_set_rotation:

- void **set_rotation** **(** :ref:`Vector3<class_vector3>` rotation_rad **)**

Set the rotation (in radians).

.. _class_Spatial_set_rotation_deg:

- void **set_rotation_deg** **(** :ref:`Vector3<class_vector3>` rotation_deg **)**

Set the rotation (in degrees).

.. _class_Spatial_set_scale:

- void **set_scale** **(** :ref:`Vector3<class_vector3>` scale **)**

Set the scale.

.. _class_Spatial_set_transform:

- void **set_transform** **(** :ref:`Transform<class_transform>` local **)**

Set the transform locally, relative to the parent spatial node.

.. _class_Spatial_set_translation:

- void **set_translation** **(** :ref:`Vector3<class_vector3>` translation **)**

.. _class_Spatial_set_visible:

- void **set_visible** **(** :ref:`bool<class_bool>` visible **)**

.. _class_Spatial_show:

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

Enables rendering of this node. Change Spatial Visible property to "True".

.. _class_Spatial_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_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_translate:

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

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

.. _class_Spatial_update_gizmo:

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

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