From 763701a2cb6b080941f02c15d270fdf142736b56 Mon Sep 17 00:00:00 2001 From: Micky Date: Sat, 20 Jan 2024 10:25:15 +0100 Subject: [PATCH] Overhaul Node3D documentation --- doc/classes/Node3D.xml | 179 +++++++++++++++++++++++------------------ 1 file changed, 99 insertions(+), 80 deletions(-) diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml index ae13af4b8268..0003625e0f71 100644 --- a/doc/classes/Node3D.xml +++ b/doc/classes/Node3D.xml @@ -1,13 +1,13 @@ - Most basic 3D game object, parent of all 3D-related nodes. + Base object in 3D space, inherited by all 3D nodes. - Most basic 3D game object, with a [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. - 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. - [b]Note:[/b] Unless otherwise specified, all methods that have angle parameters must have angles specified as [i]radians[/i]. To convert degrees to radians, use [method @GlobalScope.deg_to_rad]. - [b]Note:[/b] 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. + 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 [member top_level] is [code]true[/code]. In this coordinate system, affine operations correspond to direct affine operations on the [Node3D]'s [member transform]. The term "[i]parent space[/i]" refers to this coordinate system. The coordinate system that is attached to the [Node3D] itself is referred to as object-local coordinate system, or "[i]local space[/i]". + [b]Note:[/b] Unless otherwise specified, all methods that need angle parameters must receive angles in [i]radians[/i]. To convert degrees to radians, use [method @GlobalScope.deg_to_rad]. + [b]Note:[/b] In Godot 4, "[i]Spatial[/i]" nodes are named "[i]Node3D[/i]". Some parts of the documentation may still mention Godot 3.x's "[i]Spatial[/i]" nodes. $DOCS_URL/tutorials/3d/introduction_to_3d.html @@ -18,32 +18,33 @@ - Attach an editor gizmo to this [Node3D]. - [b]Note:[/b] 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]. + Attaches the given [param gizmo] to this node. Only works in the editor. + [b]Note:[/b] [param gizmo] should be an [EditorNode3DGizmo]. The argument type is [Node3DGizmo] to avoid depending on editor classes in [Node3D]. - Clear all gizmos attached to this [Node3D]. + Clears all [EditorNode3DGizmo] objects attached to this node. Only works in the editor. - 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. - 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 [member transform] to update. Fails if the node is not inside the tree. + [b]Note:[/b] For performance reasons, transform changes are usually accumulated and applied [i]once[/i] 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). - Returns all the gizmos attached to this [Node3D]. + Returns all the [EditorNode3DGizmo] objects attached to this node. Only works in the editor. @@ -57,14 +58,15 @@ - Returns the parent [Node3D], or [code]null[/code] if no parent exists, the parent is not of type [Node3D], or [member top_level] is [code]true[/code]. - [b]Note:[/b] Calling this method is not equivalent to [code]get_parent() as Node3D[/code], which does not take [member top_level] into account. + Returns the parent [Node3D] that directly affects this node's [member global_transform]. Returns [code]null[/code] if no parent exists, the parent is not a [Node3D], or [member top_level] is [code]true[/code]. + [b]Note:[/b] This method is not always equivalent to [method Node.get_parent], which does not take [member top_level] into account. - Returns the current [World3D] resource this [Node3D] node is registered to. + Returns the [World3D] this node is registered to. + Usually, this is the same as this node's viewport (see [method Node.get_viewport] and [method Viewport.find_world_3d]). @@ -72,51 +74,52 @@ - Rotates the global (world) transformation around axis, a unit [Vector3], by specified angle in radians. The rotation axis is in global coordinate system. + Rotates this node's [member global_transform] around the global [param axis] by the given [param angle], in radians. This operation is calculated in global space (relative to the world). - Scales the global (world) transformation by the given [Vector3] scale factors. + Scales this node's [member global_transform] by the given [param scale] factor. This operation is calculated in global space (relative to the world). + [b]Note:[/b] This method is not to be confused with the [member scale] property. - Moves the global (world) transformation by [Vector3] offset. The offset is in global coordinate system. + Adds the given translation [param offset] to the node's [member global_position] in global space (relative to the world). - Disables rendering of this node. Changes [member visible] to [code]false[/code]. + Prevents this node from being rendered. Equivalent to setting [member visible] to [code]false[/code]. This is the opposite of [method show]. - Returns whether node notifies about its local transformation changes. [Node3D] will not propagate this by default. + Returns [code]true[/code] if the node receives [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] whenever [member transform] changes. This is enabled with [method set_notify_local_transform]. - Returns whether this node uses a scale of [code](1, 1, 1)[/code] or its local transformation scale. + Returns [code]true[/code] if this node's [member scale] is ignored. See also [method set_disable_scale]. - Returns whether the node notifies about its global and local transformation changes. [Node3D] will not propagate this by default. + Returns [code]true[/code] if the node receives [constant NOTIFICATION_TRANSFORM_CHANGED] whenever [member global_transform] changes. This is enabled with [method set_notify_transform]. - Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree. + Returns [code]true[/code] if the node's [member visible] property is [code]true[/code] and all its [Node3D] ancestors are also visible. If any ancestor is hidden, this node is not visible and will not be rendered. @@ -128,8 +131,8 @@ Rotates the node so that the local forward axis (-Z, [constant Vector3.FORWARD]) points toward the [param target] position. The local up axis (+Y) points as close to the [param 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 [param target] position cannot be the same as the node's position, the [param up] vector cannot be zero, and the direction from the node's position to the [param target] vector cannot be parallel to the [param up] vector. - Operations take place in global space, which means that the node must be in the scene tree. If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). + [b]Note:[/b] Operations take place in global space, which means that the node must be in the scene tree. @@ -139,13 +142,13 @@ - Moves the node to the specified [param position], and then rotates the node to point toward the [param target] as per [method look_at]. Operations take place in global space. + Moves the node to the specified [param position], and then rotates the node to point toward the [param target] as per [method look_at]. This operation is calculated in global space (relative to the world). - Resets this node's transformations (like scale, skew and taper) preserving its rotation and translation by performing Gram-Schmidt orthonormalization on this node's [Transform3D]. + Orthonormalizes this node's [member basis]. This resets this node's [member scale] to the default, but preserves the [member position] and [member rotation]. See also [method Transform3D.orthonormalized]. @@ -153,7 +156,7 @@ - Rotates the local transformation around axis, a unit [Vector3], by specified angle in radians. + Rotates this node's [member transform] around the [param axis] by the given [param angle], in radians. This operation is calculated in parent space (relative to the parent). @@ -161,69 +164,73 @@ - Rotates the local transformation around axis, a unit [Vector3], by specified angle in radians. The rotation axis is in object-local coordinate system. + Rotates this node's local transformation around the [param axis] by the given [param angle], in radians. This operation is calculated in local space (relative to this node), and as such does not affect the [member position]. - Rotates the local transformation around the X axis by angle in radians. + Rotates this node's local transformation around its X axis by the given [param angle], in radians. This changes the pitch, without affecting the [member position]. - Rotates the local transformation around the Y axis by angle in radians. + Rotates this node's local transformation around its Y axis by the given [param angle], in radians. This changes the yaw, without affecting the the [member position]. - Rotates the local transformation around the Z axis by angle in radians. + Rotates this node's local transformation around its Z axis by the given [param angle], in radians. This changes the roll, without affecting the [member position]. - Scales the local transformation by given 3D scale factors in object-local coordinate system. + Scales this node's local transformation by the given [param scale] factor. This operation is calculated in local space (relative to this node). - Sets whether the node uses a scale of [code](1, 1, 1)[/code] or its local transformation scale. Changes to the local transformation scale are preserved. + If [code]true[/code], the node always uses the default scale of [code]Vector3(1, 1, 1)[/code], regardless of [member scale]'s value. See also [method is_scale_disabled]. - Reset all transformations for this node (sets its [Transform3D] to the identity matrix). + Sets this node's [member transform] to [constant Transform3D.IDENTITY], which resets all transformations in parent space ([member position], [member rotation], and [member scale]). - Sets whether the node ignores notification that its transformation (global or local) changed. + If [code]true[/code], the node will not receive [constant NOTIFICATION_TRANSFORM_CHANGED] or [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED]. + It may useful to call this method when handling these notifications to prevent infinite recursion. - Sets whether the node notifies about its local transformation changes. [Node3D] will not propagate this by default. + If [code]true[/code], the node will receive [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] whenever [member transform] changes. + [b]Note:[/b] Some 3D nodes such as [CSGShape3D] or [CollisionShape3D] automatically enable this to function correctly. - + - 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 [code]true[/code], the node will receive [constant NOTIFICATION_TRANSFORM_CHANGED] whenever [member global_transform] and [member transform] changes. + [b]Note:[/b] Most 3D nodes such as [VisualInstance3D] or [CollisionObject3D] automatically enable this to function correctly. + [b]Note:[/b] In the editor, nodes will propagate this notification to their children if a gizmo is attached (see [method add_gizmo]). @@ -232,143 +239,155 @@ - Set subgizmo selection for this node in the editor. + Selects the [param gizmo]'s subgizmo with the given [param id] and sets its transform. Only works in the editor. [b]Note:[/b] 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]. - Enables rendering of this node. Changes [member visible] to [code]true[/code]. + Allows this node to be rendered. Equivalent to setting [member visible] to [code]true[/code]. This is the opposite of [method hide]. - Transforms [param local_point] from this node's local space to world space. + Returns the [param local_point] converted from this node's local space to global space. This is the opposite of [method to_local]. - Transforms [param global_point] from world space to this node's local space. + Returns the [param global_point] converted from global space to this node's local space. This is the opposite of [method to_global]. - Changes the node's position by the given offset [Vector3]. - Note that the translation [param offset] is affected by the node's scale, so if scaled by e.g. [code](10, 1, 1)[/code], a translation by an offset of [code](2, 0, 0)[/code] would actually add 20 ([code]2 * 10[/code]) to the X coordinate. + Adds the given translation [param offset] to the node's [member position], in parent space (relative to the parent). As such, the final translation is multiplied by the node's [member scale], unlike [method translate_object_local]. - Changes the node's position by the given offset [Vector3] in local space. + Adds the given translation [param offset] to the node's position, in local space (relative to this node). As such, the final translation is relative to the node's facing direction. - Updates all the [Node3D] gizmos attached to this node. + Updates all the [EditorNode3DGizmo] objects attached to this node. Only works in the editor. - Basis of the [member transform] property. Represents the rotation, scale, and shear of this node. + Basis of the [member transform] property. Represents the rotation, scale, and shear of this node in parent space (relative to the parent node). - Global basis of this node. This is equivalent to [code]global_transform.basis[/code]. + Basis of the [member global_transform] property. Represents the rotation, scale, and shear of this node in global space (relative to the world). - - Global position of this node. This is equivalent to [code]global_transform.origin[/code]. + + Global position (translation) of this node in global space (relative to the world). This is equivalent to the [member global_transform]'s [member Transform3D.origin]. - Rotation part of the global transformation in radians, specified in terms of YXZ-Euler angles in the format (X angle, Y angle, Z angle). - [b]Note:[/b] 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 [Vector3] data structure not because the rotation is a vector, but only because [Vector3] exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful. + Global rotation of this node as [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians and in global space (relative to the world). This value is obtained from [member global_basis]'s rotation. + - The [member Vector3.x] is the angle around the global X axis (pitch); + - The [member Vector3.y] is the angle around the global Y axis (yaw); + - The [member Vector3.z] is the angle around the global Z axis (roll). + [b]Note:[/b] Unlike [member rotation], this property always follows the YXZ convention ([constant EULER_ORDER_YXZ]). - Helper property to access [member global_rotation] in degrees instead of radians. + The [member global_rotation] of this node, in degrees instead of radians. - World3D space (global) [Transform3D] of this node. + The transformation of this node, in global space (relative to the world). Contains and represents this node's [member global_position], [member global_rotation], and global scale. + [b]Note:[/b] Getting this property while the node is not inside the tree will fail and return [constant Transform3D.IDENTITY]. - - Local position or translation of this node relative to the parent. This is equivalent to [code]transform.origin[/code]. + + Position (translation) of this node in parent space (relative to the parent node). This is equivalent to the [member transform]'s [member Transform3D.origin]. - Access to the node rotation as a [Quaternion]. This property is ideal for tweening complex rotations. + Rotation of this node represented as a [Quaternion] in parent space (relative to the parent node). This value is obtained from [member basis]'s rotation. + [b]Note:[/b] Quaternions are much more suitable for 3D math but are less intuitive. Setting this property can be useful for interpolation (see [method Quaternion.slerp]). - 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 [member rotation_order] property. - [b]Note:[/b] 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 [Vector3] data structure not because the rotation is a vector, but only because [Vector3] exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful. - [b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [member rotation_degrees]. + Rotation of this node as [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians and in parent space (relative to the parent node). This value is obtained from [member basis]'s rotation. + - The [member Vector3.x] is the angle around the local X axis (pitch); + - The [member Vector3.y] is the angle around the local Y axis (yaw); + - The [member Vector3.z] is the angle around the local Z axis (roll). + The order of each consecutive rotation can be changed with [member rotation_order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]). + [b]Note:[/b] This property is edited in degrees in the inspector. If you want to use degrees in a script, use [member rotation_degrees]. - Helper property to access [member rotation] in degrees instead of radians. + The [member rotation] of this node, in degrees instead of radians. + [b]Note:[/b] This is [b]not[/b] the property available in the Inspector dock. - Specify how rotation (and scale) will be presented in the editor. + How this node's rotation and scale are displayed in the Inspector dock. - Specify the axis rotation order of the [member 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 [member rotation] property. The final orientation is calculated by rotating around the X, Y, and Z axis in this order. - Scale part of the local transformation. - [b]Note:[/b] 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. - [b]Note:[/b] Not all nodes are visually scaled by the [member scale] property. For example, [Light3D]s are not visually affected by [member scale]. + Scale of this node in parent space (relative to the parent node). This value is obtained from [member basis]'s scale. + [b]Note:[/b] The behavior of some 3D node types is not affected by this property. These include [Light3D], [Camera3D], [AudioStreamPlayer3D], etc. + [b]Warning:[/b] 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. - If [code]true[/code], the node will not inherit its transformations from its parent. Node transformations are only in global space. + If [code]true[/code], the node does not inherit its transformations from its parent. As such, node transformations will only be in global space, which also means that [member global_transform] and [member transform] will be identical. - Local space [Transform3D] of this node, with respect to the parent node. + The transformation of this node, in parent space (relative to the parent node). Contains and represents this node's [member position], [member rotation], and [member scale]. - 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 [member GeometryInstance3D.visibility_range_begin]. Nodes hidden via the [member Node3D.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 [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 [member GeometryInstance3D.visibility_range_begin]. Nodes hidden via the [member 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. - If [code]true[/code], this node is drawn. The node is only visible if all of its ancestors are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]). + If [code]true[/code], this node can be visible. The node is only rendered when all of its ancestors can be visible, as well. That means [method is_visible_in_tree] must return [code]true[/code]. - Emitted when node visibility changes. + Emitted when this node's visibility changes (see [member visible] and [method is_visible_in_tree]). + This signal is emitted [i]after[/i] the related [constant NOTIFICATION_VISIBILITY_CHANGED] notification. - - [Node3D] nodes receive this notification when their global transform changes. This means that either the current or a parent node changed its transform. - In order for [constant NOTIFICATION_TRANSFORM_CHANGED] to work, users first need to ask for it, with [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. + + Notification received when this node's [member global_transform] changes, if [method is_transform_notification_enabled] is [code]true[/code]. See also [method set_notify_transform]. + [b]Note:[/b] Most 3D nodes such as [VisualInstance3D] or [CollisionObject3D] automatically enable this to function correctly. + [b]Note:[/b] In the editor, nodes will propagate this notification to their children if a gizmo is attached (see [method add_gizmo]). - [Node3D] nodes receive this notification when they are registered to new [World3D] resource. + Notification received when this node is registered to a new [World3D] (see [method get_world_3d]). - [Node3D] nodes receive this notification when they are unregistered from current [World3D] resource. + Notification received when this node is unregistered from the current [World3D] (see [method get_world_3d]). - [Node3D] nodes receive this notification when their visibility changes. + Notification received when this node's visibility changes (see [member visible] and [method is_visible_in_tree]). + This notification is received [i]before[/i] the related [signal visibility_changed] signal. - [Node3D] nodes receive this notification when their local transform changes. This is not received when the transform of a parent node is changed. - In order for [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_local_transform]. + Notification received when this node's [member transform] changes, if [method is_local_transform_notification_enabled] is [code]true[/code]. This is not received when a parent [Node3D]'s [member transform] changes. See also [method set_notify_local_transform]. + [b]Note:[/b] Some 3D nodes such as [CSGShape3D] or [CollisionShape3D] automatically enable this to function correctly. - The rotation is edited using [Vector3] Euler angles. + The rotation is edited using a [Vector3] in [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url]. The rotation is edited using a [Quaternion]. - The rotation is edited using a [Basis]. In this mode, [member scale] can't be edited separately. + The rotation is edited using a [Basis]. In this mode, the raw [member basis]'s axes can be freely modified, but the [member scale] property is not available.