文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载BoneConstraint3D是 Godot 4.6 中SkeletonModifier3D体系的核心基类节点用于在Skeleton3D骨骼系统上实现“一根骨骼跟随另一根骨骼/节点运动”的约束逻辑。本指南以官方类参考文档 class_boneconstraint3d.rst 为主体结合其基类与三个内置子类的源码文档系统讲解双骨骼关联的 API 设计、多设置setting列表机制、参考类型语义并给出可直接运行的 GDScript 实战代码。读完本文你将掌握如何为角色骨骼添加 Aim、CopyTransform、ConvertTransform 三类程序化约束并理解如何在编辑器与脚本中正确配置它们。BoneConstraint3D 在骨架系统中的地位BoneConstraint3D的继承关系为BoneConstraint3D SkeletonModifier3D Node3D Node Object即它首先是一个Node3D节点通过其父级Skeleton3D获得目标骨架再作为SkeletonModifier3D在动画播放之后对骨骼姿态进行后处理。在 Godot 4.6 中官方将其定位为“通过关联两根骨骼来修改Skeleton3D骨骼的节点”是 class_aimmodifier3d.rstAimModifier3D、class_copytransformmodifier3d.rstCopyTransformModifier3D、class_converttransformmodifier3d.rstConvertTransformModifier3D三个内置修改器共同的基类。其工作方式概括为一句核心语义以set_apply_bone()指定的骨骼为被修改对象以get_reference_bone()/set_reference_node()指定的骨骼或节点为参考对象将参考对象的变换处理并应用到目标骨骼上。其中参考骨骼“只会被引用绝不会被本修改器修改”这一点保证了约束不会产生级联写入的副作用。与 SkeletonModifier3D 的执行时机作为SkeletonModifier3D的子类BoneConstraint3D继承了两个关键属性见 class_skeletonmodifier3d.rstactive默认true控制修改器是否参与处理置为false即可临时停用约束。influence默认1.0修改结果的整体权重由Skeleton3D负责混合blend。官方文档特别强调influence由Skeleton3D自动应用于修改器写入的所有骨骼姿态因此修改器内部只需输出 100% 的计算结果不要自行插值。此外如果场景中存在AnimationMixer修改一定发生在AnimationMixer播放流程之后保证约束结果是叠加在动画之上的最终姿态。修改完成后Skeleton3D会发出modification_processed信号若需要读取修改后的骨骼姿态应在该信号触发时通过Skeleton3D.get_bone_pose()或Skeleton3D.get_bone_global_pose()获取详见 class_skeletonmodifier3d.rst。多设置setting列表机制BoneConstraint3D最具特色的设计是一个节点可同时维护多个约束设置setting每个设置都是一条独立的“参考 → 应用”关联。官方文档明确说明本类大多数方法都接收一个index参数该参数指定返回第几个设置列表条目例如settings/index/amount。BoneConstraint3D提供了 16 个方法其中 8 个与设置数量管理直接相关方法说明set_setting_count(count)/get_setting_count()设置/获取修改器中的设置条目总数clear_setting()清空全部设置set_amount(index, amount)/get_amount(index)设置/获取第index条设置的应用强度浮点0.0–1.0 常用于渐进式约束set_apply_bone(index, bone)/get_apply_bone(index)按骨骼索引设置/获取被修改的骨骼set_apply_bone_name(index, bone_name)/get_apply_bone_name(index)按骨骼名称设置/获取被修改的骨骼set_reference_bone(index, bone)/get_reference_bone(index)按骨骼索引设置/获取参考骨骼只读引用set_reference_bone_name(index, bone_name)/get_reference_bone_name(index)按骨骼名称设置/获取参考骨骼只读引用set_reference_node(index, node)/get_reference_node(index)设置/获取参考NodePath参考目标为节点时使用set_reference_type(index, type)/get_reference_type(index)设置/获取参考目标类型ReferenceType枚举所有方法都来自 class_boneconstraint3d.rst 的方法表其中index均对应“第几条设置”。在编辑器检查器中这些字段会以settings/index/amount、settings/index/apply_bone等路径形式出现与脚本 API 一一对应。为什么需要多设置多设置机制让单个修改器节点能够同时承担多条约束。例如在角色身上可以第 0 条设置让左手腕跟随左前臂的旋转复制变换第 1 条设置让头部瞄准一个外部Node3D目标Aim 约束第 2 条设置将右手掌的旋转映射为左手腕的偏航角重映射约束。在同一个骨架处理周期内一次性完成避免挂载多个修改器节点带来的管理成本。ReferenceType 枚举骨骼空间 vs 模型空间BoneConstraint3D定义了一个唯一枚举ReferenceType用于声明参考目标所在的空间见 class_boneconstraint3d.rst 的 Enumerations 小节常量值语义REFERENCE_TYPE_BONE0参考目标是骨骼参考目标空间为局部空间local spaceREFERENCE_TYPE_NODE1参考目标是Node3D参考目标空间为模型空间model space即参考节点的坐标被当作直接放置在BoneConstraint3D所在Skeleton3D父节点之下这个枚举是理解约束行为的关键选择骨骼作参考时参与计算的是该骨骼相对于其父骨骼的局部变换选择节点作参考时则使用节点在骨架模型空间中的世界变换。这也解释了为什么 class_copytransformmodifier3d.rst 与 class_converttransformmodifier3d.rst 都注明“relative相对和 global全局选项仅在get_reference_type()为REFERENCE_TYPE_BONE时可用”——相对/全局基准只有在骨骼局部空间才有明确定义。继承体系三个内置约束修改器BoneConstraint3D被三个内置节点继承它们分别代表三种典型的“双骨骼关联”玩法全部复用本文前面介绍的设置列表与参考语义。AimModifier3D骨骼瞄准参考对象AimModifier3D 的功能是“旋转一根骨骼使其朝向参考骨骼/节点”是LookAtModifier3D的简化版——不支持角度限制与基于时间插值等高级选项。作为补偿它默认使用无欧拉角的平滑追踪实现见set_use_euler()描述除非你显式开启欧拉模式。其专属方法均带index参数包括set_forward_axis(index, axis)/get_forward_axis(index)指定骨骼的“前向轴”使用SkeletonModifier3D.BoneAxis枚举如BONE_AXIS_PLUS_Z决定骨骼哪一侧指向参考目标。set_use_euler(index, enabled)/is_using_euler(index)true时使用欧拉角提供旋转false时用“由前向轴向量与指向参考的向量生成的弧”计算旋转默认平滑模式。set_primary_rotation_axis(index, axis)/get_primary_rotation_axis(index)仅在欧拉模式生效时指定第一次旋转的轴Vector3.Axis。set_use_secondary_rotation(index, enabled)/is_using_secondary_rotation(index)仅在欧拉模式生效时启用第二根轴做双轴旋转。set_relative(index, enabled)/is_relative(index)true时旋转相对当前姿态叠加false时相对静止姿态rest即用 Aim 结果替换当前姿态。值得注意的是SkeletonModifier3D.BoneAxis枚举还包含BONE_DIRECTION_FROM_PARENT从父骨骼指向子骨骼的轴在需要让骨骼沿“父→子”方向对准目标时非常实用见 class_skeletonmodifier3d.rst 的BoneDirection枚举。CopyTransformModifier3D复制参考变换CopyTransformModifier3D 把参考骨骼/节点的变换位置、旋转、缩放复制到目标骨骼并允许通过掩码mask与选项进行精细控制。它定义了两种位掩码枚举TransformFlagTRANSFORM_FLAG_POSITION 1、TRANSFORM_FLAG_ROTATION 2、TRANSFORM_FLAG_SCALE 4、TRANSFORM_FLAG_ALL 7决定是否复制位置/旋转/缩放。AxisFlagAXIS_FLAG_X 1、AXIS_FLAG_Y 2、AXIS_FLAG_Z 4、AXIS_FLAG_ALL 7决定处理哪些坐标轴另有set_invert_flags()用于反转所选轴。该节点根据set_relative()与set_additive()的组合提供四种应用方式官方文档明确列出relativeadditive行为是是提取参考相对静止姿态rest的位姿加到目标骨骼当前姿态上是否提取参考相对静止姿态的位姿加到目标骨骼的静止姿态上否是提取参考的绝对位姿加到目标骨骼当前姿态上否否提取参考的绝对位姿替换目标骨骼当前姿态另有set_global()true时提取参考骨骼全局姿态并使目标骨骼全局姿态与之重合false时按局部姿态应用。文档同时给出了两个值得注意的边界情况若参考骨骼的父骨骼存在非均匀缩放参考骨骼在全局空间会被剪切shear而局部姿态无法携带剪切缩放可能不会按预期生效反转缩放时是“取倒数”如2.0变0.5而非取负值反转旋转则是翻转四元数元素且只反转单轴可能因四元数特性产生意外旋转。ConvertTransformModifier3D轴重映射转换ConvertTransformModifier3D 在复制的基础上增加了轴重映射能力它读取参考骨骼在reference_axis上的数值可通过reference_range_min/max限定范围经reference_transform_mode换算后输出到目标骨骼的apply_axis上同样可设定apply_range_min/max与apply_transform_mode实现“把一个关节的旋转/位移映射到另一个关节的另一根轴”的效果常用于动作重定向retargeting与机械联动。它与 CopyTransformModifier3D 拥有完全相同的四种 relative additive 应用组合并额外提醒受约束轴上若存在大于 180 度的旋转可能发生翻转flip。需要说明的是三个子类都暴露了setting_count属性默认0用于在编辑器检查器中直接调整设置数量这也是脚本调用set_setting_count()时实际写入的属性见 class_aimmodifier3d.rst、class_copytransformmodifier3d.rst、class_converttransformmodifier3d.rst。GDScript 实战为角色添加三类约束以下示例演示在脚本中驱动BoneConstraint3D及其子类。假设场景树为Player (Node3D) ├── Skeleton (Skeleton3D) │ └── BoneConstraint (BoneConstraint3D) # 必须直接挂在 Skeleton3D 下 └── AimTarget (Node3D) # 可选的外部参考节点基础配置双骨骼关联与强度extends Node3D onready var skeleton: Skeleton3D $Skeleton onready var constraint: BoneConstraint3D $Skeleton/BoneConstraint func setup_constraint() - void: # 单条设置即可满足大多数需求 constraint.set_setting_count(1) # 用骨骼名称指定右前臂为被修改骨骼右上臂为参考骨骼 constraint.set_apply_bone_name(0, right_forearm) constraint.set_reference_bone_name(0, right_upper_arm) # 参考目标为骨骼 → 局部空间参考目标为 Node3D → 模型空间 constraint.set_reference_type(0, BoneConstraint3D.REFERENCE_TYPE_BONE) # 应用强度0.0 完全不起作用1.0 完全生效中间值由 Skeleton3D 混合 constraint.set_amount(0, 1.0) # 或改用骨骼索引性能略优需确保索引有效 # constraint.set_apply_bone(0, skeleton.find_bone(right_forearm)) # constraint.set_reference_bone(0, skeleton.find_bone(right_upper_arm))Aim 约束头部追踪外部节点onready var aim: AimModifier3D $Skeleton/AimModifier func setup_aim() - void: aim.set_setting_count(1) # 被修改骨骼头骨参考目标场景中的 AimTarget 节点 aim.set_apply_bone_name(0, head) aim.set_reference_node(0, aim.get_path_to($AimTarget)) aim.set_reference_type(0, BoneConstraint3D.REFERENCE_TYPE_NODE) # 默认前向轴为 Z可按需调整例如 BONE_AXIS_PLUS_Y aim.set_forward_axis(0, SkeletonModifier3D.BONE_AXIS_PLUS_Z) # 平滑弧旋转无欧拉角避免万向节死锁保持默认 false 即可 aim.set_use_euler(0, false) # 相对当前姿态叠加保留动画中的基础旋转 aim.set_relative(0, true)CopyTransform 约束手套跟随手掌onready var copy: CopyTransformModifier3D $Skeleton/CopyTransformModifier func setup_copy() - void: copy.set_setting_count(1) copy.set_apply_bone_name(0, glove_l) copy.set_reference_bone_name(0, hand_l) copy.set_reference_type(0, BoneConstraint3D.REFERENCE_TYPE_BONE) # 只复制旋转与缩放位置由动画驱动 copy.set_copy_flags(0, CopyTransformModifier3D.TRANSFORM_FLAG_ROTATION | CopyTransformModifier3D.TRANSFORM_FLAG_SCALE) # 仅处理 X/Y 轴并反转 X 轴镜像手套 copy.set_axis_flags(0, CopyTransformModifier3D.AXIS_FLAG_X | CopyTransformModifier3D.AXIS_FLAG_Y) copy.set_axis_x_inverted(0, true) # 相对静止姿态 替换最常用的“整姿态复制” copy.set_relative(0, true) copy.set_additive(0, false)管理多个设置与整体开关func toggle_constraints(enabled: bool) - void: # active 继承自 SkeletonModifier3D直接控制整个修改器是否处理 constraint.active enabled aim.active enabled func query_settings() - void: # 多设置场景下遍历访问 var count: int copy.get_setting_count() for i in count: var apply: String copy.get_apply_bone_name(i) var ref_name: String copy.get_reference_bone_name(i) var amount: float copy.get_amount(i) print(Setting %d: %s - %s (amount%f) % [i, ref_name, apply, amount])读取约束处理结果由于修改发生在AnimationMixer之后若要在约束生效后再取骨骼姿态应监听基类信号func _ready() - void: skeleton.modification_processed.connect(_on_modification_processed) func _on_modification_processed() - void: var pose : skeleton.get_bone_global_pose( skeleton.find_bone(head) ) # pose 此时已包含 AimModifier3D 等修改器的计算结果使用注意事项与边界条件综合官方文档中的Note说明实践中需要注意以下几点节点挂载位置BoneConstraint3D及其子类必须作为Skeleton3D的子节点修改器通过父级Skeleton3D获取骨架见 class_skeletonmodifier3d.rst若没有父级Skeleton3Dget_skeleton()返回null。参考对象只读通过set_reference_bone()/set_reference_bone_name()/set_reference_node()指定的对象仅被读取不会被修改器改写。不要自行应用 influenceinfluence由Skeleton3D统一混合修改器内部应输出完整计算结果。reference_type 决定空间语义REFERENCE_TYPE_BONE使用局部空间REFERENCE_TYPE_NODE使用模型空间参考节点视作直接放在Skeleton3D之下相对/全局选项仅对骨骼参考有效见 class_copytransformmodifier3d.rst。数值边界ConvertTransformModifier3D 在受约束轴上超过 180 度旋转可能翻转CopyTransformModifier3D 的反转缩放是倒数而非取负非均匀缩放父骨骼可能造成剪切无法表达。index越界安全所有index参数对应settings/index/...条目使用前应通过set_setting_count()分配数量避免越界访问。与其他骨骼修改器的关系BoneConstraint3D只是 Godot 4.6 中十余个SkeletonModifier3D之一。同体系还包括SkeletonIK3D、CCDIK3D、FABRIK3D、PhysicalBoneSimulator3D、SpringBoneSimulator3D等完整清单见 class_skeletonmodifier3d.rst 的 Inherited By 列表。它们共享同一套“父级Skeleton3DAnimationMixer之后执行 influence统一混合”的处理框架区别仅在于求解算法。在 4.5 → 4.6 升级中部分修改器如SpringBoneSimulator3D的枚举类型被统一收敛到SkeletonModifier3D.BoneDirection与SkeletonModifier3D.RotationAxis如果你正从旧版本迁移可参考 tutorials/migrating/upgrading_to_godot_4.6.rst 的变更表。小结BoneConstraint3D以极简的 API 形态提供了强大的双骨骼约束抽象通过设置列表index支持单节点多约束通过ReferenceType区分骨骼局部空间与节点模型空间并以apply/reference一对概念统一了“谁被改、谁作参照”的语义。基于它派生的 AimModifier3D瞄准、CopyTransformModifier3D复制变换、ConvertTransformModifier3D轴重映射覆盖了角色动画、动作重定向与机械联动等常见场景且都能在Skeleton3D的统一influence混合机制下与动画无缝叠加。深入阅读 class_boneconstraint3d.rst 及三个子类文档即可掌握这套骨架程序化控制的完整能力。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 4 骨骼瞄准修改器 AimModifier3D 完全指南让骨骼平滑注视参考骨骼Godot 4 骨骼瞄准修改器 AimModifier3D 完全指南让骨骼平滑注视参考骨骼 AimModifier3D 是 Godot 4.7 引入的骨骼修改文档教程游戏开发Godot Engine3D骨骼约束IK与FK动画Godot Engine3D骨骼约束IK与FK动画 Godot Engine 作为一款功能丰富的跨平台2D和3D游戏引擎提供了强大的骨骼动画系统支持正向运游戏开发图形学跨平台Godot 骨骼空间修正器 BoneSpaceAdjuster3D 详解让皮肤缩放与子骨骼位置完美同步Godot 骨骼空间修正器 BoneSpaceAdjuster3D 详解让皮肤缩放与子骨骼位置完美同步 导读 BoneSpaceAdjuster3D 是 Go文档教程游戏开发上一篇LLaVA-OneVision-2数据集深度探索VideoCaption与Spatial数据应用详解下一篇SikuliX高级应用如何构建企业级UI自动化测试框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考