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¶

继承： 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”。

教程¶

属性¶

Basis	basis
Basis	global_basis
Vector3	global_position
Vector3	global_rotation
Vector3	global_rotation_degrees
Transform3D	global_transform
Vector3	position	`Vector3(0, 0, 0)`
Quaternion	quaternion
Vector3	rotation	`Vector3(0, 0, 0)`
Vector3	rotation_degrees
RotationEditMode	rotation_edit_mode	`0`
EulerOrder	rotation_order	`2`
Vector3	scale	`Vector3(1, 1, 1)`
bool	top_level	`false`
Transform3D	transform	`Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)`
NodePath	visibility_parent	`NodePath("")`
bool	visible	`true`

方法¶

void	add_gizmo(gizmo: Node3DGizmo)
void	clear_gizmos()
void	clear_subgizmo_selection()
void	force_update_transform()
Array[Node3DGizmo]	get_gizmos() const
Node3D	get_parent_node_3d() const
World3D	get_world_3d() const
void	global_rotate(axis: Vector3, angle: float)
void	global_scale(scale: Vector3)
void	global_translate(offset: Vector3)
void	hide()
bool	is_local_transform_notification_enabled() const
bool	is_scale_disabled() const
bool	is_transform_notification_enabled() const
bool	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	orthonormalize()
void	rotate(axis: Vector3, angle: float)
void	rotate_object_local(axis: Vector3, angle: float)
void	rotate_x(angle: float)
void	rotate_y(angle: float)
void	rotate_z(angle: float)
void	scale_object_local(scale: Vector3)
void	set_disable_scale(disable: bool)
void	set_identity()
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()
Vector3	to_global(local_point: Vector3) const
Vector3	to_local(global_point: Vector3) const
void	translate(offset: Vector3)
void	translate_object_local(offset: Vector3)
void	update_gizmos()

信号¶

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。