class Spatial
package godot
extends Node › Object
extended 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, with a 3D godot.Transform
and visibility settings. All other 3D game objects inherit from Spatial. Use godot.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 godot.Spatial
object is set as top-level. Affine operations in this coordinate system correspond to direct affine operations on the godot.Spatial
's transform. The word local below refers to this coordinate system. The coordinate system that is attached to the godot.Spatial
object itself is referred to as object-local coordinate system.
Note: Unless otherwise specified, all methods that have angle parameters must have angles specified as radians. To convert degrees to radians, use @GDScript.deg2rad
.
Static variables
staticread onlyNOTIFICATION_ENTER_GAMEPLAY:Int
Spatial nodes receives this notification if the portal system gameplay monitor detects they have entered the gameplay area.
staticread onlyNOTIFICATION_ENTER_WORLD:Int
Spatial nodes receives this notification when they are registered to new godot.World
resource.
staticread onlyNOTIFICATION_EXIT_GAMEPLAY:Int
Spatial nodes receives this notification if the portal system gameplay monitor detects they have exited the gameplay area.
staticread onlyNOTIFICATION_EXIT_WORLD:Int
Spatial nodes receives this notification when they are unregistered from current godot.World
resource.
staticread onlyNOTIFICATION_TRANSFORM_CHANGED:Int
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 godot.Spatial.notificationTransformChanged
to work, users first need to ask for it, with godot.Spatial.setNotifyTransform
. The notification is also sent if the node is in the editor context and it has a valid gizmo.
staticread onlyNOTIFICATION_VISIBILITY_CHANGED:Int
Spatial nodes receives this notification when their visibility changes.
Constructor
Variables
gizmo:SpatialGizmo
The godot.SpatialGizmo
for this node. Used for example in Godot.EditorSpatialGizmo
as custom visualization and editing handles in Editor.
rotation:Vector3
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 godot.Vector3
data structure not because the rotation is a vector, but only because godot.Vector3
exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.
rotationDegrees:Vector3
Rotation part of the local transformation in degrees, specified in terms of YXZ-Euler angles in the format (X angle, Y angle, Z angle).
visible:Bool
If true
, this node is drawn. The node is only visible if all of its antecedents are visible as well (in other words, godot.Spatial.isVisibleInTree
must return true
).
Methods
forceUpdateTransform():Void
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.
getParentSpatial():Spatial
Returns the parent godot.Spatial
, or an empty godot.Object
if no parent exists or parent is not of type godot.Spatial
.
globalRotate(axis:Vector3, angle:Single):Void
Rotates the global (world) transformation around axis, a unit godot.Vector3
, by specified angle in radians. The rotation axis is in global coordinate system.
globalScale(scale:Vector3):Void
Scales the global (world) transformation by the given godot.Vector3
scale factors.
globalTranslate(offset:Vector3):Void
Moves the global (world) transformation by godot.Vector3
offset. The offset is in global coordinate system.
isLocalTransformNotificationEnabled():Bool
Returns whether node notifies about its local transformation changes. godot.Spatial
will not propagate this by default.
isScaleDisabled():Bool
Returns whether this node uses a scale of (1, 1, 1)
or its local transformation scale.
isSetAsToplevel():Bool
Returns whether this node is set as Toplevel, that is whether it ignores its parent nodes transformations.
isTransformNotificationEnabled():Bool
Returns whether the node notifies about its global and local transformation changes. godot.Spatial
will not propagate this by default.
isVisibleInTree():Bool
Returns true
if the node is present in the godot.SceneTree
, its godot.Spatial.visible
property is true
and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree.
lookAt(target:Vector3, up:Vector3):Void
Rotates the node so that the local forward axis (-Z) points toward the target
position.
The local up axis (+Y) points as close to the up
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.
The target
position cannot be the same as the node's position, the up
vector cannot be zero, and the direction from the node's position to the target
vector cannot be parallel to the up
vector.
Operations take place in global space.
lookAtFromPosition(position:Vector3, target:Vector3, up:Vector3):Void
Moves the node to the specified position
, and then rotates itself to point toward the target
as per godot.Spatial.lookAt
. Operations take place in global space.
orthonormalize():Void
Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation by performing Gram-Schmidt orthonormalization on this node's godot.Transform
.
rotate(axis:Vector3, angle:Single):Void
Rotates the local transformation around axis, a unit godot.Vector3
, by specified angle in radians.
rotateObjectLocal(axis:Vector3, angle:Single):Void
Rotates the local transformation around axis, a unit godot.Vector3
, by specified angle in radians. The rotation axis is in object-local coordinate system.
scaleObjectLocal(scale:Vector3):Void
Scales the local transformation by given 3D scale factors in object-local coordinate system.
setAsToplevel(enable:Bool):Void
Makes the node ignore its parents transformations. Node transformations are only in global space.
setDisableScale(disable:Bool):Void
Sets whether the node uses a scale of (1, 1, 1)
or its local transformation scale. Changes to the local transformation scale are preserved.
setIdentity():Void
Reset all transformations for this node (sets its godot.Transform
to the identity matrix).
setIgnoreTransformNotification(enabled:Bool):Void
Sets whether the node ignores notification that its transformation (global or local) changed.
setNotifyLocalTransform(enable:Bool):Void
Sets whether the node notifies about its local transformation changes. godot.Spatial
will not propagate this by default.
setNotifyTransform(enable:Bool):Void
Sets whether the node notifies about its global and local transformation changes. godot.Spatial
will not propagate this by default, unless it is in the editor context and it has a valid gizmo.
toGlobal(localPoint:Vector3):Vector3
Transforms local_point
from this node's local space to world space.
toLocal(globalPoint:Vector3):Vector3
Transforms global_point
from world space to this node's local space.
translate(offset:Vector3):Void
Changes the node's position by the given offset godot.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.
translateObjectLocal(offset:Vector3):Void
Changes the node's position by the given offset godot.Vector3
in local space.