Skeleton3D

继承： Node3D < Node < Object

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

描述

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

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

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

教程

• 第三人称射击（TPS）演示

属性

方法

信号

bone_enabled_changed(bone_idx: int) 🔗

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

bone_list_changed() 🔗

该信号目前没有描述，请帮我们贡献一个吧 ！

pose_updated() 🔗

姿势发生更改时发出。

注意：更新过程中不会发出该信号，因此不会检测到 SkeletonModifier3D 的修改。

show_rest_only_changed() 🔗

当 show_rest_only 的值改变时触发。

skeleton_updated() 🔗

当最终姿势计算完成后发出，将在更新过程中应用于皮肤。

这意味着所有 SkeletonModifier3D 处理都已完成。为了检测每个 SkeletonModifier3D 处理的完成情况，请使用 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 🔗

骨架的姿势需要更新时收到的通知。每帧只会通过延迟处理调用一次。

属性说明

bool animate_physical_bones = true 🔗

• void set_animate_physical_bones(value: bool)

• bool get_animate_physical_bones()

已弃用： 未来版本中可能会修改或移除该属性。

If you follow the recommended workflow and explicitly have PhysicalBoneSimulator3D as a child of Skeleton3D, you can control whether it is affected by raycasting without running physical_bones_start_simulation, by its SkeletonModifier3D.active.

However, for old (deprecated) configurations, Skeleton3D has an internal virtual PhysicalBoneSimulator3D for compatibility. This property controls the internal virtual PhysicalBoneSimulator3D‘s SkeletonModifier3D.active.

ModifierCallbackModeProcess modifier_callback_mode_process = 1 🔗

• void set_modifier_callback_mode_process(value: ModifierCallbackModeProcess)

• ModifierCallbackModeProcess get_modifier_callback_mode_process()

设置修改器的处理时机。

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 🔗

返回与 name 匹配的骨骼索引。如果不存在具有该名称的骨骼，则返回 -1。

void force_update_all_bone_transforms() 🔗

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

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

void force_update_bone_child_transform(bone_idx: int) 🔗

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

PackedInt32Array get_bone_children(bone_idx: int) const 🔗

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

int get_bone_count() const 🔗

返回骨架中骨骼的数量。

Transform3D get_bone_global_pose(bone_idx: int) const 🔗

返回指定骨骼相对于骨架的整体变换。相对于骨架帧，这不是骨骼的实际“全局”变换。

注意：这是你在 process 期间为骨架设置的全局姿势，最终全局姿势可能会被延迟 process 期间的修改器覆盖，如果你想访问最终全局姿势，请使用 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 🔗

返回指定骨骼的姿势变换。

注意：这是你在 process 期间为骨架设置的姿势，最终姿势可能会被延迟 process 期间的修改器覆盖，如果你想访问最终姿势，请使用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 🔗

返回将所有骨骼名称用英文逗号（,）连接得到的 StringName。

可以用作枚举属性的提示。

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_bone_enabled(bone_idx: int, enabled: bool = true) 🔗

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

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

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

注意：如果其他骨骼姿势已更改，该方法将执行一个脏的姿势重新计算，并会导致性能下降。如果你知道将应用多个全局姿势，请考虑使用带预计算的 set_bone_pose。

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

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

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

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

注意：姿势变换需要的是全局姿势！要将 Node3D 的世界变换转换为全局骨骼姿势，请将节点的 Node3D.global_transform 的 Transform3D.affine_inverse 乘以所期望的世界变换。

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

将索引号为 bone_idx 的骨骼的名称设置为 name。

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

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

注意：parent_idx 必须小于 bone_idx。

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

将索引号为 bone_idx 的骨骼的姿势变换设置为 pose。

void set_bone_pose_position(bone_idx: int, position: Vector3) 🔗

将 bone_idx 处的骨骼姿势位置设置为 position。position 是一个 Vector3，描述局部于 Skeleton3D 节点的位置。

void set_bone_pose_rotation(bone_idx: int, rotation: Quaternion) 🔗

将 bone_idx 处骨骼的姿势旋转设置为 rotation。rotation 是一个 Quaternion，描述该骨骼局部坐标空间中相对于任何父骨骼的旋转的旋转。

void set_bone_pose_scale(bone_idx: int, scale: Vector3) 🔗

将 bone_idx 处骨骼的姿势缩放设置为 scale。

void set_bone_rest(bone_idx: int, rest: Transform3D) 🔗

设置骨骼 bone_idx 的放松变换。

void unparent_bone_and_rest(bone_idx: int) 🔗

让位于 bone_idx 的骨骼不再有父级，并将其放松位置设置为之前父级放松时的位置。