★ FEATURED ARTICLE 文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载本文基于 godot-docs 仓库中的Skeleton2D类参考文档classes/class_skeleton2d.rst完整讲解该类的继承关系、全部公开方法与信号以及它与SkeletonModificationStack2D逆运动学修改体系的协作方式并结合仓库内的 2D 骨骼动画教程tutorials/animation/2d_skeletons.rst和相关类文档说明在 Godot 2D 项目中如何搭建骨骼、控制骨骼位姿并接入 IK。读完后你将能够独立完成建骨 → 设定 rest pose → 绑定多边形 → 程序化驱动骨骼 → 运行 IK的完整工作流。一、Skeleton2D 是什么类定位与继承关系类参考文档开头声明该文件由 Godot 引擎源码自动生成为准生成器为引擎仓库的make_rst.pyXML 源为Skeleton2D.xml因此其中列出的 API 是与引擎实现严格对应的权威参考。按类参考文档Skeleton2D的继承链为Object Node CanvasItem Node2D Skeleton2D参考文档中的一句话定位是它是Bone2D层级a hierarchy of Bone2D的父节点用于创建 2D 骨骼动画2D skeletal animation。其 Description 部分给出了两个核心职责父化骨骼层级Skeleton2D 父化一个Bone2D节点层级持有 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 个公开方法完整签名与功能如下与 类参考文档 的方法表一一对应返回类型方法签名功能voidexecute_modifications(delta: float, execution_mode: int)执行挂在SkeletonModificationStack2D上的全部修改如果已分配Bone2Dget_bone(idx: int)按骨骼索引返回对应的Bone2Dintget_bone_count()(const)返回 Skeleton2D 下属Bone2D节点的数量Transform2Dget_bone_local_pose_override(bone_idx: int)返回指定骨骼的局部位姿覆写变换SkeletonModificationStack2Dget_modification_stack()(const)返回当前挂接的修改栈若存在RIDget_skeleton()(const)返回 Skeleton2D 实例的RIDvoidset_bone_local_pose_override(bone_idx: int, override_pose: Transform2D, strength: float, persistent: bool)为指定骨骼设置局部位姿覆写voidset_modification_stack(modification_stack: SkeletonModificationStack2D)为当前骨骼设置修改栈三、骨骼访问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 strengthpersistent决定该位姿是否保持——为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()渲染层的 RIDget_skeleton()返回一个RID即该 Skeleton2D 实例在渲染层的资源标识。RID是 Godot 渲染体系的通用句柄类型从类参考文档的语义看该方法是骨骼渲染层实例句柄的对外出口供需要在自定义绘制/gizmo 等场景下引用骨骼渲染资源的扩展开发使用。日常 2D 动画开发通常无需直接接触它。六、IK 修改体系SkeletonModificationStack2D 与 execute_modifications()类参考文档的 Description 指出要为某个 Skeleton2D 配置不同类型的逆运动学IK应创建一个SkeletonModificationStack2DIK 通过增加modification_count并创建相应数量的修改modification来应用。这是execute_modifications()、set_modification_stack()、get_modification_stack()三个方法所围绕的核心机制。6.1 修改栈资源 SkeletonModificationStack2DSkeletonModificationStack2D继承自Resource是持有SkeletonModification2D栈的资源。类参考文档classes/class_skeletonmodificationstack2d.rst说明修改的执行顺序对全身 IK 尤其重要——例如人形骨骼上应先执行脊椎的修改再执行手臂的修改才能得到正确结果。其属性及默认值如下属性默认值说明enabledfalse为true时栈中的修改会被调用这一执行由Skeleton2D节点自动处理modification_count0栈中修改的数量strength1.0修改的整体插值强度0表示完全不应用0.5表示半量应用1表示完全应用并覆写Bone2D的姿态关键方法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 版本并注意跨版本兼容性。基类属性属性默认值说明enabledtrue为true时该修改的_execute()会被SkeletonModificationStack2D调用execution_mode0告诉修改栈何时执行该修改部分修改只在特定执行模式下可用其某些设置虚方法供子类重写_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 列表子类用途概要SkeletonModification2DTwoBoneIK基于余弦定律让两根骨骼如手臂上臂前臂弯折到达目标点比 FABRIK 更轻量、结果自然SkeletonModification2DFABRIK基于 FABRIK 算法的链式 IKSkeletonModification2DCCDIK基于 CCD 算法的链式 IKSkeletonModification2DLookAt让骨骼朝向目标SkeletonModification2DJiggle惯性摆动效果SkeletonModification2DPhysicalBones物理骨骼模拟SkeletonModification2DStackHolder持有并代理另一个修改栈用于嵌套组织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_changedSkeleton2D只定义了一个信号bone_setup_changed()当挂接到该骨骼的Bone2D配置setup发生变化时发出。文档明确说明这主要供骨骼内部使用。对应用开发者而言它的价值在于当你开发编辑器插件、或需要在骨骼结构变化如增删骨骼、重写 rest pose后同步更新自己的状态时可以连接此信号作为变更通知。八、编辑器工作流从零搭建一副 2D 骨骼Skeleton2D类参考的 Tutorials 一节直接链接到 2D 骨骼动画教程。该教程的完整流程与本文 API 的对应关系如下教程素材为教程目录下的gBot_pieces.png切图与gBot_complete.png参考图准备切块为每个身体部件创建一个Polygon2D在 UV 编辑器的 Points 模式中沿部件描多边形再通过Edit Copy Polygon to UV更新 UV重复直至覆盖整个图集。创建 Skeleton2D在角色根节点动画角色通常建议CharacterBody2D下创建Skeleton2D子节点作为骨骼的基座。搭建 Bone2D 层级在 Skeleton2D 下逐级创建Bone2D并命名通常从髋部开始末端tip骨骼较短且默认指向右侧可在检查器中调整其长度一般只有末端骨骼才需要关心长度与特定旋转。设置 rest pose在场景树中选中骨骼节点点击工具栏的Skeleton2D按钮从下拉菜单选择Overwrite Rest Pose骨骼上的缺失 rest pose 警告即消失。如果之后增删骨骼需要重新设置 rest pose。若从代码侧完成则需遍历骨骼逐一设置各自的 rest编辑器中这是一步菜单操作代码中无等价的一步入口。绑定多边形选中各Polygon2D把骨骼节点赋给其skeleton属性。该属性是NodePath默认NodePath()类参考说明若为空或无效则不会使用骨骼变形见 Polygon2D 类参考。同步骨骼列表并绘制权重在 UV 编辑器的Bones区块点击Sync Bones to Polygon把骨骼列表一次性同步进多边形增删/重命名骨骼后需重新同步然后选中骨骼逐点绘制权重白色为完全权重、黑色不受该骨骼影响同一点被多根骨骼涂白时影响会在骨骼间分摊。内部顶点Godot 绘制多边形时会连接点并生成内部三角形弯折表现可能不符合预期。解决方式是在预期弯曲区域添加内部顶点并在Polygon区块重画更精细的轮廓新增的内部顶点同样需要绘制权重。动画骨骼而非多边形权重绘制完成后只需在动画中关键帧Bone2D节点而非多边形多边形即随之弯折变形。九、常见陷阱与注意事项骨骼索引不是创建顺序而是节点层级的前序遍历顺序脚本中务必用get_bone(idx)/Bone2D.get_index_in_skeleton()核对否则 IK 关节与位姿覆写会作用到错误的骨骼上。override_pose必须是局部变换相对该Bone2D这是类参考文档专门加粗提示的约束。增删骨骼后必须重写 rest pose否则警告不会消失且动画参考姿态会错。修改栈的enabled默认为false每个修改的enabled默认trueadd_modification()之后还需enable_all_modifications(true)或等价操作修改才会真正执行。执行顺序有讲究全身 IK 中应先执行躯干类修改再执行四肢类修改SkeletonModificationStack2D按索引0起顺序执行添加顺序即执行顺序。实验性 APISkeletonModification2D家族与SkeletonModificationStack2D均被标记为 Experimental未来版本可能修改或移除升级 Godot 版本时需要回归验证。Polygon2D.skeleton不赋值为NodePath时骨骼变形完全不生效这是骨骼动了、贴图不动这类问题最常见的成因。十、相关文档索引Skeleton2D 类参考本文核心文档Bone2D 类参考rest pose、apply_rest()、骨骼角度/长度等SkeletonModification2D 类参考修改基类与虚方法约定SkeletonModificationStack2D 类参考修改栈属性与执行语义SkeletonModification2DTwoBoneIK 类参考TwoBoneIK 参数Polygon2D 类参考skeleton绑定属性与 UV 骨骼权重2D 骨骼动画教程完整编辑器操作与素材2D 开发入门教程视口工具栏 Skeleton Options 菜单赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐FlashKDA精度对比fla_chunk_kda官方对比图里的输入敏感性全解读FlashKDA精度对比fla_chunk_kda官方对比图里的输入敏感性全解读 FlashKDA 是一个基于 CUTLASS 构建的高性能 Kimi Del人工智能大模型算子库高性能计算Godot 2D 骨骼动画实战用 Skeleton2D 打造可操控的绑定角色godot-demo-projects Skeleton2D Demo 全解析Godot 2D 骨骼动画实战用 Skeleton2D 打造可操控的绑定角色godot demo projects Skeleton2D Demo 全解析示例工程Godot Engine3D骨骼约束IK与FK动画Godot Engine3D骨骼约束IK与FK动画 Godot Engine 作为一款功能丰富的跨平台2D和3D游戏引擎提供了强大的骨骼动画系统支持正向运游戏开发图形学跨平台上一篇File Converter 配色体系解析从 Colors.md 到 WPF 主题实现的完整指南下一篇ModOrganizer2终极指南轻松管理游戏模组的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
