Node3D

继承： Node < Object

派生： AudioListener3D, AudioStreamPlayer3D, BoneAttachment3D, Camera3D, CollisionObject3D, CollisionPolygon3D, CollisionShape3D, GridMap, ImporterMeshInstance3D, Joint3D, LightmapProbe, Marker3D, NavigationLink3D, NavigationObstacle3D, NavigationRegion3D, OpenXRCompositionLayer, OpenXRHand, Path3D, PathFollow3D, RayCast3D, RemoteTransform3D, ShapeCast3D, Skeleton3D, SkeletonModifier3D, SpringArm3D, VehicleWheel3D, VisualInstance3D, XRFaceModifier3D, XRNode3D, XROrigin3D

最基本的 3D 游戏对象，所有 3D 相关节点的父类。

描述

最基本的 3D 游戏对象，具有 Transform3D 和可见性设置。所有其他的 3D 游戏对象都继承自 Node3D。在 3D 项目中，请使用 Node3D 作为父节点对子节点进行移动、缩放、旋转和显示/隐藏。

除非该 Node3D 对象被设置为顶层，否则仿射操作（旋转、缩放、平移）会在父节点的本地坐标系中进行。在这个坐标系中的仿射操作对应于对 Node3D 变换的直接仿射运算。下文中的本地一词指的就是这个坐标系。附加到 Node3D 对象本身的坐标系被称为对象本地坐标系。

注意：除非另有规定，所有有角度参数的方法必须将角度指定为弧度。请使用 @GlobalScope.deg_to_rad 将度数转换为弧度。

注意：请注意，从 Godot 4 开始，“Spatial”节点现在被称为“Node3D”。Godot 3.x 中指的“Spatial”节点，均指的是 Godot 4 中的“Node3D”。

教程

• 3D 简介

• 所有 3D 演示

属性

方法

信号

visibility_changed() 🔗

当节点可见性更改时触发。

枚举

enum RotationEditMode: 🔗

RotationEditMode ROTATION_EDIT_MODE_EULER = 0

旋转量以 Vector3 欧拉角的形式编辑。

RotationEditMode ROTATION_EDIT_MODE_QUATERNION = 1

旋转量以 Quaternion 的形式编辑。

RotationEditMode ROTATION_EDIT_MODE_BASIS = 2

旋转量以 Basis 的形式编辑。此模式下无法单独编辑 scale。

常量

NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗

Node3D 节点在自己的全局变换发生改变时，会收到这个通知。这意味着当前节点或者某个父节点的变换发生了改变。

用户需要使用 set_notify_transform 手动申请才能够收到 NOTIFICATION_TRANSFORM_CHANGED。如果该节点在编辑器环境中，并且拥有至少一个有效的小工具，则也会发送这个通知。

NOTIFICATION_ENTER_WORLD = 41 🔗

Node3D 节点在注册到新的 World3D 资源时，会收到这个通知。

NOTIFICATION_EXIT_WORLD = 42 🔗

Node3D 节点从当前的 World3D 资源中取消注册时，会收到这个通知。

NOTIFICATION_VISIBILITY_CHANGED = 43 🔗

Node3D 节点在其可见性发生变化时，会收到该通知。

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗

Node3D 节点在其局部变换发生改变时，会收到这个通知。父节点的变换发生改变时不会收到这个通知。

为了使 NOTIFICATION_LOCAL_TRANSFORM_CHANGED 起作用，用户首先需要使用 set_notify_local_transform 请求它。

属性说明

Basis basis 🔗

• void set_basis(value: Basis)

• Basis get_basis()

transform 属性的基。代表该节点的旋转、缩放、切变。

Basis global_basis 🔗

• void set_global_basis(value: Basis)

• Basis get_global_basis()

这个节点的全局基。与 global_transform.basis 等价。

Vector3 global_position 🔗

• void set_global_position(value: Vector3)

• Vector3 get_global_position()

这个节点的全局位置。与 global_transform.origin 等价。

Vector3 global_rotation 🔗

• void set_global_rotation(value: Vector3)

• Vector3 get_global_rotation()

全局变换的旋转部分，单位为弧度，以 YXZ 欧拉角的形式表示（X 角、Y 角、Z 角）。

注意：在数学意义上，旋转是一个矩阵而不是一个向量。这三个欧拉角是旋转矩阵欧拉角参数化的三个独立参数，存储在 Vector3 数据结构中并不是因为旋转是一个矢量，而是因为 Vector3 是一种方便存储 3 个浮点数的数据结构。因此，对旋转“向量”应用仿射操作是没有意义的。

Vector3 global_rotation_degrees 🔗

• void set_global_rotation_degrees(value: Vector3)

• Vector3 get_global_rotation_degrees()

辅助属性，用于按度数访问 global_rotation 而不是弧度数。

Transform3D global_transform 🔗

• void set_global_transform(value: Transform3D)

• Transform3D get_global_transform()

该节点在 World3D 空间的（全局）Transform3D。

Vector3 position = Vector3(0, 0, 0) 🔗

• void set_position(value: Vector3)

• Vector3 get_position()

该节点相对于父节点的局部位置或平移。相当于 transform.origin。

Quaternion quaternion 🔗

• void set_quaternion(value: Quaternion)

• Quaternion get_quaternion()

以一个 Quaternion 的形式访问该节点的旋转。该属性非常适合补间复杂的旋转。

Vector3 rotation = Vector3(0, 0, 0) 🔗

• void set_rotation(value: Vector3)

• Vector3 get_rotation()

以弧度为单位的，局部变换的旋转部分，根据欧拉角指定。角度按照 rotation_order 属性指定的顺序，构造一个旋转。

注意：在数学意义上，旋转是一个矩阵，而不是一个向量。三个欧拉角，即旋转矩阵的欧拉角参数化的三个独立参数，存储在一个 Vector3 数据结构中，并不是因为旋转是一个向量，而是因为 Vector3 是一个方便存储 3 个浮点数的数据结构。因此，对旋转“向量”，应用仿射操作是没有意义的。

注意：该属性在检查器中以度为单位进行编辑。如果要在脚本中使用度数，请使用 rotation_degrees。

Vector3 rotation_degrees 🔗

• void set_rotation_degrees(value: Vector3)

• Vector3 get_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 属性的轴旋转顺序。最终的方向是通过按该属性指定的顺序旋转欧拉角来构建的。

Vector3 scale = Vector3(1, 1, 1) 🔗

• void set_scale(value: Vector3)

• Vector3 get_scale()

局部变换的缩放部分。

注意：3D 中，变换矩阵是无法分解出正负混合的缩放的。由于 Godot 中使用变换矩阵来表示缩放，得到的缩放值要么全正、要么全负。

注意：并不是所有节点的外观都会被 scale 属性缩放。例如，Light3D 的外观就不受 scale 影响。

bool top_level = false 🔗

• void set_as_top_level(value: bool)

• bool is_set_as_top_level()

如果为 true，则该节点将不会从其父节点继承其变换。节点变换仅在全局空间中。

Transform3D transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗

• void set_transform(value: Transform3D)

• Transform3D get_transform()

该节点的局部空间 Transform3D，相对于父节点。

NodePath visibility_parent = NodePath("") 🔗

• void set_visibility_parent(value: NodePath)

• NodePath get_visibility_parent()

定义该节点及其子树的可见性范围父级。可见性父级必须是一个 GeometryInstance3D。仅当可见性父级（及其所有可见性祖先）通过比其自身 GeometryInstance3D.visibility_range_begin 更靠近相机而被隐藏时，任何视觉实例才会可见。通过 visible 属性隐藏的节点，基本上可以从可见性依赖树中移除，因此依赖实例不会考虑隐藏节点或其祖先。

bool visible = true 🔗

• void set_visible(value: bool)

• bool is_visible()

如果为 true，这个节点就会被画出来。只有当它的所有前项也是可见的时候，这个节点才是可见的（换句话说，is_visible_in_tree 必须返回 true）。

方法说明

void add_gizmo(gizmo: Node3DGizmo) 🔗

将编辑器小工具附加到该 Node3D。

注意：小工具对象通常是 EditorNode3DGizmo 的一个实例，但参数类型保持通用以避免在 Node3D 中创建对编辑器类的依赖。

void clear_gizmos() 🔗

清除附加于该 Node3D 的所有小工具。

void clear_subgizmo_selection() 🔗

在编辑器中，清除该节点的子小工具选择。在一个属性更改后，子小工具 ID 变得无效时很有用。

void force_update_transform() 🔗

强制更新变换。由于性能原因，物理中的变换改变不是即时的。变换是在累积后再设置。如果你在进行物理操作时需要最新的变换，请使用此功能。

Array[Node3DGizmo] get_gizmos() const 🔗

返回附加到该 Node3D 的所有小工具。

Node3D get_parent_node_3d() const 🔗

返回 Node3D 父节点，如果没有父节点、父节点不是 Node3D 类型或 top_level 为 true，则返回 null。

注意：调用这个方法并不等价于 get_parent() as Node3D，后者不会考虑 top_level。

World3D get_world_3d() const 🔗

返回此 Node3D 节点所注册的当前 World3D 资源。

void global_rotate(axis: Vector3, angle: float) 🔗

将全局（世界）变换围绕某个轴（单位 Vector3）旋转指定的弧度。旋转轴使用全局坐标系。

void global_scale(scale: Vector3) 🔗

将全局（世界）变换按照给定的 Vector3 缩放因子进行缩放。

void global_translate(offset: Vector3) 🔗

将全局（世界）变换按照 Vector3 偏移量进行移动。偏移量使用全局坐标系。

void hide() 🔗

禁用该节点的渲染。会将 visible 改为 false。

bool is_local_transform_notification_enabled() const 🔗

返回该节点是否通知其局部变换的更改。Node3D 默认不会传播此属性。

bool is_scale_disabled() const 🔗

返回该节点是否使用 (1, 1, 1) 的比例或其本地变换比例。

bool is_transform_notification_enabled() const 🔗

返回该节点是否通知其全局和局部变换的更改。Node3D 默认不会传播此属性。

bool is_visible_in_tree() const 🔗

如果该节点位于 SceneTree 中，并且其 visible 属性为 true，并且其所有上层节点也均可见，则返回 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 向量不能为零，从节点的位置到 target 的向量不能与 up 平行。

操作发生在全局空间，也就是说该节点必须位于场景树中。

如果 use_model_front 为 true，则会将 +Z 轴（资产正面）作为向前的轴（此时 +X 为左），指向 target 的位置。默认情况下会将 -Z 轴（相机前方）作为向前的轴（此时 +X 为右）。

void look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗

将节点移动到指定的 position，然后根据 look_at 旋转该节点以指向 target。操作发生在全局空间中。

void orthonormalize() 🔗

通过在该节点的 Transform3D 上执行 Gram-Schmidt 正交归一化，重置该节点的变换（如缩放、倾斜和锥度），以保留其旋转和平移。

void rotate(axis: Vector3, angle: float) 🔗

围绕轴（单位 Vector3）旋转局部变换，指定角度（弧度）。

void rotate_object_local(axis: Vector3, angle: float) 🔗

围绕轴（单位 Vector3）旋转局部变换，指定角度（弧度）。旋转轴是在物体的本地坐标系中。

void rotate_x(angle: float) 🔗

围绕 X 轴旋转局部变换，旋转角度为弧度。

void rotate_y(angle: float) 🔗

围绕 Y 轴旋转局部变换，旋转角度为弧度。

void rotate_z(angle: float) 🔗

围绕 Z 轴旋转局部变换，旋转角度为弧度。

void scale_object_local(scale: Vector3) 🔗

在物体局部坐标系中，通过给定的 3D 比例因子来缩放局部变换。

void set_disable_scale(disable: bool) 🔗

设置节点是否使用 (1, 1, 1) 的比例或其本地变换比例。对本地变换比例的改变会被保留下来。

void set_identity() 🔗

重置此节点的所有变换（将其 Transform3D 设置为单位矩阵）。

void set_ignore_transform_notification(enabled: bool) 🔗

设置该节点是否忽略其转换（全局或局部）改变的通知。

void set_notify_local_transform(enable: bool) 🔗

设置该节点是否通知其局部变换的更改。Node3D 默认不会传播此属性。

void set_notify_transform(enable: bool) 🔗

设置该节点是否通知其全局和局部变换的更改。Node3D 默认不会传播此属性，除非位于编辑器上下文中，并且存在有效的小工具。

void set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) 🔗

在编辑器中为该节点设置子小工具选区。

注意：小工具对象通常是 EditorNode3DGizmo 的一个实例，但参数类型保持通用以避免在 Node3D 中创建对编辑器类的依赖。

void show() 🔗

启用此节点的呈现。将 visible 更改为 true。

Vector3 to_global(local_point: Vector3) const 🔗

将 local_point 从这个节点的局部空间转换为世界空间。

Vector3 to_local(global_point: Vector3) const 🔗

将 global_point 从世界空间转换到这个节点的局部空间。

void translate(offset: Vector3) 🔗

通过给定的偏移量 Vector3 更改该节点的位置。

请注意，平移 offset 受节点缩放的影响，因此如果按例如 (10, 1, 1) 的比例缩放，那么偏移 (2, 0, 0) 的平移，实际上会在 X 坐标上增加 20（2 * 10）。

void translate_object_local(offset: Vector3) 🔗

通过给定的局部空间偏移量 Vector3 改变该节点的位置。

void update_gizmos() 🔗

更新附加于该节点的所有 Node3D 小工具。