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.

Skeleton3D

继承: Node3D < Node < Object

包含骨骼层级结构的节点,用于创建 3D 骨骼动画。

描述

Skeleton3D 提供了管理骨骼层级结构的接口,包括姿势、放松姿势和动画(见 Animation)。它还可以使用布娃娃物理。

骨骼相对于骨架的整体变换由骨骼的姿势决定。骨骼的放松姿势定义的是骨骼姿势的初始变换。

请注意,下文的“全局姿势”是指骨骼相对于骨架的整体变换,因此并不是骨骼的实际全局/世界变换。

教程

属性

ModifierCallbackModeProcess

modifier_callback_mode_process

1

float

motion_scale

1.0

bool

show_rest_only

false

方法

int

add_bone(name: String)

void

clear_bones()

void

clear_bones_global_pose_override()

Skin

create_skin_from_rest_transforms()

int

find_bone(name: String) const

void

force_update_all_bone_transforms()

void

force_update_bone_child_transform(bone_idx: int)

bool

get_animate_physical_bones() const

PackedInt32Array

get_bone_children(bone_idx: int) const

int

get_bone_count() const

Transform3D

get_bone_global_pose(bone_idx: int) const

Transform3D

get_bone_global_pose_no_override(bone_idx: int) const

Transform3D

get_bone_global_pose_override(bone_idx: int) const

Transform3D

get_bone_global_rest(bone_idx: int) const

String

get_bone_name(bone_idx: int) const

int

get_bone_parent(bone_idx: int) const

Transform3D

get_bone_pose(bone_idx: int) const

Vector3

get_bone_pose_position(bone_idx: int) const

Quaternion

get_bone_pose_rotation(bone_idx: int) const

Vector3

get_bone_pose_scale(bone_idx: int) const

Transform3D

get_bone_rest(bone_idx: int) const

StringName

get_concatenated_bone_names() const

PackedInt32Array

get_parentless_bones() const

int

get_version() const

bool

is_bone_enabled(bone_idx: int) const

void

localize_rests()

void

physical_bones_add_collision_exception(exception: RID)

void

physical_bones_remove_collision_exception(exception: RID)

void

physical_bones_start_simulation(bones: Array[StringName] = [])

void

physical_bones_stop_simulation()

SkinReference

register_skin(skin: Skin)

void

reset_bone_pose(bone_idx: int)

void

reset_bone_poses()

void

set_animate_physical_bones(enabled: bool)

void

set_bone_enabled(bone_idx: int, enabled: bool = true)

void

set_bone_global_pose(bone_idx: int, pose: Transform3D)

void

set_bone_global_pose_override(bone_idx: int, pose: Transform3D, amount: float, persistent: bool = false)

void

set_bone_name(bone_idx: int, name: String)

void

set_bone_parent(bone_idx: int, parent_idx: int)

void

set_bone_pose(bone_idx: int, pose: Transform3D)

void

set_bone_pose_position(bone_idx: int, position: Vector3)

void

set_bone_pose_rotation(bone_idx: int, rotation: Quaternion)

void

set_bone_pose_scale(bone_idx: int, scale: Vector3)

void

set_bone_rest(bone_idx: int, rest: Transform3D)

void

unparent_bone_and_rest(bone_idx: int)


信号

bone_enabled_changed(bone_idx: int) 🔗

当使用 set_bone_enabled 切换 bone_idx 处的骨骼时发出。使用 is_bone_enabled 来检查新值。


bone_list_changed() 🔗

目前没有这个信号的描述。请帮我们贡献一个


pose_updated() 🔗

Emitted when the pose is updated.

Note: During the update process, this signal is not fired, so modification by SkeletonModifier3D is not detected.


show_rest_only_changed() 🔗

show_rest_only 的值改变时触发。


skeleton_updated() 🔗

Emitted when the final pose has been calculated will be applied to the skin in the update process.

This means that all SkeletonModifier3D processing is complete. In order to detect the completion of the processing of each SkeletonModifier3D, use SkeletonModifier3D.modification_processed.


枚举

enum ModifierCallbackModeProcess: 🔗

ModifierCallbackModeProcess MODIFIER_CALLBACK_MODE_PROCESS_PHYSICS = 0

在物理帧期间处理修改的标志(见 Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS)。

ModifierCallbackModeProcess MODIFIER_CALLBACK_MODE_PROCESS_IDLE = 1

在处理帧期间处理修改的标志(见 Node.NOTIFICATION_INTERNAL_PROCESS)。


常量

NOTIFICATION_UPDATE_SKELETON = 50 🔗

Notification received when this skeleton's pose needs to be updated. In that case, this is called only once per frame in a deferred process.


属性说明

ModifierCallbackModeProcess modifier_callback_mode_process = 1 🔗

Sets the processing timing for the Modifier.


float motion_scale = 1.0 🔗

  • void set_motion_scale(value: float)

  • float get_motion_scale()

与 3D 位置轨道动画相乘。

注意:除非这个值是 1.0,否则动画中的键值将与实际位置值不匹配。


bool show_rest_only = false 🔗

  • void set_show_rest_only(value: bool)

  • bool is_show_rest_only()

如果为 true,则无论其值如何,强制骨骼处于默认放松姿势。在编辑器中,这也会阻止骨骼被编辑。


方法说明

int add_bone(name: String) 🔗

添加具有给定名称的新骨骼。返回新骨骼的索引,如果该方法失败,则返回 -1

注意:骨骼名称应该是唯一的、非空的,并且不能包含 :/ 字符。


void clear_bones() 🔗

清除这个骨架上的所有骨骼。


void clear_bones_global_pose_override() 🔗

已弃用: 未来版本中可能修改或移除该方法。

移除骨架中所有骨骼上的全局姿势覆盖。


Skin create_skin_from_rest_transforms() 🔗

目前没有这个方法的描述。请帮我们贡献一个


int find_bone(name: String) const 🔗

Returns the bone index that matches name as its name. Returns -1 if no bone with this name exists.


void force_update_all_bone_transforms() 🔗

已弃用: This method should only be called internally.

强制更新该骨架中所有骨骼的变换/姿势。


void force_update_bone_child_transform(bone_idx: int) 🔗

强制更新索引为 bone_idx 的骨骼及其所有子项的变换/姿势。


bool get_animate_physical_bones() const 🔗

已弃用: 未来版本中可能修改或移除该方法。


PackedInt32Array get_bone_children(bone_idx: int) const 🔗

返回一个数组,其中包含传入骨骼 bone_idx 的所有子节点的骨骼索引。


int get_bone_count() const 🔗

返回骨架中骨骼的数量。


Transform3D get_bone_global_pose(bone_idx: int) const 🔗

Returns the overall transform of the specified bone, with respect to the skeleton. Being relative to the skeleton frame, this is not the actual "global" transform of the bone.

Note: This is the global pose you set to the skeleton in the process, the final global pose can get overridden by modifiers in the deferred process, if you want to access the final global pose, use SkeletonModifier3D.modification_processed.


Transform3D get_bone_global_pose_no_override(bone_idx: int) const 🔗

已弃用: 未来版本中可能修改或移除该方法。

返回指定骨骼的整体变换,相对于骨架,不包含任何全局姿势覆盖。由于是相对于骨架的,这不是该骨骼的实际“全局”变换。


Transform3D get_bone_global_pose_override(bone_idx: int) const 🔗

已弃用: 未来版本中可能修改或移除该方法。

返回 bone_idx 骨骼的全局姿势覆盖变换。


Transform3D get_bone_global_rest(bone_idx: int) const 🔗

返回 bone_idx 骨骼的全局放松变换。


String get_bone_name(bone_idx: int) const 🔗

返回索引为 bone_idx 的骨骼的名称。


int get_bone_parent(bone_idx: int) const 🔗

返回 bone_idx 处的骨骼的父级骨骼索引。如果为 -1,则该骨骼没有父级。

注意:返回的父骨骼索引总是小于 bone_idx


Transform3D get_bone_pose(bone_idx: int) const 🔗

Returns the pose transform of the specified bone.

Note: This is the pose you set to the skeleton in the process, the final pose can get overridden by modifiers in the deferred process, if you want to access the final pose, use SkeletonModifier3D.modification_processed.


Vector3 get_bone_pose_position(bone_idx: int) const 🔗

返回骨骼在 bone_idx处的姿势位置。返回的 Vector3 位于 Skeleton3D 节点的局部坐标空间中。


Quaternion get_bone_pose_rotation(bone_idx: int) const 🔗

返回 bone_idx 处骨骼的姿势旋转。返回的 Quaternion 是局部于该骨骼的,且相对于任何父骨骼的旋转。


Vector3 get_bone_pose_scale(bone_idx: int) const 🔗

返回 bone_idx 处骨骼的姿态缩放。


Transform3D get_bone_rest(bone_idx: int) const 🔗

返回骨骼 bone_idx 的放松变换。


StringName get_concatenated_bone_names() const 🔗

Returns all bone names concatenated with commas (,) as a single StringName.

It is useful to set it as a hint for the enum property.


PackedInt32Array get_parentless_bones() const 🔗

返回一个包含所有无父级的骨骼的数组。另一种看待这一点的方法是,它返回所有骨骼的索引,这些骨骼不依赖于该骨架中的其他骨骼,或不被该骨架中的其他骨骼修改。


int get_version() const 🔗

返回骨骼层次结构在该骨架中更改的次数,包括重命名。

骨架版本没有被序列化:只能在 Skeleton3D 的单个实例中使用。

用于使 IK 解算器中的和处理骨骼的其他节点中的缓存失效。


bool is_bone_enabled(bone_idx: int) const 🔗

返回位于 bone_idx 的骨骼是否启用了骨骼姿势。


void localize_rests() 🔗

将骨架中的所有骨骼都恢复到放松姿势。


void physical_bones_add_collision_exception(exception: RID) 🔗

已弃用: 未来版本中可能修改或移除该方法。

向物理骨骼添加一个碰撞例外。

就像 RigidBody3D 节点一样工作。


void physical_bones_remove_collision_exception(exception: RID) 🔗

已弃用: 未来版本中可能修改或移除该方法。

移除物理骨骼的一个碰撞例外。

就像 RigidBody3D 节点一样工作。


void physical_bones_start_simulation(bones: Array[StringName] = []) 🔗

已弃用: 未来版本中可能修改或移除该方法。

让 Skeleton 中的 PhysicalBone3D 节点开始仿真模拟,对物理世界做出反应。

可以传入骨骼名称列表,只对传入的骨骼进行仿真模拟。


void physical_bones_stop_simulation() 🔗

已弃用: 未来版本中可能修改或移除该方法。

让 Skeleton 中的 PhysicalBone3D 节点停止仿真模拟。


SkinReference register_skin(skin: Skin) 🔗

将给定的 Skin 绑定到 Skeleton。


void reset_bone_pose(bone_idx: int) 🔗

bone_idx 骨骼设置为放松姿势。


void reset_bone_poses() 🔗

将所有骨骼都设置为放松姿势。


void set_animate_physical_bones(enabled: bool) 🔗

已弃用: 未来版本中可能修改或移除该方法。


void set_bone_enabled(bone_idx: int, enabled: bool = true) 🔗

如果为 false 则为位于 bone_idx 的骨骼禁用姿势,如果为 true 则启用该骨骼姿势。


void set_bone_global_pose(bone_idx: int, pose: Transform3D) 🔗

Sets the global pose transform, pose, for the bone at bone_idx.

Note: If other bone poses have been changed, this method executes a dirty poses recalculation and will cause performance to deteriorate. If you know that multiple global poses will be applied, consider using set_bone_pose with precalculation.


void set_bone_global_pose_override(bone_idx: int, pose: Transform3D, amount: float, persistent: bool = false) 🔗

已弃用: 未来版本中可能修改或移除该方法。

bone_idx 处的骨骼设置全局姿势变换 pose

amount 是应用姿势时将使用的插值强度,persistent 决定应用的姿势是否会保留。

注意:姿势变换需要的是全局姿势!要将 Node3D 的世界变换转换为全局骨骼姿势,请将节点的 Node3D.global_transformTransform3D.affine_inverse 乘以所期望的世界变换。


void set_bone_name(bone_idx: int, name: String) 🔗

Sets the bone name, name, for the bone at bone_idx.


void set_bone_parent(bone_idx: int, parent_idx: int) 🔗

将骨骼索引 parent_idx 设置为 bone_idx 处骨骼的父级。如果为 -1,则该骨骼没有父级。

注意:parent_idx 必须小于