Node3D

继承: Node < Object

派生: AudioListener3D, AudioStreamPlayer3D, BoneAttachment3D, Camera3D, CollisionObject3D, CollisionPolygon3D, CollisionShape3D, GridMap, ImporterMeshInstance3D, Joint3D, LightmapProbe, Marker3D, NavigationLink3D, NavigationObstacle3D, NavigationRegion3D, OccluderInstance3D, OpenXRHand, Path3D, PathFollow3D, RayCast3D, RemoteTransform3D, ShapeCast3D, Skeleton3D, SpringArm3D, VehicleWheel3D, VisualInstance3D, 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 ( Node3DGizmo gizmo )

void

clear_gizmos ( )

void

clear_subgizmo_selection ( )

void

force_update_transform ( )

Node3DGizmo[]

get_gizmos ( ) const

Node3D

get_parent_node_3d ( ) const

World3D

get_world_3d ( ) const

void

global_rotate ( Vector3 axis, float angle )

void

global_scale ( Vector3 scale )

void

global_translate ( Vector3 offset )

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 ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false )

void

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

void

orthonormalize ( )

void

rotate ( Vector3 axis, float angle )

void

rotate_object_local ( Vector3 axis, float angle )

void

rotate_x ( float angle )

void

rotate_y ( float angle )

void

rotate_z ( float angle )

void

scale_object_local ( Vector3 scale )

void

set_disable_scale ( bool disable )

void

set_identity ( )

void

set_ignore_transform_notification ( bool enabled )

void

set_notify_local_transform ( bool enable )

void

set_notify_transform ( bool enable )

void

set_subgizmo_selection ( Node3DGizmo gizmo, int id, Transform3D transform )

void

show ( )

Vector3

to_global ( Vector3 local_point ) const

Vector3

to_local ( Vector3 global_point ) const

void

translate ( Vector3 offset )

void

translate_object_local ( Vector3 offset )

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 ( Basis value )

  • Basis get_basis ( )

直接访问 transform 属性的 3x3 基。


Basis global_basis

  • void set_global_basis ( Basis value )

  • Basis get_global_basis ( )

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


Vector3 global_position

  • void set_global_position ( Vector3 value )

  • Vector3 get_global_position ( )

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


Vector3 global_rotation

  • void set_global_rotation ( Vector3 value )

  • Vector3 get_global_rotation ( )

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

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


Vector3 global_rotation_degrees

  • void set_global_rotation_degrees ( Vector3 value )

  • 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 ( Vector3 value )

  • 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 ( bool value )

  • 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("")

  • void set_visibility_parent ( NodePath value )

  • NodePath get_visibility_parent ( )

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


bool visible = true

  • void set_visible ( bool value )

  • bool is_visible ( )

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


方法说明

void add_gizmo ( Node3DGizmo gizmo )

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

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


void clear_gizmos ( )

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


void clear_subgizmo_selection ( )

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


void force_update_transform ( )

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


Node3DGizmo[] get_gizmos ( ) const

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


Node3D get_parent_node_3d ( ) const

返回父节点 Node3D,如果不存在父节点,或父节点不是 Node3D 类型,则返回空的 Object


World3D get_world_3d ( ) const

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


void global_rotate ( Vector3 axis, float angle )

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


void global_scale ( Vector3 scale )

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


void global_translate ( Vector3 offset )

将全局(世界)变换按照 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 ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false )

旋转该节点,让局部向前的轴(-Z,Vector3.FORWARD)指向 target 的位置。

局部向上的轴(+Y)在保持与局部向前的轴垂直的前提下,尽可能接近 up 向量。最终的变换是正交变换,并且保留了原有缩放。非统一缩放可能无法正常工作。

target 位置不能和该节点的位置相同,up 向量不能为零,从节点的位置到 target 的向量不能与 up 平行。

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

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


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

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


void orthonormalize ( )

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


void rotate ( Vector3 axis, float angle )

围绕轴(单位 Vector3)旋转局部变换,指定角度(弧度)。


void rotate_object_local ( Vector3 axis, float angle )

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


void rotate_x ( float angle )

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


void rotate_y ( float angle )

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


void rotate_z ( float angle )

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


void scale_object_local ( Vector3 scale )

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


void set_disable_scale ( bool disable )

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


void set_identity ( )

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


void set_ignore_transform_notification ( bool enabled )

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


void set_notify_local_transform ( bool enable )

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


void set_notify_transform ( bool enable )

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


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

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

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


void show ( )

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


Vector3 to_global ( Vector3 local_point ) const

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


Vector3 to_local ( Vector3 global_point ) const

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


void translate ( Vector3 offset )

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

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


void translate_object_local ( Vector3 offset )

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


void update_gizmos ( )

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

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.