**Inherited By:** ARVRAnchor, ARVRController, ARVROrigin, AudioStreamPlayer3D, BoneAttachment, Camera, CollisionObject, CollisionPolygon, CollisionShape, GridMap, Joint, Listener, Navigation, NavigationMeshInstance, Path, PathFollow, Position3D, ProximityGroup, RayCast, RemoteTransform, Skeleton, SpringArm, VehicleWheel, VisibilityNotifier, VisualInstance

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

## Description

Most basic 3D game object, with a 3D 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

## Properties

SpatialGizmo | gizmo | |

Transform | global_transform | |

Vector3 | rotation | |

Vector3 | rotation_degrees | `Vector3( 0, 0, 0 )` |

Vector3 | scale | `Vector3( 1, 1, 1 )` |

Transform | Transform | `Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )` |

Vector3 | Translation | `Vector3( 0, 0, 0 )` |

bool | visible | `true` |

## Methods

## Signals

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

Emitted when node visibility changes.

## Constants

**NOTIFICATION_TRANSFORM_CHANGED**=**2000**— 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 set_notify_transform.

**NOTIFICATION_ENTER_WORLD**=**41**— Spatial nodes receives this notification when they are registered to new World resource.**NOTIFICATION_EXIT_WORLD**=**42**— Spatial nodes receives this notification when they are unregistered from current World resource.**NOTIFICATION_VISIBILITY_CHANGED**=**43**— Spatial nodes receives this notification when their visibility changes.

## Property Descriptions

- SpatialGizmo
**gizmo**

Setter | set_gizmo(value) |

Getter | get_gizmo() |

The SpatialGizmo for this node. Used for example in EditorSpatialGizmo as custom visualization and editing handles in Editor.

- Transform
**global_transform**

Setter | set_global_transform(value) |

Getter | get_global_transform() |

World space (global) Transform of this node.

- 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:** 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.

- Vector3
**rotation_degrees**

Default | `Vector3( 0, 0, 0 )` |

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).

- Vector3
**scale**

Default | `Vector3( 1, 1, 1 )` |

Setter | set_scale(value) |

Getter | get_scale() |

Scale part of the local transformation.

- Transform
**transform**

Default | `Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )` |

Setter | set_transform(value) |

Getter | get_transform() |

Local space Transform of this node, with respect to the parent node.

- Vector3
**translation**

Default | `Vector3( 0, 0, 0 )` |

Setter | set_translation(value) |

Getter | get_translation() |

Local translation of this node.

- bool
**visible**

Default | `true` |

Setter | set_visible(value) |

Getter | is_visible() |

If `true`

, this node is drawn.

## Method Descriptions

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

Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations.

- Spatial
**get_parent_spatial****(****)**const

Returns the parent `Spatial`

, or an empty Object if no parent exists or parent is not of type `Spatial`

.

- World
**get_world****(****)**const

Returns the current World resource this `Spatial`

node is registered to.

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

- void
**global_scale****(**Vector3 scale**)**

Scales the global (world) transformation by the given Vector3 scale factors.

- void
**global_translate****(**Vector3 offset**)**

Moves the global (world) transformation by Vector3 offset. The offset is in global coordinate system.

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

Disables rendering of this node. Changes visible to `false`

.

- bool
**is_local_transform_notification_enabled****(****)**const

Returns whether node notifies about its local transformation changes. `Spatial`

will not propagate this by default.

- bool
**is_scale_disabled****(****)**const

Returns whether this node uses a scale of `(1, 1, 1)`

or its local transformation scale.

- bool
**is_set_as_toplevel****(****)**const

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

- 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.

- bool
**is_visible_in_tree****(****)**const

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

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.

Moves the node to the specified `position`

, and then rotates itself to point toward the `target`

as per look_at. Operations take place in global space.

- 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 Transform.

Rotates the local transformation around axis, a unit Vector3, by specified angle in radians.

Rotates the local transformation around axis, a unit Vector3, by specified angle in radians. The rotation axis is in object-local coordinate system.

- void
**rotate_x****(**float angle**)**

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

- void
**rotate_y****(**float angle**)**

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

- void
**rotate_z****(**float angle**)**

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

- void
**scale_object_local****(**Vector3 scale**)**

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

- void
**set_as_toplevel****(**bool enable**)**

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

- void
**set_disable_scale****(**bool disable**)**

Sets whether the node uses a scale of `(1, 1, 1)`

or its local transformation scale. Changes to the local transformation scale are preserved.

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

Reset all transformations for this node (sets its Transform to the identity matrix).

- void
**set_ignore_transform_notification****(**bool enabled**)**

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

- void
**set_notify_local_transform****(**bool enable**)**

Sets whether the node notifies about its local transformation changes. `Spatial`

will not propagate this by default.

- void
**set_notify_transform****(**bool enable**)**

Sets whether the node notifies about its global and local transformation changes. `Spatial`

will not propagate this by default.

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

Enables rendering of this node. Changes visible to `true`

.

Transforms `local_point`

from this node’s local space to world space.

Transforms `global_point`

from world space to this node’s local space.

- void
**translate****(**Vector3 offset**)**

Changes the node’s position by the given offset Vector3.

Note that the translation `offset`

is affected by the node’s scale, so if scaled by e.g. `(10, 1, 1)`

, a translation by an offset of `(2, 0, 0)`

would actually add 20 (`2 * 10`

) to the X coordinate.

- void
**translate_object_local****(**Vector3 offset**)**

Changes the node’s position by the given offset Vector3 in local space.

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

Updates the SpatialGizmo of this node.

## Leave a Reply