Item3D¶

继承： Item < Object

派生： AudioListener, AudioPlayer, BoneSlot, Camera, ColliderObjectBase, ColliderPolygon, ColliderShape, GridMap, ImporterMeshRender, JointBase, LightProbe, SpaceMarker, NavigationLink, NavigationObstacle, NavigationRegion, OpenXRCompositionLayer, OpenXRHand, Route, RouteMove, RayCast, RemoteTransform, ShapeCast, SkeletonMesh, SkeletonRevamp, SpringArm, SpringBoneCollider, WheelCollider, VisualRender, XRFaceRevamp, XRNode, XROrigin

最基本的3D应用对象，所有3D相关节点的父节点。

描述¶

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

仿射操作（旋转、缩放、平移）发生在父级的局部坐标系中，除非将Item3D对象设置为顶级。该坐标系中的仿射操作对应于Item3D的变换上的直接仿射操作。下面的本地一词指的是该坐标系。附加到Item3D对象本身的坐标系称为对象-局部坐标系。

注意：除非另有说明，否则所有具有角度参数的方法都必须具有指定为弧度的角度。要将度转换为弧度，请使用@GlobalScope.deg_to_rad()。

属性¶

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)`
ItemPath	visibility_parent	`ItemPath("")`
bool	visible	`true`

方法¶

void	add_gizmo(gizmo: Node3DGizmo)
void	clear_gizmos()
void	clear_subgizmo_selection()
void	force_update_transform()
Array[Node3DGizmo]	get_gizmos() const
Transform3D	get_global_transform_interpolated()
Item3D	get_parent_item_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 🔗

Item3D节点在其全局变换更改时收到此通知。这意味着当前节点或父节点更改了其转换。

为了使NOTIFICATION_TRANSFORM_CHANGED工作，用户首先需要使用set_notify_transform()来请求它。如果节点在编辑器上下文中并且它至少有一个有效的gizmo，则也会发送通知。

NOTIFICATION_ENTER_WORLD = 41 🔗

Item3D节点在注册到新的World3D资源时会收到此通知。

NOTIFICATION_EXIT_WORLD = 42 🔗

Item3D节点在从当前World3D资源中取消注册时会收到此通知。

NOTIFICATION_VISIBILITY_CHANGED = 43 🔗

Item3D节点在其可见性更改时会收到此通知。

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗

Item3D节点在其本地转换更改时收到此通知。当父节点的转换更改时，不会收到此通知。

为了让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-Euler角的格式指定（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属性指定的顺序构造旋转。

注意：此属性在检查器中以度为单位进行编辑。如果要在脚本中使用度，请使用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中的混合负尺度不能从变换矩阵中分解。由于i3D中尺度用变换矩阵表示的方式，尺度值要么全部为正，要么全部为负。

注意：并非所有节点都通过scale属性进行视觉缩放。例如，Light在视觉上不受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，相对于父节点。

ItemPath visibility_parent = ItemPath("") 🔗

void set_visibility_parent(value: ItemPath)
ItemPath get_visibility_parent()

定义此节点及其子树的可见性范围父级。可见性父级必须是GeometryInstance3D。只有当可见性父级（及其所有可见性祖先）比其自己的GeometryRender.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) 🔗

将编辑器小发明附加到此Item3D。

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

void clear_gizmos() 🔗

清除连接到此Item3D的所有小发明。

void clear_subgizmo_selection() 🔗

在编辑器中清除此节点的subgizmo选择。当属性更改后subgizmo ID无效时很有用。

void force_update_transform() 🔗

强制转换更新。由于性能原因，物理中的转换更改不是即时的。转换会累积然后设置。如果您在执行物理操作时需要最新的转换，请使用此选项。

Array[Node3DGizmo] get_gizmos() const 🔗

返回附加到此Item3D的所有小玩意。

Transform3D get_global_transform_interpolated() 🔗

使用物理插值时，在某些情况下，您希望知道节点的插值（显示）变换，而不是标准变换（可能仅精确到最近的物理刻度）。

这对于发生在Item.Update()，而不是Item.FixedUpdate()。例子包括Camera聚焦在一个节点上，或者找到从框架上发射激光的位置，而不是物理刻度。

注意：此函数在第一次调用时在Item3D上创建一个插值泵，它可以响应物理插值重置。如果您在最初跟随Item3D时遇到“条纹”问题，请务必在重置Item3D物理插值之前至少调用get_global_transform_interpolated()一次。

Item3D get_parent_item_3d() const 🔗

返回父级Item3D，或者null如果不存在父级，父级不是Item3D类型，或者top_level是true。

注意：调用此方法不等同于get_parent（）作为Item3D，它不考虑top_level。

World3D get_world_3d() const 🔗

返回此Item3D节点注册到的当前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 🔗

返回节点是否通知其本地转换更改。Item3D默认情况下不会传播它。

bool is_scale_disabled() const 🔗

返回此节点是使用（1,1,1）的比例还是其本地转换比例。

bool is_transform_notification_enabled() const 🔗

返回节点是否通知其全局和本地转换更改。Item3D默认情况下不会传播它。

bool is_visible_in_tree() const 🔗

返回true如果节点存在于SceneTree中，则其visible属性为true并且其所有祖先也可见。如果隐藏了任何祖先，则该节点在场景树中将不可见。

仅在继承自Item3D的父节点中检查可见性。如果父节点是任何其他类型（例如Item、AnimationPlayer），则假定它是可见的。

注意：此方法不考虑VisualRender.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向量不能为零。

target和up不能是Vector3.ZERO，并且不应该是共线的，以避免围绕局部Z轴意外旋转。

操作发生在全局空间中，这意味着节点必须在场景树中。

如果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) 🔗

设置节点是否通知其本地转换更改。Item3D默认情况下不会传播它。

void set_notify_transform(enable: bool) 🔗

设置节点是否通知其全局和本地转换更改。Item3D默认情况下不会传播它，除非它在编辑器上下文中并且它具有有效的gizmo。

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

在编辑器中为该节点设置subgizmo选择。

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

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）偏移的平移实际上会将20（2*10）添加到X坐标。

void translate_object_local(offset: Vector3) 🔗

通过本地空间中给定的偏移量Vector3更改节点的位置。

void update_gizmos() 🔗

更新附加到此节点的所有Item3D小发明。