Spatial

Inherits: Node < Object

Inherited By: ARVRAnchor, ARVRController, ARVROrigin, AudioStreamPlayer3D, BoneAttachment, Camera, CollisionObject, CollisionPolygon, CollisionShape, CullInstance, GridMap, Joint, Listener, Navigation, NavigationMeshInstance, Occluder, Path, PathFollow, Portal, Position3D, ProximityGroup, RayCast, RemoteTransform, Room, RoomGroup, RoomManager, Skeleton, SpringArm, VehicleWheel

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

描述

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

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

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

教程

• Introduction to 3D

• All 3D Demos

属性

方法

信号

• gameplay_entered ( )

当节点进入游戏区域时由入口系统游戏监视器触发。

• gameplay_exited ( )

当节点退出游戏区域时，由界面系统的游戏监视器触发。

• visibility_changed ( )

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

常量

• NOTIFICATION_TRANSFORM_CHANGED = 2000 —- 当空间节点的全局变换发生变化时，空间节点会收到这个通知。这意味着当前节点或父节点改变了它的变换。

为了使NOTIFICATION_TRANSFORM_CHANGED生效，用户首先需要用set_notify_transform发送请求。如果节点是在编辑器的上下文中，并且它有一个有效的gizmo，那么该通知也会被发送。

• NOTIFICATION_ENTER_WORLD = 41 —- 空间节点在注册到新的 World 资源时会收到此通知。

• NOTIFICATION_EXIT_WORLD = 42 —- 当空间节点从当前的 World 资源中取消注册时，它们会收到此通知。

• NOTIFICATION_VISIBILITY_CHANGED = 43 —- 空间节点在其可见性发生变化时会收到此通知。

• NOTIFICATION_ENTER_GAMEPLAY = 45 —- 如果门户系统游戏监视器检测到它们已进入游戏区域，空间节点会收到此通知。

• NOTIFICATION_EXIT_GAMEPLAY = 46 —- 如果门户系统游戏监视器检测到它们已退出游戏区域，空间节点会收到此通知。

属性说明

• SpatialGizmo gizmo

此节点的 SpatialGizmo。例如在 EditorSpatialGizmo 中用作编辑器中的自定义可视化和编辑手柄。

• Transform global_transform

此节点的世界空间（全局）Transform。

• Vector3 rotation

局部变换的旋转部分以弧度表示，以YXZ-Euler角的形式表示(X角、Y角、Z角)。

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

• Vector3 rotation_degrees

旋转部分局部变换为度，按YXZ-Euler角格式指定(X角、Y角、Z角)。

• Vector3 scale

局部变换的缩放部分。

• Transform transform

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

• Vector3 translation

此节点的局部变换。

• bool visible

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

方法说明

• void force_update_transform ( )

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

• Spatial get_parent_spatial ( ) const

返回父对象 Spatial，如果不存在父对象或父对象不是 Spatial 类型，则返回一个空的 Object。

• World get_world ( ) const

返回此 Spatial 节点所注册的当前 World 资源。

• 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

返回节点是否通知其局部变换的变化。Spatial默认情况下不会对此进行传播。

• bool is_scale_disabled ( ) const

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

• bool is_set_as_toplevel ( ) const

返回该节点是否被设置为Toplevel，也就是是否忽略其父节点的变换。

• bool is_transform_notification_enabled ( ) const

返回节点是否通知其全局和局部的变换变化。默认情况下，Spatial不会对此进行传播。

• bool is_visible_in_tree ( ) const

如果该节点位于SceneTree中，并且其visible属性为true，并且其所有前提均可见，则返回true。如果任何先决条件被隐藏，则该节点在场景树中将不可见。

• void look_at ( Vector3 target, Vector3 up )

旋转自身，使局部-Z轴指向target位置。

变换将首先围绕给定的up矢量进行旋转，然后通过进一步围绕垂直于target和up矢量的轴进行旋转来完全对准目标。

操作是在全局空间进行的。

• void look_at_from_position ( Vector3 position, Vector3 target, Vector3 up )

将节点移动到指定的position，然后按照look_at的要求旋转自己以指向target。操作是在全局空间进行的。

• void orthonormalize ( )

通过对该节点的Transform进行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_as_toplevel ( bool enable )

使得节点忽略其父级的变换。节点的变换只在全局空间进行。

• void set_disable_scale ( bool disable )

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

• void set_identity ( )

重置该节点的所有变换（将其Transform重置为单位矩阵）。

• void set_ignore_transform_notification ( bool enabled )

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

• void set_notify_local_transform ( bool enable )

设置节点是否通知它的局部变换变化。默认情况下，Spatial不会传播这一点。

• void set_notify_transform ( bool enable )

设置节点是否通知其全局和局部变换的变化。Spatial默认情况下不会传播，除非是在编辑器上下文中，并且它有一个有效的gizmo。

• 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受节点比例因子(scale)的影响，所以如果按例如(10,1,1)进行缩放，平移(2,0,0)实际上会在X坐标上增加20 (2 * 10)。

• void translate_object_local ( Vector3 offset )

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

• void update_gizmo ( )

更新该节点的SpatialGizmo。