Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Node3D
派生： AudioListener3D, AudioStreamPlayer3D, BoneAttachment3D, Camera3D, CollisionObject3D, CollisionPolygon3D, CollisionShape3D, GridMap, ImporterMeshInstance3D, Joint3D, LightmapProbe, Marker3D, NavigationLink3D, NavigationObstacle3D, NavigationRegion3D, OpenXRCompositionLayer, OpenXRHand, OpenXRRenderModel, OpenXRRenderModelManager, Path3D, PathFollow3D, RayCast3D, RemoteTransform3D, ShapeCast3D, Skeleton3D, SkeletonModifier3D, SpringArm3D, SpringBoneCollision3D, VehicleWheel3D, VisualInstance3D, XRFaceModifier3D, XRNode3D, XROrigin3D
3D 空间中的基础对象，所有 3D 节点都会继承。
描述
Node3D 节点是对位于 3D 空间中的节点基础表示，所有其他 3D 节点都继承自该类。
除非该 Node3D 的 top_level 为 true，仿射操作（旋转、缩放、平移）的计算都使用相对于父节点的坐标系。在这一坐标系中，放射操作对应于该 Node3D 的 transform 的直接仿射运算。术语父空间指的就是这个坐标系。附加到 Node3D 本身的坐标系被称为对象本地坐标系，即局部空间。
注意：除非另行说明，所有需要提供角度参数的方法收到的角度都必须以弧度为单位。请使用 @GlobalScope.deg_to_rad() 将度数转换为弧度。
注意：Godot 3 及更早版本中，Node3D 的名字叫 Spatial（空间节点）。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
void |
add_gizmo(gizmo: Node3DGizmo) |
void |
|
void |
|
void |
|
get_gizmos() const |
|
get_parent_node_3d() const |
|
get_world_3d() const |
|
void |
global_rotate(axis: Vector3, angle: float) |
void |
global_scale(scale: Vector3) |
void |
global_translate(offset: Vector3) |
void |
hide() |
is_scale_disabled() const |
|
is_visible_in_tree() const |
|
void |
look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) |
void |
look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) |
void |
|
void |
|
void |
rotate_object_local(axis: Vector3, angle: float) |
void |
|
void |
|
void |
|
void |
scale_object_local(scale: Vector3) |
void |
set_disable_scale(disable: bool) |
void |
|
void |
set_ignore_transform_notification(enabled: bool) |
void |
set_notify_local_transform(enable: bool) |
void |
set_notify_transform(enable: bool) |
void |
set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) |
void |
show() |
void |
|
void |
translate_object_local(offset: Vector3) |
void |
信号
visibility_changed() 🔗
该节点的可见性发生改变时发出（见 visible 和 is_visible_in_tree()）。
这个信号会在相关的 NOTIFICATION_VISIBILITY_CHANGED 通知之后触发。
枚举
enum RotationEditMode: 🔗
RotationEditMode ROTATION_EDIT_MODE_EULER = 0
该旋转角度是通过一个 Euler angles（Euler angles）类型的 Vector3（三维向量）来进行编辑的。在 Godot 中，欧拉角始终使用内旋（intrinsic）顺序，这意味着旋转是围绕物体自身的局部坐标轴进行的。
RotationEditMode ROTATION_EDIT_MODE_QUATERNION = 1
旋转量以 Quaternion（四元数）的形式进行编辑。四元数可以避免 gimbal lock 以及必须选择旋转顺序的问题，但不如欧拉角直观。四元数旋转与 3D 几何代数中的旋转子（rotors）基本相同，只是数值的标记方式不同。
RotationEditMode ROTATION_EDIT_MODE_BASIS = 2
常量
NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗
如果 is_transform_notification_enabled() 为 true，该节点的 global_transform 发生改变时收到的通知。另见 set_notify_transform()。
注意：VisualInstance3D、CollisionObject3D 等大多数 3D 节点都会自动启用，从而正常工作。
注意：在编辑器中，如果节点附加了小工具，就会将该通知传播给子节点（见 add_gizmo()）。
NOTIFICATION_ENTER_WORLD = 41 🔗
当该节点注册至新 World3D 时收到的通知（见 get_world_3d()）。
NOTIFICATION_EXIT_WORLD = 42 🔗
当该节点从当前 World3D 中注销时收到的通知（见 get_world_3d()）。
该通知会以反向顺序发送。
NOTIFICATION_VISIBILITY_CHANGED = 43 🔗
节点的可见性发生改变时收到的通知（见 visible 和 is_visible_in_tree()）。
该通知会在相关 visibility_changed 信号之前收到。
NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗
如果 is_local_transform_notification_enabled() 为 true，该节点的 transform 发生改变时收到的通知。父级 Node3D 节点的 transform 发生改变时不会受到该通知。另见 set_notify_local_transform()。
注意：CSGShape3D、CollisionShape3D 等部分节点会自动启用，从而正常工作。
属性说明
transform 属性的基。代表该节点在父空间中的旋转、缩放、倾斜（相对于父节点）。
global_transform 属性的基。代表该节点在全局空间中的旋转、缩放、倾斜（相对于世界）。
注意：如果该节点不在树中，则获取该属性会失败并返回 Basis.IDENTITY。
该节点的全局位置（平移），使用全局空间（相对于世界）。等价于 global_transform 的 Transform3D.origin。
注意：如果该节点不在树中，则获取该属性会失败并返回 Vector3.ZERO。
该节点的全局旋转欧拉角，单位为弧度，使用全局空间（相对于世界）。该值获取自 global_basis 的旋转。
注意：与 rotation 不同，该属性始终使用 YXZ 约定（@GlobalScope.EULER_ORDER_YXZ）。
注意：如果该节点不在树中，则获取该属性会失败并返回 Vector3.ZERO。
Vector3 global_rotation_degrees 🔗
该节点的 global_rotation，但单位为角度而非弧度。
注意：如果该节点不在树中，则获取该属性会失败并返回 Vector3.ZERO。
Transform3D global_transform 🔗
void set_global_transform(value: Transform3D)
Transform3D get_global_transform()
该节点的变换，使用全局空间（相对于世界）。包含并代表该节点的 global_position、global_rotation 以及全局缩放。
注意：如果该节点不在树中，则获取该属性会失败并返回 Transform3D.IDENTITY。
Vector3 position = Vector3(0, 0, 0) 🔗
该节点的位置（平移），使用父空间（相对于父节点）。等价于 transform 的 Transform3D.origin。
Quaternion quaternion 🔗
void set_quaternion(value: Quaternion)
Quaternion get_quaternion()
该节点的旋转，以父空间中的四元数 Quaternion 的形式显示（相对于父节点）。该值获取自 basis 的旋转。
注意：四元数更适合 3D 数学运算，但相对不那么直观。设置该属性可能适用于插值（见 Quaternion.slerp()）。
Vector3 rotation = Vector3(0, 0, 0) 🔗
该节点的旋转角度，以 Euler angles（Euler angles）表示，单位为弧度，且处于父空间（相对于父节点）。该值提取自 basis 的旋转分量。
Vector3.x 是围绕局部 X 轴的旋转角度（俯仰角 / pitch）；
Vector3.y 是围绕局部 Y 轴的旋转角度（偏航角 / yaw）；
Vector3.z 是围绕局部 Z 轴的旋转角度（滚转角 / roll）。
每次连续旋转的顺序可以通过 rotation_order 来更改（详见 EulerOrder 常量）。在 Godot 中，欧拉角始终使用内旋（intrinsic）顺序。默认情况下，使用的是内旋 YXZ 约定（@GlobalScope.EULER_ORDER_YXZ）。
注意： 此属性在检视器（inspector）中是以“度”为单位进行编辑的。如果你想在脚本中使用“度”作为单位，请使用 rotation_degrees。
该节点的 rotation，但单位为角度而非弧度。
注意：这不是检查器面板中的那个属性。
RotationEditMode rotation_edit_mode = 0 🔗
void set_rotation_edit_mode(value: RotationEditMode)
RotationEditMode get_rotation_edit_mode()
该节点的旋转和缩放在检查器面板中的显示方式。
EulerOrder rotation_order = 2 🔗
void set_rotation_order(value: EulerOrder)
EulerOrder get_rotation_order()
rotation 属性的轴旋转顺序。在 Godot 中，欧拉角始终使用内旋（intrinsic）顺序，这意味着最终的朝向是通过按照此顺序绕局部轴旋转来计算的。
Vector3 scale = Vector3(1, 1, 1) 🔗
该节点的缩放，使用局部空间（相对于该节点）。该值获取自 basis 的缩放。
注意：部分 3D 节点类型的行为不受该属性的影响。例如 Light3D、Camera3D、AudioStreamPlayer3D 等。
警告：各缩放分量的正负必须一致，并且不能完全等于 0.0。否则无法从 basis 获取该缩放值，可能导致所需的缩放在从磁盘重新加载后丢失，以及其他潜在的不稳定行为。
如果为 true，则该节点不会继承其父节点的变换。因此，节点的变换只会在全局空间中进行，同时也意味着 global_transform 和 transform 完全一致。
Transform3D transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗
void set_transform(value: Transform3D)
Transform3D get_transform()
该节点的局部变换，使用父空间（相对于父节点）。包含并代表该节点的 position、rotation 以及 scale。
NodePath visibility_parent = NodePath("") 🔗
该节点及其子级的可见性范围父级。可见性父级必须是一个 GeometryInstance3D。
仅当可见性父级节点（及其所有可见性祖级节点）因为与相机的距离比其自身 GeometryInstance3D.visibility_range_begin 更近而被隐藏时，视觉实例才会可见。通过 visible 属性隐藏的节点，可以看作被从可见性依赖树中移除，因此依赖实例不会考虑隐藏节点或其祖级节点。
如果为 true，则该节点能否显示。只有当所有祖先节点都是可见的时候，这个节点才可见。换句话说，is_visible_in_tree() 必须返回 true。
方法说明
void add_gizmo(gizmo: Node3DGizmo) 🔗
将小工具 gizmo 附加至该节点。仅在编辑器中有效。
注意：gizmo 应为 EditorNode3DGizmo。参数类型使用 Node3DGizmo 是为了避免在 Node3D 中对编辑器类产生依赖。
void clear_gizmos() 🔗
清空所有附加到该节点的 EditorNode3DGizmo 对象。仅在编辑器中生效。
void clear_subgizmo_selection() 🔗
取消选中该节点的所有子小工具。适用于选中的子小工具在属性发生改变后不再存在的情况。仅在编辑器中有效。
void force_update_transform() 🔗
发送 NOTIFICATION_TRANSFORM_CHANGED，强制更新该节点的 global_transform。如果该节点不在树中则失败。
注意：出于性能原因，变换的更改通常会累积到一帧的末尾进行单次应用。更新还会传播至 Node3D 子节点。因此，请仅在需要最新变换时使用该方法（例如在物理操作期间）。
Array[Node3DGizmo] get_gizmos() const 🔗
返回附加于该节点的所有 EditorNode3DGizmo 对象。仅在编辑器中有效。
Transform3D get_global_transform_interpolated() 🔗
使用物理插值时，你可能会想要了解节点插值后（显示）的变换而不是标准变换（标准变换可能仅在最近的物理周期中准确）。
如果是在 Node._process() 中进行的基于帧的操作，而不是在 Node._physics_process() 中进行，这一点就尤为重要。例如让 Camera3D 聚焦某个节点，或在帧中而不是在物理周期中找到激光发射的位置。
注意：第一次对 Node2D 调用该函数时会产生插值跳跃，重置物理插值后也会产生这样的现象。如果在最初跟随 Node3D 时遇到“拖影”问题，请确保在重置 Node3D 的物理插值之前至少调用一次 get_global_transform_interpolated()。
Node3D get_parent_node_3d() const 🔗
返回直接对该节点的 global_transform 产生影响的父级 Node3D 节点。如果不存在父节点、父节点不是 Node3D 或 top_level 为 true 则返回 null。
注意：该方法并不总是等价于 Node.get_parent()，后者不会考虑 top_level。
World3D get_world_3d() const 🔗
返回该节点注册到的 World3D。
通常与该节点视口的世界一致（见 Node.get_viewport() 和 Viewport.find_world_3d()）。
void global_rotate(axis: Vector3, angle: float) 🔗
将该节点的 global_basis 绕全局轴 axis 旋转，旋转弧度为 angle。该操作所涉及的计算在全局空间中进行（相对于世界），global_position 保持不变。
void global_scale(scale: Vector3) 🔗
使用 scale 中给定的缩放系数对该节点的 global_basis 进行缩放。该操作所设计的计算在全局空间中进行（相对于世界），global_position 保持不变。
注意：请勿将该方法与 scale 属性混淆。
void global_translate(offset: Vector3) 🔗
向该节点的 global_position 添加 offset 中指定的全局空间平移偏移量（相对于世界）。
void hide() 🔗
阻止渲染该节点。等价于将 visible 设置为 false。该方法与 show() 相对。
bool is_local_transform_notification_enabled() const 🔗
如果该节点会在 transform 改变时收到 NOTIFICATION_LOCAL_TRANSFORM_CHANGED 则返回 true。可以通过 set_notify_local_transform() 启用这一行为。
bool is_scale_disabled() const 🔗
如果该节点的 global_transform 会自动进行正交归一化，则返回 true。正交归一化的节点不会变形，效果与全局缩放为 Vector3.ONE（或对应的负值）一致。另见 is_scale_disabled() 和 orthonormalize()。
注意：该设置不影响 transform。
bool is_transform_notification_enabled() const 🔗
如果该节点会在 global_transform 改变时收到 NOTIFICATION_TRANSFORM_CHANGED 则返回 true。可以通过 set_notify_transform() 启用这一行为。
bool is_visible_in_tree() const 🔗
如果该节点位于场景树中且该节点及其所有连续的 Node3D 祖先节点的 visible 属性均为 true，则返回 true。其他类型的祖先节点（例如 Node、Node2D）都会打断连续。另见 Node.get_parent()。
注意：该方法无法考虑 VisualInstance3D.layers，因此即便该方法返回 true，也可能不渲染该节点。
void look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
旋转该节点，让局部向前的轴（-Z，Vector3.FORWARD）指向 target 的位置。该操作所涉及的运算在全局空间中进行（相对于世界）。
局部向上的轴（+Y）在保持与局部向前的轴垂直的前提下，尽可能接近 up 向量。最终的变换是正交变换，并且保留了原有缩放。非统一缩放可能无法正常工作。
target 位置不能和该节点的位置相同，up 向量不能为 Vector3.ZERO。此外，节点位置到 target 位置的方向不能与 up 向量平行，这样可以避免围绕局部 Z 轴发生预料之外的旋转。
如果 use_model_front 为 true，则会将 +Z 轴（资产正面）作为向前的轴（此时 +X 为左），指向 target 的位置。默认情况下会将 -Z 轴（相机前方）作为向前的轴（此时 +X 为右）。
注意：如果该节点不在场景树中，则该方法失败。必要时请改用 look_at_from_position()。
void look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
将该节点移动到 position 位置，然后旋转至指向 target 位置，类似于 look_at()。操作发生在全局空间中（相对于世界）。
void orthonormalize() 🔗
将该节点的 basis 进行正交归一化。该方法会将该节点的 scale 设置为 Vector3.ONE（或对应的负值），保持 position 和 rotation 不变。另见 Transform3D.orthonormalized()。
void rotate(axis: Vector3, angle: float) 🔗
将节点的 basis 绕 axis 轴旋转，旋转角 angle 的单位为弧度。该操作在父空间中进行计算（相对于父节点），position 保持不变。
void rotate_object_local(axis: Vector3, angle: float) 🔗
将节点的 basis 绕 axis 轴旋转，旋转角 angle 的单位为弧度。该操作在局部空间中进行计算（相对于该节点），position 保持不变。
将节点的 basis 绕 X 轴旋转，旋转角 angle 的单位为弧度。该操作在父空间中进行计算（相对于父节点），position 保持不变。
将节点的 basis 绕 Y 轴旋转，旋转角 angle 的单位为弧度。该操作在父空间中进行计算（相对于父节点），position 保持不变。
将节点的 basis 绕 Z 轴旋转，旋转角 angle 的单位为弧度。该操作在父空间中进行计算（相对于父节点），position 保持不变。
void scale_object_local(scale: Vector3) 🔗
将节点的 basis 进行缩放，缩放系数为 scale。该操作在局部空间中进行计算（相对于该节点），position 保持不变。
void set_disable_scale(disable: bool) 🔗
如果为 true，则该节点的 global_transform 会自动进行正交归一化。正交归一化的节点不会变形，效果与全局缩放为 Vector3.ONE（或对应的负值）一致。另见 is_scale_disabled() 和 orthonormalize()。
注意：该设置不影响 transform。
void set_identity() 🔗
将该节点的 transform 设置为 Transform3D.IDENTITY，会重置父空间中的所有变换（position、rotation、scale）。
void set_ignore_transform_notification(enabled: bool) 🔗
如果为 true，则该节点不会收到 NOTIFICATION_TRANSFORM_CHANGED 和 NOTIFICATION_LOCAL_TRANSFORM_CHANGED。
适用于在处理这些通知时阻止无限递归。
void set_notify_local_transform(enable: bool) 🔗
如果为 true，则该节点会在 transform 发生变化时收到 NOTIFICATION_LOCAL_TRANSFORM_CHANGED。
注意：CSGShape3D、CollisionShape3D 等部分 3D 节点会自动启用，从而正常工作。
void set_notify_transform(enable: bool) 🔗
如果为 true，则该节点会在 global_transform 发生变化时收到 NOTIFICATION_TRANSFORM_CHANGED。
注意：VisualInstance3D、CollisionObject3D 等大多数 3D 节点会自动启用，从而正常工作。
注意：在编辑器中，如果节点附加了小工具，就会将该通知传播给子节点（见 add_gizmo()）。
void set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) 🔗
选中小工具 gizmo 的 ID 为 id 的子小工具，并设置其变换。仅在编辑器中有效。
注意：小工具对象通常是 EditorNode3DGizmo 的实例，但参数类型保持通用以避免在 Node3D 中创建对编辑器类的依赖。
void show() 🔗
允许渲染该节点。等价于将 visible 设置为 true。该方法与 hide() 相对。
Vector3 to_global(local_point: Vector3) const 🔗
返回将 local_point 从该节点的局部空间转换至全局空间的结果。该方法与 to_local() 相对。
Vector3 to_local(global_point: Vector3) const 🔗
返回将 global_point 从全局空间转换至该节点的局部空间的结果。该方法与 to_global() 相对。
void translate(offset: Vector3) 🔗
向该节点的位置添加平移偏移量 offset，使用局部空间（相对于该节点）。
注意：请优先使用 translate_object_local()，因为本方法可能在后续版本中发生改变。
注意：该操作所涉及的运算不是在父空间中进行的，这与该方法的命名方式不一致是处于兼容考虑。要在父空间中进行平移请向 position 添加 offset（node_3d.position += offset）。
void translate_object_local(offset: Vector3) 🔗
向该节点的位置添加平移偏移量 offset，使用局部空间（相对于该节点）。
void update_gizmos() 🔗
更新附加于该节点的所有 EditorNode3DGizmo 小工具。仅在编辑器中有效。