|
@@ -1,5 +1,8 @@
|
|
|
:github_url: hide
|
|
|
|
|
|
+.. meta::
|
|
|
+ :keywords: spatial
|
|
|
+
|
|
|
.. DO NOT EDIT THIS FILE!!!
|
|
|
.. Generated automatically from Godot engine sources.
|
|
|
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
|
|
@@ -14,20 +17,20 @@ Node3D
|
|
|
|
|
|
**Inherited By:** :ref:`AudioListener3D<class_AudioListener3D>`, :ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>`, :ref:`BoneAttachment3D<class_BoneAttachment3D>`, :ref:`Camera3D<class_Camera3D>`, :ref:`CollisionObject3D<class_CollisionObject3D>`, :ref:`CollisionPolygon3D<class_CollisionPolygon3D>`, :ref:`CollisionShape3D<class_CollisionShape3D>`, :ref:`GridMap<class_GridMap>`, :ref:`ImporterMeshInstance3D<class_ImporterMeshInstance3D>`, :ref:`Joint3D<class_Joint3D>`, :ref:`LightmapProbe<class_LightmapProbe>`, :ref:`Marker3D<class_Marker3D>`, :ref:`NavigationLink3D<class_NavigationLink3D>`, :ref:`NavigationObstacle3D<class_NavigationObstacle3D>`, :ref:`NavigationRegion3D<class_NavigationRegion3D>`, :ref:`OpenXRCompositionLayer<class_OpenXRCompositionLayer>`, :ref:`OpenXRHand<class_OpenXRHand>`, :ref:`Path3D<class_Path3D>`, :ref:`PathFollow3D<class_PathFollow3D>`, :ref:`RayCast3D<class_RayCast3D>`, :ref:`RemoteTransform3D<class_RemoteTransform3D>`, :ref:`ShapeCast3D<class_ShapeCast3D>`, :ref:`Skeleton3D<class_Skeleton3D>`, :ref:`SkeletonModifier3D<class_SkeletonModifier3D>`, :ref:`SpringArm3D<class_SpringArm3D>`, :ref:`SpringBoneCollision3D<class_SpringBoneCollision3D>`, :ref:`VehicleWheel3D<class_VehicleWheel3D>`, :ref:`VisualInstance3D<class_VisualInstance3D>`, :ref:`XRFaceModifier3D<class_XRFaceModifier3D>`, :ref:`XRNode3D<class_XRNode3D>`, :ref:`XROrigin3D<class_XROrigin3D>`
|
|
|
|
|
|
-Most basic 3D game object, parent of all 3D-related nodes.
|
|
|
+Base object in 3D space, inherited by all 3D nodes.
|
|
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
|
|
Description
|
|
|
-----------
|
|
|
|
|
|
-Most basic 3D game object, with a :ref:`Transform3D<class_Transform3D>` and visibility settings. All other 3D game objects inherit from **Node3D**. Use **Node3D** as a parent node to move, scale, rotate and show/hide children in a 3D project.
|
|
|
+The **Node3D** node is the base representation of a node in 3D space. All other 3D nodes inherit from this class.
|
|
|
|
|
|
-Affine operations (rotate, scale, translate) happen in parent's local coordinate system, unless the **Node3D** object is set as top-level. Affine operations in this coordinate system correspond to direct affine operations on the **Node3D**'s transform. The word local below refers to this coordinate system. The coordinate system that is attached to the **Node3D** object itself is referred to as object-local coordinate system.
|
|
|
+Affine operations (translation, rotation, scale) are calculated in the coordinate system relative to the parent, unless the **Node3D**'s :ref:`top_level<class_Node3D_property_top_level>` is ``true``. In this coordinate system, affine operations correspond to direct affine operations on the **Node3D**'s :ref:`transform<class_Node3D_property_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 have angle parameters must have angles specified as *radians*. To convert degrees to radians, use :ref:`@GlobalScope.deg_to_rad()<class_@GlobalScope_method_deg_to_rad>`.
|
|
|
+\ **Note:** Unless otherwise specified, all methods that need angle parameters must receive angles in *radians*. To convert degrees to radians, use :ref:`@GlobalScope.deg_to_rad()<class_@GlobalScope_method_deg_to_rad>`.
|
|
|
|
|
|
-\ **Note:** Be aware that "Spatial" nodes are now called "Node3D" starting with Godot 4. Any Godot 3.x references to "Spatial" nodes refer to "Node3D" in Godot 4.
|
|
|
+\ **Note:** In Godot 3 and older, **Node3D** was named *Spatial*.
|
|
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
|
@@ -181,7 +184,9 @@ Signals
|
|
|
|
|
|
**visibility_changed**\ (\ ) :ref:`🔗<class_Node3D_signal_visibility_changed>`
|
|
|
|
|
|
-Emitted when node visibility changes.
|
|
|
+Emitted when this node's visibility changes (see :ref:`visible<class_Node3D_property_visible>` and :ref:`is_visible_in_tree()<class_Node3D_method_is_visible_in_tree>`).
|
|
|
+
|
|
|
+This signal is emitted *after* the related :ref:`NOTIFICATION_VISIBILITY_CHANGED<class_Node3D_constant_NOTIFICATION_VISIBILITY_CHANGED>` notification.
|
|
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
|
@@ -204,7 +209,7 @@ enum **RotationEditMode**: :ref:`🔗<enum_Node3D_RotationEditMode>`
|
|
|
|
|
|
:ref:`RotationEditMode<enum_Node3D_RotationEditMode>` **ROTATION_EDIT_MODE_EULER** = ``0``
|
|
|
|
|
|
-The rotation is edited using :ref:`Vector3<class_Vector3>` Euler angles.
|
|
|
+The rotation is edited using a :ref:`Vector3<class_Vector3>` in `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`__.
|
|
|
|
|
|
.. _class_Node3D_constant_ROTATION_EDIT_MODE_QUATERNION:
|
|
|
|
|
@@ -220,7 +225,7 @@ The rotation is edited using a :ref:`Quaternion<class_Quaternion>`.
|
|
|
|
|
|
:ref:`RotationEditMode<enum_Node3D_RotationEditMode>` **ROTATION_EDIT_MODE_BASIS** = ``2``
|
|
|
|
|
|
-The rotation is edited using a :ref:`Basis<class_Basis>`. In this mode, :ref:`scale<class_Node3D_property_scale>` can't be edited separately.
|
|
|
+The rotation is edited using a :ref:`Basis<class_Basis>`. In this mode, the raw :ref:`basis<class_Node3D_property_basis>`'s axes can be freely modified, but the :ref:`scale<class_Node3D_property_scale>` property is not available.
|
|
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
|
@@ -237,9 +242,11 @@ Constants
|
|
|
|
|
|
**NOTIFICATION_TRANSFORM_CHANGED** = ``2000`` :ref:`🔗<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>`
|
|
|
|
|
|
-**Node3D** nodes receive this notification when their global transform changes. This means that either the current or a parent node changed its transform.
|
|
|
+Notification received when this node's :ref:`global_transform<class_Node3D_property_global_transform>` changes, if :ref:`is_transform_notification_enabled()<class_Node3D_method_is_transform_notification_enabled>` is ``true``. See also :ref:`set_notify_transform()<class_Node3D_method_set_notify_transform>`.
|
|
|
+
|
|
|
+\ **Note:** Most 3D nodes such as :ref:`VisualInstance3D<class_VisualInstance3D>` or :ref:`CollisionObject3D<class_CollisionObject3D>` automatically enable this to function correctly.
|
|
|
|
|
|
-In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>` to work, users first need to ask for it, with :ref:`set_notify_transform()<class_Node3D_method_set_notify_transform>`. The notification is also sent if the node is in the editor context and it has at least one valid gizmo.
|
|
|
+\ **Note:** In the editor, nodes will propagate this notification to their children if a gizmo is attached (see :ref:`add_gizmo()<class_Node3D_method_add_gizmo>`).
|
|
|
|
|
|
.. _class_Node3D_constant_NOTIFICATION_ENTER_WORLD:
|
|
|
|
|
@@ -247,7 +254,7 @@ In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICA
|
|
|
|
|
|
**NOTIFICATION_ENTER_WORLD** = ``41`` :ref:`🔗<class_Node3D_constant_NOTIFICATION_ENTER_WORLD>`
|
|
|
|
|
|
-**Node3D** nodes receive this notification when they are registered to new :ref:`World3D<class_World3D>` resource.
|
|
|
+Notification received when this node is registered to a new :ref:`World3D<class_World3D>` (see :ref:`get_world_3d()<class_Node3D_method_get_world_3d>`).
|
|
|
|
|
|
.. _class_Node3D_constant_NOTIFICATION_EXIT_WORLD:
|
|
|
|
|
@@ -255,7 +262,7 @@ In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICA
|
|
|
|
|
|
**NOTIFICATION_EXIT_WORLD** = ``42`` :ref:`🔗<class_Node3D_constant_NOTIFICATION_EXIT_WORLD>`
|
|
|
|
|
|
-**Node3D** nodes receive this notification when they are unregistered from current :ref:`World3D<class_World3D>` resource.
|
|
|
+Notification received when this node is unregistered from the current :ref:`World3D<class_World3D>` (see :ref:`get_world_3d()<class_Node3D_method_get_world_3d>`).
|
|
|
|
|
|
.. _class_Node3D_constant_NOTIFICATION_VISIBILITY_CHANGED:
|
|
|
|
|
@@ -263,7 +270,9 @@ In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICA
|
|
|
|
|
|
**NOTIFICATION_VISIBILITY_CHANGED** = ``43`` :ref:`🔗<class_Node3D_constant_NOTIFICATION_VISIBILITY_CHANGED>`
|
|
|
|
|
|
-**Node3D** nodes receive this notification when their visibility changes.
|
|
|
+Notification received when this node's visibility changes (see :ref:`visible<class_Node3D_property_visible>` and :ref:`is_visible_in_tree()<class_Node3D_method_is_visible_in_tree>`).
|
|
|
+
|
|
|
+This notification is received *before* the related :ref:`visibility_changed<class_Node3D_signal_visibility_changed>` signal.
|
|
|
|
|
|
.. _class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED:
|
|
|
|
|
@@ -271,9 +280,9 @@ In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICA
|
|
|
|
|
|
**NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = ``44`` :ref:`🔗<class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED>`
|
|
|
|
|
|
-**Node3D** nodes receive this notification when their local transform changes. This is not received when the transform of a parent node is changed.
|
|
|
+Notification received when this node's :ref:`transform<class_Node3D_property_transform>` changes, if :ref:`is_local_transform_notification_enabled()<class_Node3D_method_is_local_transform_notification_enabled>` is ``true``. This is not received when a parent **Node3D**'s :ref:`transform<class_Node3D_property_transform>` changes. See also :ref:`set_notify_local_transform()<class_Node3D_method_set_notify_local_transform>`.
|
|
|
|
|
|
-In order for :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED>` to work, users first need to ask for it, with :ref:`set_notify_local_transform()<class_Node3D_method_set_notify_local_transform>`.
|
|
|
+\ **Note:** Some 3D nodes such as :ref:`CSGShape3D<class_CSGShape3D>` or :ref:`CollisionShape3D<class_CollisionShape3D>` automatically enable this to function correctly.
|
|
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
|
@@ -295,7 +304,7 @@ Property Descriptions
|
|
|
- |void| **set_basis**\ (\ value\: :ref:`Basis<class_Basis>`\ )
|
|
|
- :ref:`Basis<class_Basis>` **get_basis**\ (\ )
|
|
|
|
|
|
-Basis of the :ref:`transform<class_Node3D_property_transform>` property. Represents the rotation, scale, and shear of this node.
|
|
|
+Basis of the :ref:`transform<class_Node3D_property_transform>` property. Represents the rotation, scale, and shear of this node in parent space (relative to the parent node).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -312,7 +321,9 @@ Basis of the :ref:`transform<class_Node3D_property_transform>` property. Represe
|
|
|
- |void| **set_global_basis**\ (\ value\: :ref:`Basis<class_Basis>`\ )
|
|
|
- :ref:`Basis<class_Basis>` **get_global_basis**\ (\ )
|
|
|
|
|
|
-Global basis of this node. This is equivalent to ``global_transform.basis``.
|
|
|
+Basis of the :ref:`global_transform<class_Node3D_property_global_transform>` 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 :ref:`Basis.IDENTITY<class_Basis_constant_IDENTITY>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -329,7 +340,9 @@ Global basis of this node. This is equivalent to ``global_transform.basis``.
|
|
|
- |void| **set_global_position**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_global_position**\ (\ )
|
|
|
|
|
|
-Global position of this node. This is equivalent to ``global_transform.origin``.
|
|
|
+Global position (translation) of this node in global space (relative to the world). This is equivalent to the :ref:`global_transform<class_Node3D_property_global_transform>`'s :ref:`Transform3D.origin<class_Transform3D_property_origin>`.
|
|
|
+
|
|
|
+\ **Note:** If the node is not inside the tree, getting this property fails and returns :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -346,9 +359,17 @@ Global position of this node. This is equivalent to ``global_transform.origin``.
|
|
|
- |void| **set_global_rotation**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_global_rotation**\ (\ )
|
|
|
|
|
|
-Rotation part of the global transformation in radians, specified in terms of YXZ-Euler angles in the format (X angle, Y angle, Z angle).
|
|
|
+Global rotation of this node as `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`__, in radians and in global space (relative to the world). This value is obtained from :ref:`global_basis<class_Node3D_property_global_basis>`'s rotation.
|
|
|
+
|
|
|
+- The :ref:`Vector3.x<class_Vector3_property_x>` is the angle around the global X axis (pitch);
|
|
|
+
|
|
|
+- The :ref:`Vector3.y<class_Vector3_property_y>` is the angle around the global Y axis (yaw);
|
|
|
+
|
|
|
+- The :ref:`Vector3.z<class_Vector3_property_z>` is the angle around the global Z axis (roll).
|
|
|
|
|
|
-\ **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 :ref:`Vector3<class_Vector3>` data structure not because the rotation is a vector, but only because :ref:`Vector3<class_Vector3>` exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.
|
|
|
+\ **Note:** Unlike :ref:`rotation<class_Node3D_property_rotation>`, this property always follows the YXZ convention (:ref:`@GlobalScope.EULER_ORDER_YXZ<class_@GlobalScope_constant_EULER_ORDER_YXZ>`).
|
|
|
+
|
|
|
+\ **Note:** If the node is not inside the tree, getting this property fails and returns :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -365,7 +386,9 @@ Rotation part of the global transformation in radians, specified in terms of YXZ
|
|
|
- |void| **set_global_rotation_degrees**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_global_rotation_degrees**\ (\ )
|
|
|
|
|
|
-Helper property to access :ref:`global_rotation<class_Node3D_property_global_rotation>` in degrees instead of radians.
|
|
|
+The :ref:`global_rotation<class_Node3D_property_global_rotation>` of this node, in degrees instead of radians.
|
|
|
+
|
|
|
+\ **Note:** If the node is not inside the tree, getting this property fails and returns :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -382,7 +405,9 @@ Helper property to access :ref:`global_rotation<class_Node3D_property_global_rot
|
|
|
- |void| **set_global_transform**\ (\ value\: :ref:`Transform3D<class_Transform3D>`\ )
|
|
|
- :ref:`Transform3D<class_Transform3D>` **get_global_transform**\ (\ )
|
|
|
|
|
|
-World3D space (global) :ref:`Transform3D<class_Transform3D>` of this node.
|
|
|
+The transformation of this node, in global space (relative to the world). Contains and represents this node's :ref:`global_position<class_Node3D_property_global_position>`, :ref:`global_rotation<class_Node3D_property_global_rotation>`, and global scale.
|
|
|
+
|
|
|
+\ **Note:** If the node is not inside the tree, getting this property fails and returns :ref:`Transform3D.IDENTITY<class_Transform3D_constant_IDENTITY>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -399,7 +424,7 @@ World3D space (global) :ref:`Transform3D<class_Transform3D>` of this node.
|
|
|
- |void| **set_position**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_position**\ (\ )
|
|
|
|
|
|
-Local position or translation of this node relative to the parent. This is equivalent to ``transform.origin``.
|
|
|
+Position (translation) of this node in parent space (relative to the parent node). This is equivalent to the :ref:`transform<class_Node3D_property_transform>`'s :ref:`Transform3D.origin<class_Transform3D_property_origin>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -416,7 +441,9 @@ Local position or translation of this node relative to the parent. This is equiv
|
|
|
- |void| **set_quaternion**\ (\ value\: :ref:`Quaternion<class_Quaternion>`\ )
|
|
|
- :ref:`Quaternion<class_Quaternion>` **get_quaternion**\ (\ )
|
|
|
|
|
|
-Access to the node rotation as a :ref:`Quaternion<class_Quaternion>`. This property is ideal for tweening complex rotations.
|
|
|
+Rotation of this node represented as a :ref:`Quaternion<class_Quaternion>` in parent space (relative to the parent node). This value is obtained from :ref:`basis<class_Node3D_property_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 :ref:`Quaternion.slerp()<class_Quaternion_method_slerp>`).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -433,11 +460,17 @@ Access to the node rotation as a :ref:`Quaternion<class_Quaternion>`. This prope
|
|
|
- |void| **set_rotation**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_rotation**\ (\ )
|
|
|
|
|
|
-Rotation part of the local transformation in radians, specified in terms of Euler angles. The angles construct a rotation in the order specified by the :ref:`rotation_order<class_Node3D_property_rotation_order>` property.
|
|
|
+Rotation of this node as `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`__, in radians and in parent space (relative to the parent node). This value is obtained from :ref:`basis<class_Node3D_property_basis>`'s rotation.
|
|
|
|
|
|
-\ **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 :ref:`Vector3<class_Vector3>` data structure not because the rotation is a vector, but only because :ref:`Vector3<class_Vector3>` exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.
|
|
|
+- The :ref:`Vector3.x<class_Vector3_property_x>` is the angle around the local X axis (pitch);
|
|
|
|
|
|
-\ **Note:** This property is edited in the inspector in degrees. If you want to use degrees in a script, use :ref:`rotation_degrees<class_Node3D_property_rotation_degrees>`.
|
|
|
+- The :ref:`Vector3.y<class_Vector3_property_y>` is the angle around the local Y axis (yaw);
|
|
|
+
|
|
|
+- The :ref:`Vector3.z<class_Vector3_property_z>` is the angle around the local Z axis (roll).
|
|
|
+
|
|
|
+The order of each consecutive rotation can be changed with :ref:`rotation_order<class_Node3D_property_rotation_order>` (see :ref:`EulerOrder<enum_@GlobalScope_EulerOrder>` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ<class_@GlobalScope_constant_EULER_ORDER_YXZ>`).
|
|
|
+
|
|
|
+\ **Note:** This property is edited in degrees in the inspector. If you want to use degrees in a script, use :ref:`rotation_degrees<class_Node3D_property_rotation_degrees>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -454,7 +487,9 @@ Rotation part of the local transformation in radians, specified in terms of Eule
|
|
|
- |void| **set_rotation_degrees**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_rotation_degrees**\ (\ )
|
|
|
|
|
|
-Helper property to access :ref:`rotation<class_Node3D_property_rotation>` in degrees instead of radians.
|
|
|
+The :ref:`rotation<class_Node3D_property_rotation>` of this node, in degrees instead of radians.
|
|
|
+
|
|
|
+\ **Note:** This is **not** the property available in the Inspector dock.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -471,7 +506,7 @@ Helper property to access :ref:`rotation<class_Node3D_property_rotation>` in deg
|
|
|
- |void| **set_rotation_edit_mode**\ (\ value\: :ref:`RotationEditMode<enum_Node3D_RotationEditMode>`\ )
|
|
|
- :ref:`RotationEditMode<enum_Node3D_RotationEditMode>` **get_rotation_edit_mode**\ (\ )
|
|
|
|
|
|
-Specify how rotation (and scale) will be presented in the editor.
|
|
|
+How this node's rotation and scale are displayed in the Inspector dock.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -488,7 +523,7 @@ Specify how rotation (and scale) will be presented in the editor.
|
|
|
- |void| **set_rotation_order**\ (\ value\: :ref:`EulerOrder<enum_@GlobalScope_EulerOrder>`\ )
|
|
|
- :ref:`EulerOrder<enum_@GlobalScope_EulerOrder>` **get_rotation_order**\ (\ )
|
|
|
|
|
|
-Specify the axis rotation order of the :ref:`rotation<class_Node3D_property_rotation>` property. The final orientation is constructed by rotating the Euler angles in the order specified by this property.
|
|
|
+The axis rotation order of the :ref:`rotation<class_Node3D_property_rotation>` property. The final orientation is calculated by rotating around the local X, Y, and Z axis in this order.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -505,11 +540,11 @@ Specify the axis rotation order of the :ref:`rotation<class_Node3D_property_rota
|
|
|
- |void| **set_scale**\ (\ value\: :ref:`Vector3<class_Vector3>`\ )
|
|
|
- :ref:`Vector3<class_Vector3>` **get_scale**\ (\ )
|
|
|
|
|
|
-Scale part of the local transformation.
|
|
|
+Scale of this node in local space (relative to this node). This value is obtained from :ref:`basis<class_Node3D_property_basis>`'s scale.
|
|
|
|
|
|
-\ **Note:** Mixed negative scales in 3D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, the scale values will either be all positive or all negative.
|
|
|
+\ **Note:** The behavior of some 3D node types is not affected by this property. These include :ref:`Light3D<class_Light3D>`, :ref:`Camera3D<class_Camera3D>`, :ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>`, and more.
|
|
|
|
|
|
-\ **Note:** Not all nodes are visually scaled by the :ref:`scale<class_Node3D_property_scale>` property. For example, :ref:`Light3D<class_Light3D>`\ s are not visually affected by :ref:`scale<class_Node3D_property_scale>`.
|
|
|
+\ **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 :ref:`basis<class_Node3D_property_basis>`. This may cause the intended scale to be lost when reloaded from disk, and potentially other unstable behavior.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -526,7 +561,7 @@ Scale part of the local transformation.
|
|
|
- |void| **set_as_top_level**\ (\ value\: :ref:`bool<class_bool>`\ )
|
|
|
- :ref:`bool<class_bool>` **is_set_as_top_level**\ (\ )
|
|
|
|
|
|
-If ``true``, the node will not inherit its transformations from its parent. Node transformations are only in global space.
|
|
|
+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 :ref:`global_transform<class_Node3D_property_global_transform>` and :ref:`transform<class_Node3D_property_transform>` will be identical.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -543,7 +578,7 @@ If ``true``, the node will not inherit its transformations from its parent. Node
|
|
|
- |void| **set_transform**\ (\ value\: :ref:`Transform3D<class_Transform3D>`\ )
|
|
|
- :ref:`Transform3D<class_Transform3D>` **get_transform**\ (\ )
|
|
|
|
|
|
-Local space :ref:`Transform3D<class_Transform3D>` of this node, with respect to the parent node.
|
|
|
+The local transformation of this node, in parent space (relative to the parent node). Contains and represents this node's :ref:`position<class_Node3D_property_position>`, :ref:`rotation<class_Node3D_property_rotation>`, and :ref:`scale<class_Node3D_property_scale>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -560,7 +595,9 @@ Local space :ref:`Transform3D<class_Transform3D>` of this node, with respect to
|
|
|
- |void| **set_visibility_parent**\ (\ value\: :ref:`NodePath<class_NodePath>`\ )
|
|
|
- :ref:`NodePath<class_NodePath>` **get_visibility_parent**\ (\ )
|
|
|
|
|
|
-Defines the visibility range parent for this node and its subtree. 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 :ref:`GeometryInstance3D.visibility_range_begin<class_GeometryInstance3D_property_visibility_range_begin>`. Nodes hidden via the :ref:`visible<class_Node3D_property_visible>` property are essentially removed from the visibility dependency tree, so dependent instances will not take the hidden node or its ancestors into account.
|
|
|
+Path to the visibility range parent for this node and its descendants. The visibility parent must be a :ref:`GeometryInstance3D<class_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 :ref:`GeometryInstance3D.visibility_range_begin<class_GeometryInstance3D_property_visibility_range_begin>`. Nodes hidden via the :ref:`visible<class_Node3D_property_visible>` property are essentially removed from the visibility dependency tree, so dependent instances will not take the hidden node or its descendants into account.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -577,7 +614,7 @@ Defines the visibility range parent for this node and its subtree. The visibilit
|
|
|
- |void| **set_visible**\ (\ value\: :ref:`bool<class_bool>`\ )
|
|
|
- :ref:`bool<class_bool>` **is_visible**\ (\ )
|
|
|
|
|
|
-If ``true``, this node is drawn. The node is only visible if all of its ancestors are visible as well (in other words, :ref:`is_visible_in_tree()<class_Node3D_method_is_visible_in_tree>` must return ``true``).
|
|
|
+If ``true``, this node can be visible. The node is only rendered when all of its ancestors are visible, as well. That means :ref:`is_visible_in_tree()<class_Node3D_method_is_visible_in_tree>` must return ``true``.
|
|
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
|
@@ -594,9 +631,9 @@ Method Descriptions
|
|
|
|
|
|
|void| **add_gizmo**\ (\ gizmo\: :ref:`Node3DGizmo<class_Node3DGizmo>`\ ) :ref:`🔗<class_Node3D_method_add_gizmo>`
|
|
|
|
|
|
-Attach an editor gizmo to this **Node3D**.
|
|
|
+Attaches the given ``gizmo`` to this node. Only works in the editor.
|
|
|
|
|
|
-\ **Note:** The gizmo object would typically be an instance of :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`, but the argument type is kept generic to avoid creating a dependency on editor classes in **Node3D**.
|
|
|
+\ **Note:** ``gizmo`` should be an :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`. The argument type is :ref:`Node3DGizmo<class_Node3DGizmo>` to avoid depending on editor classes in **Node3D**.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -608,7 +645,7 @@ Attach an editor gizmo to this **Node3D**.
|
|
|
|
|
|
|void| **clear_gizmos**\ (\ ) :ref:`🔗<class_Node3D_method_clear_gizmos>`
|
|
|
|
|
|
-Clear all gizmos attached to this **Node3D**.
|
|
|
+Clears all :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>` objects attached to this node. Only works in the editor.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -620,7 +657,7 @@ Clear all gizmos attached to this **Node3D**.
|
|
|
|
|
|
|void| **clear_subgizmo_selection**\ (\ ) :ref:`🔗<class_Node3D_method_clear_subgizmo_selection>`
|
|
|
|
|
|
-Clears subgizmo selection for this node in the editor. Useful when subgizmo IDs become invalid after a property change.
|
|
|
+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.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -632,7 +669,9 @@ Clears subgizmo selection for this node in the editor. Useful when subgizmo IDs
|
|
|
|
|
|
|void| **force_update_transform**\ (\ ) :ref:`🔗<class_Node3D_method_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.
|
|
|
+Forces the node's :ref:`global_transform<class_Node3D_property_global_transform>` to update, by sending :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>`. 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).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -644,7 +683,7 @@ Forces the transform to update. Transform changes in physics are not instant for
|
|
|
|
|
|
:ref:`Array<class_Array>`\[:ref:`Node3DGizmo<class_Node3DGizmo>`\] **get_gizmos**\ (\ ) |const| :ref:`🔗<class_Node3D_method_get_gizmos>`
|
|
|
|
|
|
-Returns all the gizmos attached to this **Node3D**.
|
|
|
+Returns all the :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>` objects attached to this node. Only works in the editor.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -672,9 +711,9 @@ This is particularly important for frame-based operations that take place in :re
|
|
|
|
|
|
:ref:`Node3D<class_Node3D>` **get_parent_node_3d**\ (\ ) |const| :ref:`🔗<class_Node3D_method_get_parent_node_3d>`
|
|
|
|
|
|
-Returns the parent **Node3D**, or ``null`` if no parent exists, the parent is not of type **Node3D**, or :ref:`top_level<class_Node3D_property_top_level>` is ``true``.
|
|
|
+Returns the parent **Node3D** that directly affects this node's :ref:`global_transform<class_Node3D_property_global_transform>`. Returns ``null`` if no parent exists, the parent is not a **Node3D**, or :ref:`top_level<class_Node3D_property_top_level>` is ``true``.
|
|
|
|
|
|
-\ **Note:** Calling this method is not equivalent to ``get_parent() as Node3D``, which does not take :ref:`top_level<class_Node3D_property_top_level>` into account.
|
|
|
+\ **Note:** This method is not always equivalent to :ref:`Node.get_parent()<class_Node_method_get_parent>`, which does not take :ref:`top_level<class_Node3D_property_top_level>` into account.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -686,7 +725,9 @@ Returns the parent **Node3D**, or ``null`` if no parent exists, the parent is no
|
|
|
|
|
|
:ref:`World3D<class_World3D>` **get_world_3d**\ (\ ) |const| :ref:`🔗<class_Node3D_method_get_world_3d>`
|
|
|
|
|
|
-Returns the current :ref:`World3D<class_World3D>` resource this **Node3D** node is registered to.
|
|
|
+Returns the :ref:`World3D<class_World3D>` this node is registered to.
|
|
|
+
|
|
|
+Usually, this is the same as the world used by this node's viewport (see :ref:`Node.get_viewport()<class_Node_method_get_viewport>` and :ref:`Viewport.find_world_3d()<class_Viewport_method_find_world_3d>`).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -698,7 +739,7 @@ Returns the current :ref:`World3D<class_World3D>` resource this **Node3D** node
|
|
|
|
|
|
|void| **global_rotate**\ (\ axis\: :ref:`Vector3<class_Vector3>`, angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_global_rotate>`
|
|
|
|
|
|
-Rotates the global (world) transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians. The rotation axis is in global coordinate system.
|
|
|
+Rotates this node's :ref:`global_basis<class_Node3D_property_global_basis>` around the global ``axis`` by the given ``angle``, in radians. This operation is calculated in global space (relative to the world) and preserves the :ref:`global_position<class_Node3D_property_global_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -710,7 +751,9 @@ Rotates the global (world) transformation around axis, a unit :ref:`Vector3<clas
|
|
|
|
|
|
|void| **global_scale**\ (\ scale\: :ref:`Vector3<class_Vector3>`\ ) :ref:`🔗<class_Node3D_method_global_scale>`
|
|
|
|
|
|
-Scales the global (world) transformation by the given :ref:`Vector3<class_Vector3>` scale factors.
|
|
|
+Scales this node's :ref:`global_basis<class_Node3D_property_global_basis>` by the given ``scale`` factor. This operation is calculated in global space (relative to the world) and preserves the :ref:`global_position<class_Node3D_property_global_position>`.
|
|
|
+
|
|
|
+\ **Note:** This method is not to be confused with the :ref:`scale<class_Node3D_property_scale>` property.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -722,7 +765,7 @@ Scales the global (world) transformation by the given :ref:`Vector3<class_Vector
|
|
|
|
|
|
|void| **global_translate**\ (\ offset\: :ref:`Vector3<class_Vector3>`\ ) :ref:`🔗<class_Node3D_method_global_translate>`
|
|
|
|
|
|
-Moves the global (world) transformation by :ref:`Vector3<class_Vector3>` offset. The offset is in global coordinate system.
|
|
|
+Adds the given translation ``offset`` to the node's :ref:`global_position<class_Node3D_property_global_position>` in global space (relative to the world).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -734,7 +777,7 @@ Moves the global (world) transformation by :ref:`Vector3<class_Vector3>` offset.
|
|
|
|
|
|
|void| **hide**\ (\ ) :ref:`🔗<class_Node3D_method_hide>`
|
|
|
|
|
|
-Disables rendering of this node. Changes :ref:`visible<class_Node3D_property_visible>` to ``false``.
|
|
|
+Prevents this node from being rendered. Equivalent to setting :ref:`visible<class_Node3D_property_visible>` to ``false``. This is the opposite of :ref:`show()<class_Node3D_method_show>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -746,7 +789,7 @@ Disables rendering of this node. Changes :ref:`visible<class_Node3D_property_vis
|
|
|
|
|
|
:ref:`bool<class_bool>` **is_local_transform_notification_enabled**\ (\ ) |const| :ref:`🔗<class_Node3D_method_is_local_transform_notification_enabled>`
|
|
|
|
|
|
-Returns whether node notifies about its local transformation changes. **Node3D** will not propagate this by default.
|
|
|
+Returns ``true`` if the node receives :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED>` whenever :ref:`transform<class_Node3D_property_transform>` changes. This is enabled with :ref:`set_notify_local_transform()<class_Node3D_method_set_notify_local_transform>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -758,7 +801,9 @@ Returns whether node notifies about its local transformation changes. **Node3D**
|
|
|
|
|
|
:ref:`bool<class_bool>` **is_scale_disabled**\ (\ ) |const| :ref:`🔗<class_Node3D_method_is_scale_disabled>`
|
|
|
|
|
|
-Returns whether this node uses a scale of ``(1, 1, 1)`` or its local transformation scale.
|
|
|
+Returns ``true`` if this node's :ref:`global_transform<class_Node3D_property_global_transform>` is automatically orthonormalized. This results in this node not appearing distorted, as if its global scale were set to :ref:`Vector3.ONE<class_Vector3_constant_ONE>` (or its negative counterpart). See also :ref:`set_disable_scale()<class_Node3D_method_set_disable_scale>` and :ref:`orthonormalize()<class_Node3D_method_orthonormalize>`.
|
|
|
+
|
|
|
+\ **Note:** :ref:`transform<class_Node3D_property_transform>` is not affected by this setting.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -770,7 +815,7 @@ Returns whether this node uses a scale of ``(1, 1, 1)`` or its local transformat
|
|
|
|
|
|
:ref:`bool<class_bool>` **is_transform_notification_enabled**\ (\ ) |const| :ref:`🔗<class_Node3D_method_is_transform_notification_enabled>`
|
|
|
|
|
|
-Returns whether the node notifies about its global and local transformation changes. **Node3D** will not propagate this by default.
|
|
|
+Returns ``true`` if the node receives :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>` whenever :ref:`global_transform<class_Node3D_property_global_transform>` changes. This is enabled with :ref:`set_notify_transform()<class_Node3D_method_set_notify_transform>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -782,11 +827,9 @@ Returns whether the node notifies about its global and local transformation chan
|
|
|
|
|
|
:ref:`bool<class_bool>` **is_visible_in_tree**\ (\ ) |const| :ref:`🔗<class_Node3D_method_is_visible_in_tree>`
|
|
|
|
|
|
-Returns ``true`` if the node is present in the :ref:`SceneTree<class_SceneTree>`, its :ref:`visible<class_Node3D_property_visible>` property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree.
|
|
|
+Returns ``true`` if this node is inside the scene tree and the :ref:`visible<class_Node3D_property_visible>` property is ``true`` for this node and all of its **Node3D** ancestors *in sequence*. An ancestor of any other type (such as :ref:`Node<class_Node>` or :ref:`Node2D<class_Node2D>`) breaks the sequence. See also :ref:`Node.get_parent()<class_Node_method_get_parent>`.
|
|
|
|
|
|
-Visibility is checked only in parent nodes that inherit from **Node3D**. If the parent is of any other type (such as :ref:`Node<class_Node>`, :ref:`AnimationPlayer<class_AnimationPlayer>`, or :ref:`Node2D<class_Node2D>`), it is assumed to be visible.
|
|
|
-
|
|
|
-\ **Note:** This method does not take :ref:`VisualInstance3D.layers<class_VisualInstance3D_property_layers>` into account, so even if this method returns ``true``, the node might end up not being rendered.
|
|
|
+\ **Note:** This method cannot take :ref:`VisualInstance3D.layers<class_VisualInstance3D_property_layers>` into account, so even if this method returns ``true``, the node may not be rendered.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -798,18 +841,16 @@ Visibility is checked only in parent nodes that inherit from **Node3D**. If the
|
|
|
|
|
|
|void| **look_at**\ (\ target\: :ref:`Vector3<class_Vector3>`, up\: :ref:`Vector3<class_Vector3>` = Vector3(0, 1, 0), use_model_front\: :ref:`bool<class_bool>` = false\ ) :ref:`🔗<class_Node3D_method_look_at>`
|
|
|
|
|
|
-Rotates the node so that the local forward axis (-Z, :ref:`Vector3.FORWARD<class_Vector3_constant_FORWARD>`) points toward the ``target`` position.
|
|
|
+Rotates the node so that the local forward axis (-Z, :ref:`Vector3.FORWARD<class_Vector3_constant_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 zero.
|
|
|
-
|
|
|
-The ``target`` and the ``up`` cannot be :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`, and shouldn't be colinear to avoid unintended rotation around local Z axis.
|
|
|
-
|
|
|
-Operations take place in global space, which means that the node must be in the scene tree.
|
|
|
+The ``target`` position cannot be the same as the node's position, the ``up`` vector cannot be :ref:`Vector3.ZERO<class_Vector3_constant_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 :ref:`look_at_from_position()<class_Node3D_method_look_at_from_position>` instead.
|
|
|
+
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
|
----
|
|
@@ -820,7 +861,7 @@ If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forw
|
|
|
|
|
|
|void| **look_at_from_position**\ (\ position\: :ref:`Vector3<class_Vector3>`, target\: :ref:`Vector3<class_Vector3>`, up\: :ref:`Vector3<class_Vector3>` = Vector3(0, 1, 0), use_model_front\: :ref:`bool<class_bool>` = false\ ) :ref:`🔗<class_Node3D_method_look_at_from_position>`
|
|
|
|
|
|
-Moves the node to the specified ``position``, and then rotates the node to point toward the ``target`` as per :ref:`look_at()<class_Node3D_method_look_at>`. Operations take place in global space.
|
|
|
+Moves the node to the specified ``position``, then rotates the node to point toward the ``target`` position, similar to :ref:`look_at()<class_Node3D_method_look_at>`. This operation is calculated in global space (relative to the world).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -832,7 +873,7 @@ Moves the node to the specified ``position``, and then rotates the node to point
|
|
|
|
|
|
|void| **orthonormalize**\ (\ ) :ref:`🔗<class_Node3D_method_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 :ref:`Transform3D<class_Transform3D>`.
|
|
|
+Orthonormalizes this node's :ref:`basis<class_Node3D_property_basis>`. This method sets this node's :ref:`scale<class_Node3D_property_scale>` to :ref:`Vector3.ONE<class_Vector3_constant_ONE>` (or its negative counterpart), but preserves the :ref:`position<class_Node3D_property_position>` and :ref:`rotation<class_Node3D_property_rotation>`. See also :ref:`Transform3D.orthonormalized()<class_Transform3D_method_orthonormalized>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -844,7 +885,7 @@ Resets this node's transformations (like scale, skew and taper) preserving its r
|
|
|
|
|
|
|void| **rotate**\ (\ axis\: :ref:`Vector3<class_Vector3>`, angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_rotate>`
|
|
|
|
|
|
-Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians.
|
|
|
+Rotates this node's :ref:`basis<class_Node3D_property_basis>` around the ``axis`` by the given ``angle``, in radians. This operation is calculated in parent space (relative to the parent) and preserves the :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -856,7 +897,7 @@ Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3
|
|
|
|
|
|
|void| **rotate_object_local**\ (\ axis\: :ref:`Vector3<class_Vector3>`, angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_rotate_object_local>`
|
|
|
|
|
|
-Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3>`, by specified angle in radians. The rotation axis is in object-local coordinate system.
|
|
|
+Rotates this node's :ref:`basis<class_Node3D_property_basis>` around the ``axis`` by the given ``angle``, in radians. This operation is calculated in local space (relative to this node) and preserves the :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -868,7 +909,7 @@ Rotates the local transformation around axis, a unit :ref:`Vector3<class_Vector3
|
|
|
|
|
|
|void| **rotate_x**\ (\ angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_rotate_x>`
|
|
|
|
|
|
-Rotates the local transformation around the X axis by angle in radians.
|
|
|
+Rotates this node's :ref:`basis<class_Node3D_property_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 :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -880,7 +921,7 @@ Rotates the local transformation around the X axis by angle in radians.
|
|
|
|
|
|
|void| **rotate_y**\ (\ angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_rotate_y>`
|
|
|
|
|
|
-Rotates the local transformation around the Y axis by angle in radians.
|
|
|
+Rotates this node's :ref:`basis<class_Node3D_property_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 :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -892,7 +933,7 @@ Rotates the local transformation around the Y axis by angle in radians.
|
|
|
|
|
|
|void| **rotate_z**\ (\ angle\: :ref:`float<class_float>`\ ) :ref:`🔗<class_Node3D_method_rotate_z>`
|
|
|
|
|
|
-Rotates the local transformation around the Z axis by angle in radians.
|
|
|
+Rotates this node's :ref:`basis<class_Node3D_property_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 :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -904,7 +945,7 @@ Rotates the local transformation around the Z axis by angle in radians.
|
|
|
|
|
|
|void| **scale_object_local**\ (\ scale\: :ref:`Vector3<class_Vector3>`\ ) :ref:`🔗<class_Node3D_method_scale_object_local>`
|
|
|
|
|
|
-Scales the local transformation by given 3D scale factors in object-local coordinate system.
|
|
|
+Scales this node's :ref:`basis<class_Node3D_property_basis>` by the given ``scale`` factor. This operation is calculated in local space (relative to this node) and preserves the :ref:`position<class_Node3D_property_position>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -916,7 +957,9 @@ Scales the local transformation by given 3D scale factors in object-local coordi
|
|
|
|
|
|
|void| **set_disable_scale**\ (\ disable\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_Node3D_method_set_disable_scale>`
|
|
|
|
|
|
-Sets whether the node uses a scale of ``(1, 1, 1)`` or its local transformation scale. Changes to the local transformation scale are preserved.
|
|
|
+If ``true``, this node's :ref:`global_transform<class_Node3D_property_global_transform>` is automatically orthonormalized. This results in this node not appearing distorted, as if its global scale were set to :ref:`Vector3.ONE<class_Vector3_constant_ONE>` (or its negative counterpart). See also :ref:`is_scale_disabled()<class_Node3D_method_is_scale_disabled>` and :ref:`orthonormalize()<class_Node3D_method_orthonormalize>`.
|
|
|
+
|
|
|
+\ **Note:** :ref:`transform<class_Node3D_property_transform>` is not affected by this setting.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -928,7 +971,7 @@ Sets whether the node uses a scale of ``(1, 1, 1)`` or its local transformation
|
|
|
|
|
|
|void| **set_identity**\ (\ ) :ref:`🔗<class_Node3D_method_set_identity>`
|
|
|
|
|
|
-Reset all transformations for this node (sets its :ref:`Transform3D<class_Transform3D>` to the identity matrix).
|
|
|
+Sets this node's :ref:`transform<class_Node3D_property_transform>` to :ref:`Transform3D.IDENTITY<class_Transform3D_constant_IDENTITY>`, which resets all transformations in parent space (:ref:`position<class_Node3D_property_position>`, :ref:`rotation<class_Node3D_property_rotation>`, and :ref:`scale<class_Node3D_property_scale>`).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -940,7 +983,9 @@ Reset all transformations for this node (sets its :ref:`Transform3D<class_Transf
|
|
|
|
|
|
|void| **set_ignore_transform_notification**\ (\ enabled\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_Node3D_method_set_ignore_transform_notification>`
|
|
|
|
|
|
-Sets whether the node ignores notification that its transformation (global or local) changed.
|
|
|
+If ``true``, the node will not receive :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>` or :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED>`.
|
|
|
+
|
|
|
+It may useful to call this method when handling these notifications to prevent infinite recursion.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -952,7 +997,9 @@ Sets whether the node ignores notification that its transformation (global or lo
|
|
|
|
|
|
|void| **set_notify_local_transform**\ (\ enable\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_Node3D_method_set_notify_local_transform>`
|
|
|
|
|
|
-Sets whether the node notifies about its local transformation changes. **Node3D** will not propagate this by default.
|
|
|
+If ``true``, the node will receive :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED>` whenever :ref:`transform<class_Node3D_property_transform>` changes.
|
|
|
+
|
|
|
+\ **Note:** Some 3D nodes such as :ref:`CSGShape3D<class_CSGShape3D>` or :ref:`CollisionShape3D<class_CollisionShape3D>` automatically enable this to function correctly.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -964,7 +1011,11 @@ Sets whether the node notifies about its local transformation changes. **Node3D*
|
|
|
|
|
|
|void| **set_notify_transform**\ (\ enable\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_Node3D_method_set_notify_transform>`
|
|
|
|
|
|
-Sets whether the node notifies about its global and local transformation changes. **Node3D** will not propagate this by default, unless it is in the editor context and it has a valid gizmo.
|
|
|
+If ``true``, the node will receive :ref:`NOTIFICATION_TRANSFORM_CHANGED<class_Node3D_constant_NOTIFICATION_TRANSFORM_CHANGED>` whenever :ref:`global_transform<class_Node3D_property_global_transform>` changes.
|
|
|
+
|
|
|
+\ **Note:** Most 3D nodes such as :ref:`VisualInstance3D<class_VisualInstance3D>` or :ref:`CollisionObject3D<class_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 :ref:`add_gizmo()<class_Node3D_method_add_gizmo>`).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -976,7 +1027,7 @@ Sets whether the node notifies about its global and local transformation changes
|
|
|
|
|
|
|void| **set_subgizmo_selection**\ (\ gizmo\: :ref:`Node3DGizmo<class_Node3DGizmo>`, id\: :ref:`int<class_int>`, transform\: :ref:`Transform3D<class_Transform3D>`\ ) :ref:`🔗<class_Node3D_method_set_subgizmo_selection>`
|
|
|
|
|
|
-Set subgizmo selection for this node in the editor.
|
|
|
+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 :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`, but the argument type is kept generic to avoid creating a dependency on editor classes in **Node3D**.
|
|
|
|
|
@@ -990,7 +1041,7 @@ Set subgizmo selection for this node in the editor.
|
|
|
|
|
|
|void| **show**\ (\ ) :ref:`🔗<class_Node3D_method_show>`
|
|
|
|
|
|
-Enables rendering of this node. Changes :ref:`visible<class_Node3D_property_visible>` to ``true``.
|
|
|
+Allows this node to be rendered. Equivalent to setting :ref:`visible<class_Node3D_property_visible>` to ``true``. This is the opposite of :ref:`hide()<class_Node3D_method_hide>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -1002,7 +1053,7 @@ Enables rendering of this node. Changes :ref:`visible<class_Node3D_property_visi
|
|
|
|
|
|
:ref:`Vector3<class_Vector3>` **to_global**\ (\ local_point\: :ref:`Vector3<class_Vector3>`\ ) |const| :ref:`🔗<class_Node3D_method_to_global>`
|
|
|
|
|
|
-Transforms ``local_point`` from this node's local space to world space.
|
|
|
+Returns the ``local_point`` converted from this node's local space to global space. This is the opposite of :ref:`to_local()<class_Node3D_method_to_local>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -1014,7 +1065,7 @@ Transforms ``local_point`` from this node's local space to world space.
|
|
|
|
|
|
:ref:`Vector3<class_Vector3>` **to_local**\ (\ global_point\: :ref:`Vector3<class_Vector3>`\ ) |const| :ref:`🔗<class_Node3D_method_to_local>`
|
|
|
|
|
|
-Transforms ``global_point`` from world space to this node's local space.
|
|
|
+Returns the ``global_point`` converted from global space to this node's local space. This is the opposite of :ref:`to_global()<class_Node3D_method_to_global>`.
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -1026,9 +1077,11 @@ Transforms ``global_point`` from world space to this node's local space.
|
|
|
|
|
|
|void| **translate**\ (\ offset\: :ref:`Vector3<class_Vector3>`\ ) :ref:`🔗<class_Node3D_method_translate>`
|
|
|
|
|
|
-Changes the node's position by the given offset :ref:`Vector3<class_Vector3>`.
|
|
|
+Adds the given translation ``offset`` to the node's position, in local space (relative to this node).
|
|
|
+
|
|
|
+\ **Note:** Prefer using :ref:`translate_object_local()<class_Node3D_method_translate_object_local>`, instead, as this method may be changed in a future release.
|
|
|
|
|
|
-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.
|
|
|
+\ **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 :ref:`position<class_Node3D_property_position>` (``node_3d.position += offset``).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -1040,7 +1093,7 @@ Note that the translation ``offset`` is affected by the node's scale, so if scal
|
|
|
|
|
|
|void| **translate_object_local**\ (\ offset\: :ref:`Vector3<class_Vector3>`\ ) :ref:`🔗<class_Node3D_method_translate_object_local>`
|
|
|
|
|
|
-Changes the node's position by the given offset :ref:`Vector3<class_Vector3>` in local space.
|
|
|
+Adds the given translation ``offset`` to the node's position, in local space (relative to this node).
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
|
@@ -1052,7 +1105,7 @@ Changes the node's position by the given offset :ref:`Vector3<class_Vector3>` in
|
|
|
|
|
|
|void| **update_gizmos**\ (\ ) :ref:`🔗<class_Node3D_method_update_gizmos>`
|
|
|
|
|
|
-Updates all the **Node3D** gizmos attached to this node.
|
|
|
+Updates all the :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>` objects attached to this node. Only works in the editor.
|
|
|
|
|
|
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
|
|
|
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
|