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 将度数转换为弧度。

属性

SpatialGizmo

gizmo

Transform

global_transform

Vector3

rotation

Vector3

rotation_degrees

Vector3( 0, 0, 0 )

Vector3

scale

Vector3( 1, 1, 1 )

Transform

transform

Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )

Vector3

translation

Vector3( 0, 0, 0 )

bool

visible

true

方法

void

force_update_transform ( )

Spatial

get_parent_spatial ( ) const

World

get_world ( ) 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_set_as_toplevel ( ) const

bool

is_transform_notification_enabled ( ) const

bool

is_visible_in_tree ( ) const

void

look_at ( Vector3 target, Vector3 up )

void

look_at_from_position ( Vector3 position, Vector3 target, Vector3 up )

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_as_toplevel ( bool enable )

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

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_gizmo ( )

信号

  • 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 --- 如果门户系统游戏监视器检测到它们已退出游戏区域,空间节点会收到此通知。

属性说明

Setter

set_gizmo(value)

Getter

get_gizmo()

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


Setter

set_global_transform(value)

Getter

get_global_transform()

此节点的世界空间(全局)Transform


Setter

set_rotation(value)

Getter

get_rotation()

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

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


Default

Vector3( 0, 0, 0 )

Setter

set_rotation_degrees(value)

Getter

get_rotation_degrees()

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


Default

Vector3( 1, 1, 1 )

Setter

set_scale(value)

Getter

get_scale()

局部变换的缩放部分。


Default

Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )

Setter

set_transform(value)

Getter

get_transform()

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


Default

Vector3( 0, 0, 0 )

Setter

set_translation(value)

Getter

get_translation()

此节点的局部变换。


Default

true

Setter

set_visible(value)

Getter

is_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 资源。


围绕轴(一个单位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。如果任何先决条件被隐藏,则该节点在场景树中将不可见。


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

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

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


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


  • void orthonormalize ( )

通过对该节点的Transform进行Gram-Schmidt正则化,重新设置该节点的变换(如比例、倾斜和锥度),保留其旋转和平移。


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


围绕轴(一个单位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


local_point从该节点的本地空间转换为世界空间。


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