Node3D

package
v0.0.0-...-20ed0ac Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2025 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

The Node3D node is the base representation of a node in 3D space. All other 3D nodes inherit from this class.

Affine operations (translation, rotation, scale) are calculated in the coordinate system relative to the parent, unless the Node3D's TopLevel is true. In this coordinate system, affine operations correspond to direct affine operations on the Node3D's Transform. The term parent space refers to this coordinate system. The coordinate system that is attached to the Node3D itself is referred to as object-local coordinate system, or local space.

Note: Unless otherwise specified, all methods that need angle parameters must receive angles in radians. To convert degrees to radians, use @GlobalScope.DegToRad.

Note: In Godot 3 and older, Node3D was named Spatial.

Index

Constants

View Source
const NotificationEnterWorld Object.Notification = 41 //gd:Node3D.NOTIFICATION_ENTER_WORLD
View Source
const NotificationExitWorld Object.Notification = 42 //gd:Node3D.NOTIFICATION_EXIT_WORLD
View Source
const NotificationLocalTransformChanged Object.Notification = 44 //gd:Node3D.NOTIFICATION_LOCAL_TRANSFORM_CHANGED
View Source
const NotificationTransformChanged Object.Notification = 2000 //gd:Node3D.NOTIFICATION_TRANSFORM_CHANGED
View Source
const NotificationVisibilityChanged Object.Notification = 43 //gd:Node3D.NOTIFICATION_VISIBILITY_CHANGED

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any

type Any interface {
	gd.IsClass
	AsNode3D() Instance
}

type Expanded

type Expanded = MoreArgs

type Extension

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsNode

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode3D

func (self *Extension[T]) AsNode3D() Instance

func (*Extension[T]) AsObject

func (self *Extension[T]) AsObject() [1]gd.Object

type ID

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance

func (id ID) Instance() (Instance, bool)

type Instance

type Instance [1]gdclass.Node3D

Instance of the class with convieniently typed arguments and results.

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New

func New() Instance

func (Instance) AddGizmo

func (self Instance) AddGizmo(gizmo Node3DGizmo.Instance)

Attaches the given 'gizmo' to this node. Only works in the editor.

Note: 'gizmo' should be an EditorNode3DGizmo. The argument type is Node3DGizmo to avoid depending on editor classes in Node3D.

func (Instance) AsNode

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode3D

func (self Instance) AsNode3D() Instance

func (Instance) AsObject

func (self Instance) AsObject() [1]gd.Object

func (Instance) Basis

func (self Instance) Basis() Basis.XYZ

Basis of the Transform property. Represents the rotation, scale, and shear of this node in parent space (relative to the parent node).

func (Instance) ClearGizmos

func (self Instance) ClearGizmos()

Clears all EditorNode3DGizmo objects attached to this node. Only works in the editor.

func (Instance) ClearSubgizmoSelection

func (self Instance) ClearSubgizmoSelection()

Deselects all subgizmos for this node. Useful to call when the selected subgizmo may no longer exist after a property change. Only works in the editor.

func (Instance) ForceUpdateTransform

func (self Instance) ForceUpdateTransform()

Forces the node's GlobalTransform to update, by sending NotificationTransformChanged. Fails if the node is not inside the tree.

Note: For performance reasons, transform changes are usually accumulated and applied once at the end of the frame. The update propagates through Node3D children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations).

func (Instance) GetGizmos

func (self Instance) GetGizmos() []Node3DGizmo.Instance

Returns all the EditorNode3DGizmo objects attached to this node. Only works in the editor.

func (Instance) GetGlobalTransformInterpolated

func (self Instance) GetGlobalTransformInterpolated() Transform3D.BasisOrigin

When using physics interpolation, there will be circumstances in which you want to know the interpolated (displayed) transform of a node rather than the standard transform (which may only be accurate to the most recent physics tick).

This is particularly important for frame-based operations that take place in Node.Process, rather than Node.PhysicsProcess. Examples include Camera3Ds focusing on a node, or finding where to fire lasers from on a frame rather than physics tick.

Note: This function creates an interpolation pump on the Node3D the first time it is called, which can respond to physics interpolation resets. If you get problems with "streaking" when initially following a Node3D, be sure to call GetGlobalTransformInterpolated at least once before resetting the Node3D physics interpolation.

func (Instance) GetParentNode3d

func (self Instance) GetParentNode3d() Instance

Returns the parent Node3D that directly affects this node's GlobalTransform. Returns null if no parent exists, the parent is not a Node3D, or TopLevel is true.

Note: This method is not always equivalent to Node.GetParent, which does not take TopLevel into account.

func (Instance) GetWorld3d

func (self Instance) GetWorld3d() World3D.Instance

Returns the World3D this node is registered to.

Usually, this is the same as the world used by this node's viewport (see Node.GetViewport and Viewport.FindWorld3d).

func (Instance) GlobalBasis

func (self Instance) GlobalBasis() Basis.XYZ

Basis of the GlobalTransform property. Represents the rotation, scale, and shear of this node in global space (relative to the world).

Note: If the node is not inside the tree, getting this property fails and returns [Basis.Identity].

func (Instance) GlobalPosition

func (self Instance) GlobalPosition() Vector3.XYZ

Global position (translation) of this node in global space (relative to the world). This is equivalent to the GlobalTransform's Transform3D.Origin.

Note: If the node is not inside the tree, getting this property fails and returns [Vector3.Zero].

func (Instance) GlobalRotate

func (self Instance) GlobalRotate(axis Vector3.XYZ, angle Angle.Radians)

Rotates this node's GlobalBasis around the global 'axis' by the given 'angle', in radians. This operation is calculated in global space (relative to the world) and preserves the GlobalPosition.

func (Instance) GlobalRotation

func (self Instance) GlobalRotation() Euler.Radians

Global rotation of this node as Euler angles, in radians and in global space (relative to the world). This value is obtained from GlobalBasis's rotation.

- The Vector3.X is the angle around the global X axis (pitch);

- The Vector3.Y is the angle around the global Y axis (yaw);

- The Vector3.Z is the angle around the global Z axis (roll).

Note: Unlike Rotation, this property always follows the YXZ convention ([EulerOrderYxz]).

Note: If the node is not inside the tree, getting this property fails and returns [Vector3.Zero].

func (Instance) GlobalRotationDegrees

func (self Instance) GlobalRotationDegrees() Euler.Degrees

The GlobalRotation of this node, in degrees instead of radians.

Note: If the node is not inside the tree, getting this property fails and returns [Vector3.Zero].

func (Instance) GlobalScale

func (self Instance) GlobalScale(scale Vector3.XYZ)

Scales this node's GlobalBasis by the given 'scale' factor. This operation is calculated in global space (relative to the world) and preserves the GlobalPosition.

Note: This method is not to be confused with the Scale property.

func (Instance) GlobalTransform

func (self Instance) GlobalTransform() Transform3D.BasisOrigin

The transformation of this node, in global space (relative to the world). Contains and represents this node's GlobalPosition, GlobalRotation, and global scale.

Note: If the node is not inside the tree, getting this property fails and returns [Transform3d.Identity].

func (Instance) GlobalTranslate

func (self Instance) GlobalTranslate(offset Vector3.XYZ)

Adds the given translation 'offset' to the node's GlobalPosition in global space (relative to the world).

func (Instance) Hide

func (self Instance) Hide()

Prevents this node from being rendered. Equivalent to setting Visible to false. This is the opposite of Show.

func (Instance) ID

func (self Instance) ID() ID

func (Instance) IsLocalTransformNotificationEnabled

func (self Instance) IsLocalTransformNotificationEnabled() bool

Returns true if the node receives NotificationLocalTransformChanged whenever Transform changes. This is enabled with SetNotifyLocalTransform.

func (Instance) IsScaleDisabled

func (self Instance) IsScaleDisabled() bool

Returns true if this node's GlobalTransform is automatically orthonormalized. This results in this node not appearing distorted, as if its global scale were set to [Vector3.One] (or its negative counterpart). See also SetDisableScale and Orthonormalize.

Note: Transform is not affected by this setting.

func (Instance) IsTransformNotificationEnabled

func (self Instance) IsTransformNotificationEnabled() bool

Returns true if the node receives NotificationTransformChanged whenever GlobalTransform changes. This is enabled with SetNotifyTransform.

func (Instance) IsVisibleInTree

func (self Instance) IsVisibleInTree() bool

Returns true if this node is inside the scene tree and the Visible property is true for this node and all of its Node3D ancestors in sequence. An ancestor of any other type (such as Node or Node2D) breaks the sequence. See also Node.GetParent.

Note: This method cannot take VisualInstance3D.Layers into account, so even if this method returns true, the node may not be rendered.

func (Instance) LookAt

func (self Instance) LookAt(target Vector3.XYZ)

Rotates the node so that the local forward axis (-Z, [Vector3.Forward]) points toward the 'target' position. This operation is calculated in global space (relative to the world).

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 [Vector3.Zero]. Furthermore, the direction from the node's position to the 'target' position cannot be parallel to the 'up' vector, to avoid an unintended rotation around the local Z axis.

If 'use_model_front' is true, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the 'target' position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).

Note: This method fails if the node is not in the scene tree. If necessary, use LookAtFromPosition instead.

func (Instance) LookAtFromPosition

func (self Instance) LookAtFromPosition(position Vector3.XYZ, target Vector3.XYZ)

Moves the node to the specified 'position', then rotates the node to point toward the 'target' position, similar to LookAt. This operation is calculated in global space (relative to the world).

func (Instance) MoreArgs

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) OnVisibilityChanged

func (self Instance) OnVisibilityChanged(cb func(), flags ...Signal.Flags)

Emitted when this node's visibility changes (see Visible and IsVisibleInTree).

This signal is emitted after the related NotificationVisibilityChanged notification.

func (Instance) Orthonormalize

func (self Instance) Orthonormalize()

Orthonormalizes this node's Basis. This method sets this node's Scale to [Vector3.One] (or its negative counterpart), but preserves the Position and Rotation. See also Transform3D.Orthonormalized.

func (Instance) Position

func (self Instance) Position() Vector3.XYZ

Position (translation) of this node in parent space (relative to the parent node). This is equivalent to the Transform's Transform3D.Origin.

func (Instance) Quaternion

func (self Instance) Quaternion() Quaternion.IJKX

Rotation of this node represented as a Quaternion.IJKX in parent space (relative to the parent node). This value is obtained from Basis's rotation.

Note: Quaternions are much more suitable for 3D math but are less intuitive. Setting this property can be useful for interpolation (see Quaternion.Slerp).

func (Instance) Rotate

func (self Instance) Rotate(axis Vector3.XYZ, angle Angle.Radians)

Rotates this node's Basis around the 'axis' by the given 'angle', in radians. This operation is calculated in parent space (relative to the parent) and preserves the Position.

func (Instance) RotateObjectLocal

func (self Instance) RotateObjectLocal(axis Vector3.XYZ, angle Angle.Radians)

Rotates this node's Basis around the 'axis' by the given 'angle', in radians. This operation is calculated in local space (relative to this node) and preserves the Position.

func (Instance) RotateX

func (self Instance) RotateX(angle Angle.Radians)

Rotates this node's Basis around the X axis by the given 'angle', in radians. This operation is calculated in parent space (relative to the parent) and preserves the Position.

func (Instance) RotateY

func (self Instance) RotateY(angle Angle.Radians)

Rotates this node's Basis around the Y axis by the given 'angle', in radians. This operation is calculated in parent space (relative to the parent) and preserves the Position.

func (Instance) RotateZ

func (self Instance) RotateZ(angle Angle.Radians)

Rotates this node's Basis around the Z axis by the given 'angle', in radians. This operation is calculated in parent space (relative to the parent) and preserves the Position.

func (Instance) Rotation

func (self Instance) Rotation() Euler.Radians

Rotation of this node as Euler angles, in radians and in parent space (relative to the parent node). This value is obtained from Basis's rotation.

- The Vector3.X is the angle around the local X axis (pitch);

- The Vector3.Y is the angle around the local Y axis (yaw);

- The Vector3.Z is the angle around the local Z axis (roll).

The order of each consecutive rotation can be changed with RotationOrder (see [EulerOrder] constants). By default, the YXZ convention is used ([EulerOrderYxz]).

Note: This property is edited in degrees in the inspector. If you want to use degrees in a script, use RotationDegrees.

func (Instance) RotationDegrees

func (self Instance) RotationDegrees() Euler.Degrees

The Rotation of this node, in degrees instead of radians.

Note: This is not the property available in the Inspector dock.

func (Instance) RotationEditMode

func (self Instance) RotationEditMode() RotationEditMode

How this node's rotation and scale are displayed in the Inspector dock.

func (Instance) RotationOrder

func (self Instance) RotationOrder() Angle.Order

The axis rotation order of the Rotation property. The final orientation is calculated by rotating around the local X, Y, and Z axis in this order.

func (Instance) Scale

func (self Instance) Scale() Vector3.XYZ

Scale of this node in local space (relative to this node). This value is obtained from Basis's scale.

Note: The behavior of some 3D node types is not affected by this property. These include Light3D, Camera3D, AudioStreamPlayer3D, and more.

Warning: The scale's components must either be all positive or all negative, and not exactly 0.0. Otherwise, it won't be possible to obtain the scale from the Basis. This may cause the intended scale to be lost when reloaded from disk, and potentially other unstable behavior.

func (Instance) ScaleObjectLocal

func (self Instance) ScaleObjectLocal(scale Vector3.XYZ)

Scales this node's Basis by the given 'scale' factor. This operation is calculated in local space (relative to this node) and preserves the Position.

func (Instance) SetBasis

func (self Instance) SetBasis(value Basis.XYZ)

SetBasis sets the property returned by [GetBasis].

func (Instance) SetDisableScale

func (self Instance) SetDisableScale(disable bool)

If true, this node's GlobalTransform is automatically orthonormalized. This results in this node not appearing distorted, as if its global scale were set to [Vector3.One] (or its negative counterpart). See also IsScaleDisabled and Orthonormalize.

Note: Transform is not affected by this setting.

func (Instance) SetGlobalBasis

func (self Instance) SetGlobalBasis(value Basis.XYZ)

SetGlobalBasis sets the property returned by [GetGlobalBasis].

func (Instance) SetGlobalPosition

func (self Instance) SetGlobalPosition(value Vector3.XYZ)

SetGlobalPosition sets the property returned by [GetGlobalPosition].

func (Instance) SetGlobalRotation

func (self Instance) SetGlobalRotation(value Euler.Radians)

SetGlobalRotation sets the property returned by [GetGlobalRotation].

func (Instance) SetGlobalRotationDegrees

func (self Instance) SetGlobalRotationDegrees(value Euler.Degrees)

SetGlobalRotationDegrees sets the property returned by [GetGlobalRotationDegrees].

func (Instance) SetGlobalTransform

func (self Instance) SetGlobalTransform(value Transform3D.BasisOrigin)

SetGlobalTransform sets the property returned by [GetGlobalTransform].

func (Instance) SetIdentity

func (self Instance) SetIdentity()

Sets this node's Transform to [Transform3d.Identity], which resets all transformations in parent space (Position, Rotation, and Scale).

func (Instance) SetIgnoreTransformNotification

func (self Instance) SetIgnoreTransformNotification(enabled bool)

If true, the node will not receive NotificationTransformChanged or NotificationLocalTransformChanged.

It may useful to call this method when handling these notifications to prevent infinite recursion.

func (Instance) SetNotifyLocalTransform

func (self Instance) SetNotifyLocalTransform(enable bool)

If true, the node will receive NotificationLocalTransformChanged whenever Transform changes.

Note: Some 3D nodes such as CSGShape3D or CollisionShape3D automatically enable this to function correctly.

func (Instance) SetNotifyTransform

func (self Instance) SetNotifyTransform(enable bool)

If true, the node will receive NotificationTransformChanged whenever GlobalTransform changes.

Note: Most 3D nodes such as VisualInstance3D or CollisionObject3D automatically enable this to function correctly.

Note: In the editor, nodes will propagate this notification to their children if a gizmo is attached (see AddGizmo).

func (*Instance) SetObject

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetPosition

func (self Instance) SetPosition(value Vector3.XYZ)

SetPosition sets the property returned by [GetPosition].

func (Instance) SetQuaternion

func (self Instance) SetQuaternion(value Quaternion.IJKX)

SetQuaternion sets the property returned by [GetQuaternion].

func (Instance) SetRotation

func (self Instance) SetRotation(value Euler.Radians)

SetRotation sets the property returned by [GetRotation].

func (Instance) SetRotationDegrees

func (self Instance) SetRotationDegrees(value Euler.Degrees)

SetRotationDegrees sets the property returned by [GetRotationDegrees].

func (Instance) SetRotationEditMode

func (self Instance) SetRotationEditMode(value RotationEditMode)

SetRotationEditMode sets the property returned by [GetRotationEditMode].

func (Instance) SetRotationOrder

func (self Instance) SetRotationOrder(value Angle.Order)

SetRotationOrder sets the property returned by [GetRotationOrder].

func (Instance) SetScale

func (self Instance) SetScale(value Vector3.XYZ)

SetScale sets the property returned by [GetScale].

func (Instance) SetSubgizmoSelection

func (self Instance) SetSubgizmoSelection(gizmo Node3DGizmo.Instance, id int, transform Transform3D.BasisOrigin)

Selects the 'gizmo”s subgizmo with the given 'id' and sets its transform. Only works in the editor.

Note: The gizmo object would typically be an instance of EditorNode3DGizmo, but the argument type is kept generic to avoid creating a dependency on editor classes in Node3D.

func (Instance) SetTopLevel

func (self Instance) SetTopLevel(value bool)

SetTopLevel sets the property returned by [IsSetAsTopLevel].

func (Instance) SetTransform

func (self Instance) SetTransform(value Transform3D.BasisOrigin)

SetTransform sets the property returned by [GetTransform].

func (Instance) SetVisibilityParent

func (self Instance) SetVisibilityParent(value string)

SetVisibilityParent sets the property returned by [GetVisibilityParent].

func (Instance) SetVisible

func (self Instance) SetVisible(value bool)

SetVisible sets the property returned by [IsVisible].

func (Instance) Show

func (self Instance) Show()

Allows this node to be rendered. Equivalent to setting Visible to true. This is the opposite of Hide.

func (Instance) ToGlobal

func (self Instance) ToGlobal(local_point Vector3.XYZ) Vector3.XYZ

Returns the 'local_point' converted from this node's local space to global space. This is the opposite of ToLocal.

func (Instance) ToLocal

func (self Instance) ToLocal(global_point Vector3.XYZ) Vector3.XYZ

Returns the 'global_point' converted from global space to this node's local space. This is the opposite of ToGlobal.

func (Instance) TopLevel

func (self Instance) TopLevel() bool

If true, the node does not inherit its transformations from its parent. As such, node transformations will only be in global space, which also means that GlobalTransform and Transform will be identical.

func (Instance) Transform

func (self Instance) Transform() Transform3D.BasisOrigin

The local transformation of this node, in parent space (relative to the parent node). Contains and represents this node's Position, Rotation, and Scale.

func (Instance) Translate

func (self Instance) Translate(offset Vector3.XYZ)

Adds the given translation 'offset' to the node's position, in local space (relative to this node).

Note: Prefer using TranslateObjectLocal, instead, as this method may be changed in a future release.

Note: Despite the naming convention, this operation is not calculated in parent space for compatibility reasons. To translate in parent space, add 'offset' to the Position (node_3d.position += offset).

func (Instance) TranslateObjectLocal

func (self Instance) TranslateObjectLocal(offset Vector3.XYZ)

Adds the given translation 'offset' to the node's position, in local space (relative to this node).

func (Instance) UpdateGizmos

func (self Instance) UpdateGizmos()

Updates all the EditorNode3DGizmo objects attached to this node. Only works in the editor.

func (Instance) Virtual

func (self Instance) Virtual(name string) reflect.Value

func (Instance) VisibilityParent

func (self Instance) VisibilityParent() string

Path to the visibility range parent for this node and its descendants. The visibility parent must be a GeometryInstance3D.

Any visual instance will only be visible if the visibility parent (and all of its visibility ancestors) is hidden by being closer to the camera than its own GeometryInstance3D.VisibilityRangeBegin. Nodes hidden via the Node3D.Visible property are essentially removed from the visibility dependency tree, so dependent instances will not take the hidden node or its descendants into account.

func (Instance) Visible

func (self Instance) Visible() bool

If true, this node can be visible. The node is only rendered when all of its ancestors are visible, as well. That means IsVisibleInTree must return true.

type MoreArgs

type MoreArgs [1]gdclass.Node3D

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) LookAt

func (self MoreArgs) LookAt(target Vector3.XYZ, up Vector3.XYZ, use_model_front bool)

Rotates the node so that the local forward axis (-Z, [Vector3.Forward]) points toward the 'target' position. This operation is calculated in global space (relative to the world).

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 [Vector3.Zero]. Furthermore, the direction from the node's position to the 'target' position cannot be parallel to the 'up' vector, to avoid an unintended rotation around the local Z axis.

If 'use_model_front' is true, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the 'target' position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).

Note: This method fails if the node is not in the scene tree. If necessary, use LookAtFromPosition instead.

func (MoreArgs) LookAtFromPosition

func (self MoreArgs) LookAtFromPosition(position Vector3.XYZ, target Vector3.XYZ, up Vector3.XYZ, use_model_front bool)

Moves the node to the specified 'position', then rotates the node to point toward the 'target' position, similar to LookAt. This operation is calculated in global space (relative to the world).

type RotationEditMode

type RotationEditMode int //gd:Node3D.RotationEditMode
const (
	// The rotation is edited using a [Vector3.XYZ] in [Euler angles].
	//
	// [Euler angles]: https://en.wikipedia.org/wiki/Euler_angles
	// [Vector3.XYZ]: https://pkg.go.dev/graphics.gd/variant/Vector3#XYZ
	RotationEditModeEuler RotationEditMode = 0
	// The rotation is edited using a [Quaternion.IJKX].
	//
	// [Quaternion.IJKX]: https://pkg.go.dev/graphics.gd/variant/Quaternion#IJKX
	RotationEditModeQuaternion RotationEditMode = 1
	// The rotation is edited using a [Basis.XYZ]. In this mode, the raw [Basis]'s axes can be freely modified, but the [Scale] property is not available.
	//
	// [Basis]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Basis
	// [Basis.XYZ]: https://pkg.go.dev/graphics.gd/variant/Basis#XYZ
	// [Scale]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Scale
	RotationEditModeBasis RotationEditMode = 2
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL