Godot Skeleton2D 深度解析：2D 骨骼动画的骨骼层级、位姿控制与 IK 修改体系

• 文档
• 教程
• 游戏开发

本文基于 godot-docs 仓库中的Skeleton2D类参考文档（classes/class_skeleton2d.rst），完整讲解该类的继承关系、全部公开方法与信号，以及它与SkeletonModificationStack2D逆运动学修改体系的协作方式，并结合仓库内的 2D 骨骼动画教程（tutorials/animation/2d_skeletons.rst）和相关类文档，说明在 Godot 2D 项目中如何搭建骨骼、控制骨骼位姿并接入 IK。读完后你将能够独立完成"建骨 → 设定 rest pose → 绑定多边形 → 程序化驱动骨骼 → 运行 IK"的完整工作流。

一、Skeleton2D 是什么：类定位与继承关系

类参考文档开头声明该文件由 Godot 引擎源码自动生成为准（生成器为引擎仓库的make_rst.py，XML 源为Skeleton2D.xml），因此其中列出的 API 是与引擎实现严格对应的权威参考。

按类参考文档，Skeleton2D的继承链为：

Object < Node < CanvasItem < Node2D < Skeleton2D

参考文档中的一句话定位是：它是Bone2D层级（a hierarchy of Bone2D）的父节点，用于创建 2D 骨骼动画（2D skeletal animation）。其 Description 部分给出了两个核心职责：

1. 父化骨骼层级：Skeleton2D 父化一个Bone2D节点层级；
2. 持有 rest pose 并提供统一访问入口：它持有每个Bone2Drest pose（静止姿态/参考姿态）的引用，并作为访问其骨骼的单一入口（a single point of access to its bones）。

所谓 rest pose，是骨骼的默认姿态：在动画中可以随时重置回该姿态。每个Bone2D自身带有rest属性（类型为Transform2D，默认值Transform2D(0, 0, 0, 0, 0, 0)），且这些 rest pose 是相对于父骨骼的；Bone2D.apply_rest()会把骨骼重置到 rest pose，等价于把Node2D.transform设回rest。编辑器中可以通过菜单一次性写入整副骨骼的 rest pose，而从代码侧则需要遍历骨骼逐一设置（见第八节）。

下图来自仓库 2D 骨骼教程，展示了一个建在Skeleton2D之下的完整Bone2D层级——这正是get_bone()/get_bone_count()所操作的节点结构：

另外，2D 视口工具栏提供Skeleton Options菜单用于操作 Skeleton2D 与 Bone2D：其中Show Bones可切换选中节点骨骼的可见性，Make Bone2D Node(s) from Node(s)可将选中的普通节点转换为Bone2D，详见 Introduction to 2D 教程。

二、完整方法参考

Skeleton2D共暴露 8 个公开方法，完整签名与功能如下（与 类参考文档 的方法表一一对应）：

三、骨骼访问：get_bone() 与 get_bone_count()

这两个方法构成脚本侧操作骨骼的基础。

• get_bone_count()返回 Skeleton2D 父化的节点层级中Bone2D的总数；
• get_bone(idx)返回节点层级中由idx标识的Bone2D。

关键点是索引规则：类参考文档明确说明，骨骼的编号方式是"从顶层向底层遍历节点层级（descending the node hierarchy from top to bottom），在每个分支上先加入该分支的所有子节点，再移动到下一个兄弟节点"。换言之，这是前序深度优先顺序——先父骨、再其全部子孙、最后处理兄弟分支。

var skeleton := $Character/Skeleton2D print("bone count: ", skeleton.get_bone_count()) for i in skeleton.get_bone_count(): var bone: Bone2D = skeleton.get_bone(i) # Bone2D 侧的 get_index_in_skeleton() 应与这里的 i 一致 print(i, " -> ", bone.name, ", index in skeleton: ", bone.get_index_in_skeleton())

注意返回的是节点层级中的Bone2D节点对象，因此可以顺势使用Bone2D的全部 API，例如set_bone_angle(angle)、get_bone_angle()、set_length(length)、set_autocalculate_length_and_angle(auto_calculate)等；其中get_bone_angle()返回的是 gizmo 显示的骨骼角度（不受节点transform影响），与节点自身rotation是两回事。Bone2D的完整 API 见 Bone2D 类参考。

四、骨骼位姿覆写：set_bone_local_pose_override() 与 get_bone_local_pose_override()

这对方法用于在动画之外临时/持久地覆写某根骨骼的局部位姿（例如程序化驱动、混合外部姿态数据、调试时强制摆位）。

set_bone_local_pose_override(bone_idx, override_pose, strength, persistent)各参数含义：

• bone_idx：骨骼索引，规则同第三节的前序遍历顺序；
• override_pose：要施加的位姿变换。类参考文档特别加粗提示：该变换必须是相对于bone_idx处Bone2D节点的局部变换（local transform），传入全局姿态会导致错误结果；
• strength：施加位姿时使用的插值强度（interpolation strength）；
• persistent：决定该位姿是否保持——为true时覆写效果保留，否则是临时的。

get_bone_local_pose_override(bone_idx)则读回该骨骼当前的局部位姿覆写变换。

# 让第 3 号骨骼在其局部坐标系中旋转 90 度，完全插值、非持久 var local_rot := Transform2D(PI / 2) skeleton.set_bone_local_pose_override(3, local_rot, 1.0, false) # 需要时读回当前覆写位姿 var current_override: Transform2D = skeleton.get_bone_local_pose_override(3)

由于覆写的是"局部变换"，它与Bone2D的 rest pose 语义一致——Bone2D.get_skeleton_rest()返回的正是"无父节点时返回 rest 变换、有父节点时返回相对父骨的 rest pose"，两者都以骨骼局部坐标系为参照。

五、get_skeleton()：渲染层的 RID

get_skeleton()返回一个RID，即该 Skeleton2D 实例在渲染层的资源标识。RID是 Godot 渲染体系的通用句柄类型；从类参考文档的语义看，该方法是骨骼渲染层实例句柄的对外出口，供需要在自定义绘制/gizmo 等场景下引用骨骼渲染资源的扩展开发使用。日常 2D 动画开发通常无需直接接触它。

六、IK 修改体系：SkeletonModificationStack2D 与 execute_modifications()

类参考文档的 Description 指出：要为某个 Skeleton2D 配置不同类型的逆运动学（IK），应创建一个SkeletonModificationStack2D；IK 通过增加modification_count并创建相应数量的修改（modification）来应用。这是execute_modifications()、set_modification_stack()、get_modification_stack()三个方法所围绕的核心机制。

6.1 修改栈资源 SkeletonModificationStack2D

SkeletonModificationStack2D继承自Resource，是"持有SkeletonModification2D栈"的资源。类参考文档（classes/class_skeletonmodificationstack2d.rst）说明：修改的执行顺序对全身 IK 尤其重要——例如人形骨骼上应先执行脊椎的修改，再执行手臂的修改，才能得到正确结果。

其属性及默认值如下：

关键方法：

• add_modification(modification)/delete_modification(mod_idx)/set_modification(mod_idx, modification)：增删改栈内修改；
• get_modification(mod_idx)：按索引取回修改；
• enable_all_modifications(enabled)：批量启用/禁用栈内全部修改；
• execute(delta, execution_mode)：从索引0到modification_count顺序执行所有与传入execution_mode相同的修改。文档特别提示顺序依赖："例如脊椎上的修改应先于手臂上的修改执行"；
• get_skeleton()：返回该栈绑定的Skeleton2D节点；
• setup()：初始化栈使其可以执行。文档明确：此函数应由Skeleton2D调用，除非你清楚自己在做什么，否则不要手动调用。

6.2 修改基类 SkeletonModification2D

每个修改都是继承自Resource的SkeletonModification2D（类参考）。类参考文档将其定位为一个可自由扩展的接口："让操作Skeleton2D中Bone2D的代码可以混合搭配，从而构建复杂的交互"，并以此提供"灵活而强大的 IK 方案"。

注意：该类文档标注了Experimental（"该类在未来版本中可能被修改或移除"），其全部内置子类与SkeletonModificationStack2D同样带此标注。在生产项目中使用这套 IK 体系时，需要锁定 Godot 版本并注意跨版本兼容性。

基类属性：

虚方法（供子类重写）：

• _setup_modification(modification_stack)：初始化钩子，在修改被设置（setup）时调用；
• _execute(delta)：真正执行修改逻辑的地方；
• _draw_editor_gizmo()：仅在编辑器内调用，用于绘制修改专属 gizmo。文档提示：由于SkeletonModification2D资源自身无法绘制，需要通过get_modification_stack()拿到Skeleton2D并使用它的绘制函数。

此外基类还提供了实用方法clamp_angle(angle, min, max, invert)：把角度钳制到min/max区间；invert为true时反向钳制（即钳到区间之外）。

内置修改子类（类参考文档 "Inherited By" 列表）：

6.3 完整代码示例：为两条臂骨挂接 TwoBoneIK

以SkeletonModification2DTwoBoneIK为例，其关键属性为：target_nodepath（目标节点路径，默认NodePath("")）、flip_bend_direction（收缩时向外而非向内弯曲，默认false）、target_minimum_distance/target_maximum_distance（目标距离钳制，默认0.0表示不做距离约束，超出上限时按上限距离求解）。关节骨骼可用set_joint_one_bone_idx(bone_idx)/set_joint_two_bone_idx(bone_idx)按索引指定，也可用对应的..._bone2d_node(NodePath)版本按节点路径指定：

extends Node2D var skeleton: Skeleton2D func _ready() -> void: skeleton = $Character/Skeleton2D # 1. 创建修改栈并挂接到 Skeleton2D var stack := SkeletonModificationStack2D.new() skeleton.set_modification_stack(stack) stack.modification_count = 1 # 2. 创建 TwoBoneIK：上臂 + 前臂两根骨骼 var arm_ik := SkeletonModification2DTwoBoneIK.new() arm_ik.set_joint_one_bone_idx(1) # 上臂（骨骼索引见前序遍历规则） arm_ik.set_joint_two_bone_idx(2) # 前臂 arm_ik.target_nodepath = NodePath("../HandTarget") arm_ik.flip_bend_direction = true # 手肘朝外弯曲 arm_ik.target_maximum_distance = 240.0 # 目标过远时按上限求解，防止"硬伸" # 3. 加入栈并启用（栈 enabled 默认为 false，修改 enabled 默认为 true） stack.add_modification(arm_ik) stack.enable_all_modifications(true)

挂接完成后，修改栈的执行"由Skeleton2D节点自动处理"（enabled属性说明中的原话）。而类参考文档中Skeleton2D自身暴露的execute_modifications(delta, execution_mode)——"执行SkeletonModificationStack2D上的全部修改，如果 Skeleton2D 已分配了一个"——则用于你希望主动、按帧外时机（例如在同一帧内特定逻辑之后立即生效）驱动修改的场景；其execution_mode参数与各修改的execution_mode属性配合，决定本次执行只作用于匹配模式的修改，从而把不同阶段的修改（如先脊椎后手臂）分阶段触发。

任何修改都可以通过get_modification_stack()取回栈资源后，用stack.get_modification(i)继续调整其参数，无需重新创建。

七、信号：bone_setup_changed

Skeleton2D只定义了一个信号：

• bone_setup_changed()：当挂接到该骨骼的Bone2D配置（setup）发生变化时发出。文档明确说明"这主要供骨骼内部使用"。对应用开发者而言，它的价值在于：当你开发编辑器插件、或需要在骨骼结构变化（如增删骨骼、重写 rest pose）后同步更新自己的状态时，可以连接此信号作为变更通知。

八、编辑器工作流：从零搭建一副 2D 骨骼

Skeleton2D类参考的 Tutorials 一节直接链接到 2D 骨骼动画教程。该教程的完整流程与本文 API 的对应关系如下（教程素材为教程目录下的gBot_pieces.png切图与gBot_complete.png参考图）：

1. 准备切块：为每个身体部件创建一个Polygon2D，在 UV 编辑器的 Points 模式中沿部件描多边形，再通过Edit > Copy Polygon to UV更新 UV，重复直至覆盖整个图集。
2. 创建 Skeleton2D：在角色根节点（动画角色通常建议CharacterBody2D）下创建Skeleton2D子节点，作为骨骼的基座。
3. 搭建 Bone2D 层级：在 Skeleton2D 下逐级创建Bone2D并命名，通常从髋部开始；末端（tip）骨骼较短且默认指向右侧，可在检查器中调整其长度，一般只有末端骨骼才需要关心长度与特定旋转。
4. 设置 rest pose：在场景树中选中骨骼节点，点击工具栏的Skeleton2D按钮，从下拉菜单选择Overwrite Rest Pose，骨骼上的缺失 rest pose 警告即消失。如果之后增删骨骼，需要重新设置 rest pose。若从代码侧完成，则需遍历骨骼逐一设置各自的 rest（编辑器中这是一步菜单操作，代码中无等价的一步入口）。

5. 绑定多边形：选中各Polygon2D，把骨骼节点赋给其skeleton属性。该属性是NodePath（默认NodePath("")），类参考说明："若为空或无效，则不会使用骨骼变形"（见 Polygon2D 类参考）。
6. 同步骨骼列表并绘制权重：在 UV 编辑器的Bones区块点击Sync Bones to Polygon，把骨骼列表一次性同步进多边形（增删/重命名骨骼后需重新同步），然后选中骨骼逐点绘制权重：白色为完全权重、黑色不受该骨骼影响；同一点被多根骨骼涂白时，影响会在骨骼间分摊。
7. 内部顶点：Godot 绘制多边形时会连接点并生成内部三角形，弯折表现可能不符合预期。解决方式是在预期弯曲区域添加内部顶点，并在Polygon区块重画更精细的轮廓；新增的内部顶点同样需要绘制权重。
8. 动画骨骼而非多边形：权重绘制完成后，只需在动画中关键帧Bone2D节点（而非多边形），多边形即随之弯折变形。

九、常见陷阱与注意事项

• 骨骼索引不是"创建顺序"，而是节点层级的前序遍历顺序；脚本中务必用get_bone(idx)/Bone2D.get_index_in_skeleton()核对，否则 IK 关节与位姿覆写会作用到错误的骨骼上。
• override_pose必须是局部变换（相对该Bone2D），这是类参考文档专门加粗提示的约束。
• 增删骨骼后必须重写 rest pose，否则警告不会消失，且动画参考姿态会错。
• 修改栈的enabled默认为false（每个修改的enabled默认true）：add_modification()之后还需enable_all_modifications(true)或等价操作，修改才会真正执行。
• 执行顺序有讲究：全身 IK 中应先执行躯干类修改再执行四肢类修改，SkeletonModificationStack2D按索引0起顺序执行，添加顺序即执行顺序。
• 实验性 API：SkeletonModification2D家族与SkeletonModificationStack2D均被标记为 Experimental（未来版本可能修改或移除），升级 Godot 版本时需要回归验证。
• Polygon2D.skeleton不赋值为NodePath时骨骼变形完全不生效，这是"骨骼动了、贴图不动"这类问题最常见的成因。

十、相关文档索引

• Skeleton2D 类参考（本文核心文档）
• Bone2D 类参考：rest pose、apply_rest()、骨骼角度/长度等
• SkeletonModification2D 类参考：修改基类与虚方法约定
• SkeletonModificationStack2D 类参考：修改栈属性与执行语义
• SkeletonModification2DTwoBoneIK 类参考：TwoBoneIK 参数
• Polygon2D 类参考：skeleton绑定属性与 UV 骨骼权重
• 2D 骨骼动画教程：完整编辑器操作与素材
• 2D 开发入门教程：视口工具栏 Skeleton Options 菜单

• 文档
• 教程
• 游戏开发