Spatial

Inherits:Node<Object

Inherited By:ARVRAnchor,ARVRController,ARVROrigin,AudioStreamPlayer3D,BoneAttachment,Camera,CollisionObject,CollisionPolygon,CollisionShape,CullInstance,GridMap,Joint,Listener,Navigation,NavigationMeshInstance,Occluder,Path,PathFollow,Portal,Position3D,ProximityGroup,RayCast,RemoteTransform,Room,RoomGroup,RoomManager,Skeleton,SpringArm,VehicleWheel

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

Description

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

Note: Unless otherwise specified, all methods that have angle parameters must have angles specified asradians. To convert degrees to radians, use@GDScript.deg2rad.

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

void

force_update_transform()

Spatial

get_parent_spatial()const

World

get_world()const

void

global_rotate(Vector3 axis,float angle)

void

global_scale(Vector3 scale)

void

global_translate(Vector3 offset)

void

hide()

bool

is_local_transform_notification_enabled()const

bool

is_scale_disabled()const

bool

is_set_as_toplevel()const

bool

is_transform_notification_enabled()const

bool

is_visible_in_tree()const

void

look_at(Vector3 target,Vector3 up)

void

look_at_from_position(Vector3 position,Vector3 target,Vector3 up)

void

orthonormalize()

void

rotate(Vector3 axis,float angle)

void

rotate_object_local(Vector3 axis,float angle)

void

rotate_x(float angle)

void

rotate_y(float angle)

void

rotate_z(float angle)

void

scale_object_local(Vector3 scale)

void

set_as_toplevel(bool enable)

void

set_disable_scale(bool disable)

void

set_identity()

void

set_ignore_transform_notification(bool enabled)

void

set_notify_local_transform(bool enable)

void

set_notify_transform(bool enable)

void

show()

Vector3

to_global(Vector3 local_point)const

Vector3

to_local(Vector3 global_point)const

void

translate(Vector3 offset)

void

translate_object_local(Vector3 offset)

void

update_gizmo()

Signals

  • gameplay_entered()

Emitted by portal system gameplay monitor when a node enters the gameplay area.

  • gameplay_exited()

Emitted by portal system gameplay monitor when a node exits the gameplay area.

  • 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 forNOTIFICATION_TRANSFORM_CHANGED to work, users first need to ask for it, withset_notify_transform. The notification is also sent if the node is in the editor context and it has a valid gizmo.

  • NOTIFICATION_ENTER_WORLD =41 --- Spatial nodes receives this notification when they are registered to newWorld resource.

  • NOTIFICATION_EXIT_WORLD =42 --- Spatial nodes receives this notification when they are unregistered from currentWorld resource.

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

  • NOTIFICATION_ENTER_GAMEPLAY =45 --- Spatial nodes receives this notification if the portal system gameplay monitor detects they have entered the gameplay area.

  • NOTIFICATION_EXIT_GAMEPLAY =46 --- Spatial nodes receives this notification if the portal system gameplay monitor detects they have exited the gameplay area.

Property Descriptions

Setter

set_gizmo(value)

Getter

get_gizmo()

TheSpatialGizmo for this node. Used for example inEditorSpatialGizmo as custom visualization and editing handles in Editor.

Setter

set_global_transform(value)

Getter

get_global_transform()

World space (global)Transform of this node.

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 aVector3 data structure not because the rotation is a vector, but only becauseVector3 exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.

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

Default

Vector3(1,1,1)

Setter

set_scale(value)

Getter

get_scale()

Scale part of the local transformation.

Default

Transform(1,0,0,0,1,0,0,0,1,0,0,0)

Setter

set_transform(value)

Getter

get_transform()

Local spaceTransform of this node, with respect to the parent node.

Default

Vector3(0,0,0)

Setter

set_translation(value)

Getter

get_translation()

Local translation of this node.

Default

true

Setter

set_visible(value)

Getter

is_visible()

Iftrue, this node is drawn. The node is only visible if all of its antecedents are visible as well (in other words,is_visible_in_tree must returntrue).

Method Descriptions

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

Returns the parentSpatial, or an emptyObject if no parent exists or parent is not of typeSpatial.

Returns the currentWorld resource thisSpatial node is registered to.

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

Scales the global (world) transformation by the givenVector3 scale factors.

  • voidglobal_translate(Vector3 offset)

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

  • voidhide()

Disables rendering of this node. Changesvisible tofalse.

  • boolis_local_transform_notification_enabled()const

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

Returns whether this node uses a scale of(1,1,1) or its local transformation scale.

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

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

Returnstrue if the node is present in theSceneTree, itsvisible property istrue and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree.

Rotates the node so that the local forward axis (-Z) points toward thetarget position.

The local up axis (+Y) points as close to theup vector as possible while staying perpendicular to the local forward axis. The resulting transform is orthogonal, and the scale is preserved. Non-uniform scaling may not work correctly.

Thetarget position cannot be the same as the node's position, theup vector cannot be zero, and the direction from the node's position to thetarget vector cannot be parallel to theup vector.

Operations take place in global space.

Moves the node to the specifiedposition, and then rotates itself to point toward thetarget as perlook_at. Operations take place in global space.

  • voidorthonormalize()

Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation by performing Gram-Schmidt orthonormalization on this node'sTransform.

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

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

  • voidrotate_x(float angle)

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

  • voidrotate_y(float angle)

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

  • voidrotate_z(float angle)

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

  • voidscale_object_local(Vector3 scale)

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

  • voidset_as_toplevel(bool enable)

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

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

  • voidset_identity()

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

  • voidset_ignore_transform_notification(bool enabled)

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

  • voidset_notify_local_transform(bool enable)

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

  • voidset_notify_transform(bool enable)

Sets whether the node notifies about its global and local transformation changes.Spatial will not propagate this by default, unless it is in the editor context and it has a valid gizmo.

  • voidshow()

Enables rendering of this node. Changesvisible totrue.

Transformslocal_point from this node's local space to world space.

Transformsglobal_point from world space to this node's local space.

Changes the node's position by the given offsetVector3.

Note that the translationoffset 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.

  • voidtranslate_object_local(Vector3 offset)

Changes the node's position by the given offsetVector3 in local space.

  • voidupdate_gizmo()

Updates theSpatialGizmo of this node.