企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

导读

BoneSpaceAdjuster3D是 Godot 引擎中用于处理"骨骼皮肤缩放（skin scale）"与子骨骼关节位置同步的专用SkeletonModifier3D修正器：它接收一个缩放值，并将其转换为子骨骼的位置偏移。本文基于 Godot 官方文档仓库中该类的完整参考文档（classes/class_bonespaceadjuster3d.rst），系统讲解其继承关系、属性、全部方法、典型使用场景与底层原理，帮助你掌握"通过Skeleton3D.set_bone_skin_scale()调整骨骼视觉厚度而不破坏骨骼链关节位置"的完整实战方案。阅读完成后，你将能够在自己的角色骨骼系统中正确配置与驱动BoneSpaceAdjuster3D。

一、为什么需要 BoneSpaceAdjuster3D：皮肤缩放与骨骼位置的关系

在骨骼动画系统中，Skeleton3D的每一根骨头都定义了从父关节到子关节的变换关系。Godot 提供了一个特殊的缩放能力——皮肤缩放（skin scale）：

• Skeleton3D.set_bone_skin_scale(bone_idx, skin_scale)将指定骨骼的皮肤缩放设为skin_scale（Vector3），其官方说明明确指出："该缩放不会影响骨骼的子骨骼，它主要用于修改皮肤的可视厚度（visual thickness）"（见 classes/class_skeleton3d.rst 中set_bone_skin_scale方法描述）。
• 对应地，Skeleton3D.get_bone_skin_scale(bone_idx)返回指定骨骼的皮肤缩放值（见 classes/class_skeleton3d.rst 中get_bone_skin_scale方法描述）。

这里存在一个关键矛盾：皮肤被缩放（变粗或变细）后，骨骼本身既不被缩放也不会被重新定位，于是子骨骼的关节原点仍然停留在缩放前的坐标上。当你想用皮肤缩放"拉长"或"加粗"某段肢体，或者某根骨骼拥有多个子骨骼时，子骨骼的位置就会与变形后的皮肤脱节。BoneSpaceAdjuster3D正是为解决这一脱节而生的：它输入一个缩放值，并将其转换为子骨骼的位置（"Inputs a scale and converts it to the position of a child bone"）。

二、类层次与继承关系

BoneSpaceAdjuster3D的完整继承链为：

BoneSpaceAdjuster3D < SkeletonModifier3D < Node3D < Node < Object

它属于 Godot 4.3+ 引入的Skeleton Modifier（骨骼修正器）体系。其基类SkeletonModifier3D的职责是：通过父节点自动获取目标Skeleton3D；当场景中存在AnimationMixer时，修正总是在动画播放完成之后执行，因此可以用它实现自定义 IK 求解器、约束或骨骼物理（见 classes/class_skeletonmodifier3d.rst 的 Description）。

在同族修正器中，它拥有两个关键的内置属性（详见下文）：

• active（默认true）：控制修正器是否参与处理；
• influence（默认1.0）：控制修正的影响力，Skeleton3D会基于该值对修正结果做混合，因此修正器内部必须始终输出 100% 的结果、不自行插值。

从引擎的实现角度看，BoneSpaceAdjuster3D与BoneConstraint3D、BoneTwistDisperser3D、IKModifier3D、SpringBoneSimulator3D、RetargetModifier3D等十余个修正器共同继承自SkeletonModifier3D，是一套用于在动画播放后统一改写骨骼姿态的机制。

三、属性详解

BoneSpaceAdjuster3D只暴露两个属性，但它们决定了修正器"全自动处理"还是"按骨骼手动配置"两种工作模式。

3.1 setting_size（int）

The number of settings in the modifier.

即"修正器中设置项的数量"。每个设置项对应一根需要处理的骨骼，并通过索引index访问。当你通过set_bone()/set_bone_name()/set_bone_scale()等方法逐项配置骨骼时，setting_size会随之增长；使用clear_setting()清空后它归零。典型使用方式是用一个循环遍历0到setting_size - 1的所有索引。

3.2 use_bone_skin_scale_for_all_bones（bool，默认true）

Iftrue, this modifier processes all bones for whichSkeleton3D.get_bone_skin_scale()is notVector3(1, 1, 1). Iffalse, this modifier allows you to configure whether to process bone skin scaling individually in the settings.

这是整个类最核心的开关，对应 setterset_use_bone_skin_scale_for_all_bones()与查询方法are_all_bones_using_bone_skin_scale()：

• true（默认）：自动扫描整个骨架，凡是get_bone_skin_scale()返回值不等于Vector3(1, 1, 1)的骨骼都会被处理。Vector3(1, 1, 1)是"无缩放"的语义，因此默认情况下你只需要用set_bone_skin_scale()设置哪些骨骼需要皮肤缩放，修正器就会自动补齐这些骨骼的子骨骼位置，无需任何额外配置——这是最省事的接入方式。
• false：进入手动模式。修正器不再自动扫描，而是要求你通过设置项逐根指定骨骼及其缩放来源：对每个索引index，用set_bone()/set_bone_name()指定目标骨骼，再用set_use_bone_skin_scale(index, enabled)决定该骨骼是使用Skeleton3D的skin_scale属性（true）还是使用自定义缩放值（false，此时配合set_bone_scale()）。

属性速查表：

四、方法详解

该类共 9 个公开方法，全部围绕"按索引管理设置项"设计。所有方法中的index均指设置项索引（而非骨骼索引），取值范围为0 <= index < setting_size。

4.1 设置项的配置方法（写操作）

4.2 设置项的查询方法（读操作，均为 const）

4.3 典型调用流程

# 手动模式配置示例（use_bone_skin_scale_for_all_bones = false） var adjuster := BoneSpaceAdjuster3D.new() # 设置项 0：使用骨骼 3 的 skin_scale 属性 adjuster.set_bone(0, 3) adjuster.set_use_bone_skin_scale(0, true) # 设置项 1：对骨骼 5 手动指定一个非零缩放 adjuster.set_bone(0 + 1, 5) adjuster.set_use_bone_skin_scale(1, false) adjuster.set_bone_scale(1, Vector3(2.0, 2.0, 1.0)) # 读取回查 print(adjuster.setting_size) # 2 print(adjuster.get_bone(1)) # 5 print(adjuster.is_using_bone_skin_scale(1)) # false print(adjuster.get_bone_scale(1)) # (2, 2, 1)

五、实战场景与配置步骤

5.1 场景一：自动模式——最简单接入

当你只想"让某根骨骼变粗/变细，同时让它的子骨骼跟上"时，不需要写任何 GDScript 配置：

1. 在场景树中为Skeleton3D添加一个BoneSpaceAdjuster3D子节点（修正器通过父节点自动找到目标骨架）；
2. 保持use_bone_skin_scale_for_all_bones = true（默认值）；
3. 运行时对目标骨骼调用skeleton.set_bone_skin_scale(bone_idx, Vector3(1.5, 1.5, 1.5))；
4. 修正器自动扫描到该骨骼的get_bone_skin_scale()不为(1,1,1)，随即把它的子骨骼位置重新定位到缩放后的皮肤表面。

5.2 场景二：调整骨骼长度 / 多子骨骼骨骼

官方描述明确指出该修正器适用于两类特殊情形：

• 想用set_bone_skin_scale()调整骨骼长度（例如沿骨骼轴向拉伸一段肢体时）；
• 骨骼拥有多个子骨骼时（一个父骨骼分叉出多个子骨骼，皮肤缩放后每个子关节都必须重新定位）。

这两种情形下子骨骼的"跟随"不能靠Skeleton3D自身完成（因为皮肤缩放不作用于子骨骼），必须由BoneSpaceAdjuster3D把缩放换算为子骨骼的位置偏移。

5.3 场景三：手动逐根控制

当骨架复杂、只想处理其中少数骨骼、或想用自定义缩放值（而非skin_scale属性）时，将use_bone_skin_scale_for_all_bones设为false，按第四节流程逐项配置即可。

六、底层机制与配套知识点

6.1 修正器处理时机

作为SkeletonModifier3D的子类，BoneSpaceAdjuster3D的改写发生在AnimationMixer播放完成之后、每帧骨骼姿态输出之前。这意味着它的修正结果会覆盖动画/IK 设置的骨骼姿态，且会被基类自动混合influence；因此不要在修正逻辑内部再手动应用influence插值（见 classes/class_skeletonmodifier3d.rst 中_process_modification_with_delta的说明）。

6.2 与 RetargetModifier3D 的配合

若你的角色使用骨骼重定向（retarget），需注意RetargetModifier3D的copy_bone_skin_scale属性（默认true）会把源骨架的get_bone_skin_scale()复制到子骨架的映射骨骼上（见 classes/class_retargetmodifier3d.rst）。这意味着：

• 重定向场景下皮肤缩放会被自动传递，子骨架上的BoneSpaceAdjuster3D也会随之生效；
• 若你想在子骨架上手动用set_bone_skin_scale()覆盖，必须先把copy_bone_skin_scale设为false，否则即使源骨架未设置皮肤缩放，子骨架映射骨骼也会被写入(1,1,1)而覆盖你的手动值。

6.3 已知限制

官方文档同时给出两条重要提示（见 classes/class_skeleton3d.rst 中set_bone_skin_scale的描述）：

• 皮肤缩放可能会破坏部分依赖骨骼长度的 SkeletonModifier 类（如 SpringBoneSimulator、IKModifier3D）的 gizmo 显示；
• 皮肤缩放本身不改变骨骼姿态，因此BoneSpaceAdjuster3D只是"同步关节位置"，并不会让骨骼旋转/平移本身产生缩放。

七、总结

BoneSpaceAdjuster3D是 Godot 骨骼系统中"皮肤缩放后关节同步"问题的标准答案：

• 自动模式（默认）下零配置生效，只需配合Skeleton3D.set_bone_skin_scale()使用；
• 手动模式下通过set_bone/set_bone_name/set_bone_scale/set_use_bone_skin_scale/clear_setting五组读写方法实现逐骨骼精细控制；
• 与RetargetModifier3D.copy_bone_skin_scale联动时注意覆盖语义；
• 使用set_bone_scale()手动指定缩放时务必保持非零值。

结合官方参考文档 classes/class_bonespaceadjuster3d.rst、基类 classes/class_skeletonmodifier3d.rst 以及配套的 classes/class_skeleton3d.rst、classes/class_retargetmodifier3d.rst，你可以完整掌握从"皮肤缩放"到"子骨骼跟随"的整条链路，为角色肢体增粗、骨骼拉伸等定制化骨骼效果提供稳定可靠的技术支撑。

• 文档
• 教程
• 游戏开发