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.

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 🔗

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 🔗

该节点在 World3D 空间的(全局)Transform3D


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

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


Quaternion quaternion 🔗

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


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

以弧度为单位的,局部变换的旋转部分,根据欧拉角指定。角度按照 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 🔗

指定旋转(和缩放)在编辑器中的显示方式。


EulerOrder rotation_order = 2 🔗

指定 rotation 属性的轴旋转顺序。最终的方向是通过按该属性指定的顺序旋转欧拉角来构建的。


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

局部变换的缩放部分。

注意: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) 🔗

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


NodePath visibility_parent = NodePath("") 🔗

定义该节点及其子树的可见性范围父级。可见性父级必须是一个 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_leveltrue,则返回 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 🔗<