Node3D

package
v0.0.0-...-ff35923 Latest Latest
Warning

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

 Go to latest Published: Sep 16, 2025 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

The graphics.gd/classdb/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 graphics.gd/classdb/Node3D's Instance.TopLevel is true. In this coordinate system, affine operations correspond to direct affine operations on the graphics.gd/classdb/Node3D's Instance.Transform. The term parent space refers to this coordinate system. The coordinate system that is attached to the graphics.gd/classdb/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 [graphics.gd/classdb/@GlobalScope.Instance.DegToRad].

Note: In Godot 3 and older, graphics.gd/classdb/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 [1]gdclass.Node3D

func (Expanded) LookAt 

func (self Expanded) 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 Instance.LookAtFromPosition instead.

func (Expanded) LookAtFromPosition 

func (self Expanded) 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 Instance.LookAt. This operation is calculated in global space (relative to the world).

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 graphics.gd/classdb/EditorNode3DGizmo. The argument type is graphics.gd/classdb/Node3DGizmo to avoid depending on editor classes in graphics.gd/classdb/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

func (Instance) ClearGizmos 

func (self Instance) ClearGizmos()

Clears all graphics.gd/classdb/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 Instance.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 graphics.gd/classdb/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 graphics.gd/classdb/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 graphics.gd/classdb/Node.Instance.Process, rather than graphics.gd/classdb/Node.Instance.PhysicsProcess. Examples include [graphics.gd/classdb/Camera3D]s 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 graphics.gd/classdb/Node3D the first time it is called, which can respond to physics interpolation resets. If you get problems with "streaking" when initially following a graphics.gd/classdb/Node3D, be sure to call Instance.GetGlobalTransformInterpolated at least once before resetting the graphics.gd/classdb/Node3D physics interpolation.

func (Instance) GetParentNode3d 

func (self Instance) GetParentNode3d() Instance

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

Note: This method is not always equivalent to graphics.gd/classdb/Node.Instance.GetParent, which does not take Instance.TopLevel into account.

func (Instance) GetWorld3d 

func (self Instance) GetWorld3d() World3D.Instance

Returns the graphics.gd/classdb/World3D this node is registered to.

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

func (Instance) GlobalBasis 

func (self Instance) GlobalBasis() Basis.XYZ

func (Instance) GlobalPosition 

func (self Instance) GlobalPosition() Vector3.XYZ

func (Instance) GlobalRotate 

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

Rotates this node's Instance.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 Instance.GlobalPosition.

func (Instance) GlobalRotation 

func (self Instance) GlobalRotation() Euler.Radians

func (Instance) GlobalRotationDegrees 

func (self Instance) GlobalRotationDegrees() Euler.Degrees

func (Instance) GlobalScale 

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

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

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

func (Instance) GlobalTransform 

func (self Instance) GlobalTransform() Transform3D.BasisOrigin

func (Instance) GlobalTranslate 

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

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

func (Instance) Hide 

func (self Instance) Hide()

Prevents this node from being rendered. Equivalent to setting Instance.Visible to false. This is the opposite of Instance.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 Instance.Transform changes. This is enabled with Instance.SetNotifyLocalTransform.

func (Instance) IsScaleDisabled 

func (self Instance) IsScaleDisabled() bool

Returns true if this node's Instance.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 Instance.SetDisableScale and Instance.Orthonormalize.

Note: Instance.Transform is not affected by this setting.

func (Instance) IsTransformNotificationEnabled 

func (self Instance) IsTransformNotificationEnabled() bool

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

func (Instance) IsVisibleInTree 

func (self Instance) IsVisibleInTree() bool

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

Note: This method cannot take graphics.gd/classdb/VisualInstance3D.Instance.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 Instance.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 Instance.LookAt. This operation is calculated in global space (relative to the world).

func (Instance) OnVisibilityChanged 

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

func (Instance) Orthonormalize 

func (self Instance) Orthonormalize()

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

func (Instance) Position 

func (self Instance) Position() Vector3.XYZ

func (Instance) Quaternion 

func (self Instance) Quaternion() Quaternion.IJKX

func (Instance) Rotate 

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

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

func (Instance) RotateObjectLocal 

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

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

func (Instance) RotateX 

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

Rotates this node's Instance.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 Instance.Position.

func (Instance) RotateY 

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

Rotates this node's Instance.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 Instance.Position.

func (Instance) RotateZ 

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

Rotates this node's Instance.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 Instance.Position.

func (Instance) Rotation 

func (self Instance) Rotation() Euler.Radians

func (Instance) RotationDegrees 

func (self Instance) RotationDegrees() Euler.Degrees

func (Instance) RotationEditMode 

func (self Instance) RotationEditMode() RotationEditMode

func (Instance) RotationOrder 

func (self Instance) RotationOrder() Angle.Order

func (Instance) Scale 

func (self Instance) Scale() Vector3.XYZ

func (Instance) ScaleObjectLocal 

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

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

func (Instance) SetBasis 

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

func (Instance) SetDisableScale 

func (self Instance) SetDisableScale(disable bool)

If true, this node's Instance.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 Instance.IsScaleDisabled and Instance.Orthonormalize.

Note: Instance.Transform is not affected by this setting.

func (Instance) SetGlobalBasis 

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

func (Instance) SetGlobalPosition 

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

func (Instance) SetGlobalRotation 

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

func (Instance) SetGlobalRotationDegrees 

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

func (Instance) SetGlobalTransform 

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

func (Instance) SetIdentity 

func (self Instance) SetIdentity()

Sets this node's Instance.Transform to [Transform3d.Identity], which resets all transformations in parent space (Instance.Position, Instance.Rotation, and Instance.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 Instance.Transform changes.

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

func (Instance) SetNotifyTransform 

func (self Instance) SetNotifyTransform(enable bool)

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

Note: Most 3D nodes such as graphics.gd/classdb/VisualInstance3D or graphics.gd/classdb/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 Instance.AddGizmo).

func (*Instance) SetObject 

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

func (Instance) SetPosition 

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

func (Instance) SetQuaternion 

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

func (Instance) SetRotation 

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

func (Instance) SetRotationDegrees 

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

func (Instance) SetRotationEditMode 

func (self Instance) SetRotationEditMode(value RotationEditMode)

func (Instance) SetRotationOrder 

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

func (Instance) SetScale 

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

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 graphics.gd/classdb/EditorNode3DGizmo, but the argument type is kept generic to avoid creating a dependency on editor classes in graphics.gd/classdb/Node3D.

func (Instance) SetTopLevel 

func (self Instance) SetTopLevel(value bool)

func (Instance) SetTransform 

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

func (Instance) SetVisibilityParent 

func (self Instance) SetVisibilityParent(value string)

func (Instance) SetVisible 

func (self Instance) SetVisible(value bool)

func (Instance) Show 

func (self Instance) Show()

Allows this node to be rendered. Equivalent to setting Instance.Visible to true. This is the opposite of Instance.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 Instance.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 Instance.ToGlobal.

func (Instance) TopLevel 

func (self Instance) TopLevel() bool

func (Instance) Transform 

func (self Instance) Transform() Transform3D.BasisOrigin

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 Instance.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 Instance.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 graphics.gd/classdb/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

func (Instance) Visible 

func (self Instance) Visible() bool

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
	RotationEditModeEuler RotationEditMode = 0
	// The rotation is edited using a [Quaternion.IJKX].
	RotationEditModeQuaternion RotationEditMode = 1
	// The rotation is edited using a [Basis.XYZ]. In this mode, the raw [Instance.Basis]'s axes can be freely modified, but the [Instance.Scale] property is not available.
	RotationEditModeBasis RotationEditMode = 2
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.