文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载SpringBoneCollisionCapsule3D 是 Godot 引擎骨骼弹簧模拟体系中用于约束骨骼链摆动的胶囊形碰撞体常配合 SpringBoneSimulator3D 用于角色头发、衣摆、尾巴等部位的惯性摆动与碰撞避让。读完本文你将掌握该类的全部属性语义、尺寸约束规则、与骨骼及模拟器的协作方式并能独立搭建一套可运行的弹簧骨骼碰撞场景。类的定位与继承关系根据 class_springbonecollisioncapsule3d.rst 的定义SpringBoneCollisionCapsule3D 的继承链为SpringBoneCollisionCapsule3D SpringBoneCollision3D Node3D Node Object它本质上是一个Node3D 场景节点描述的是一个与 SpringBoneSimulator3D 交互的胶囊形碰撞体。在 Godot 4.4 起引入的弹簧骨骼系统中碰撞体并不依赖物理引擎PhysicsServer3D而是作为自洽碰撞体self-standing collision直接参与骨骼模拟的数值修正。同族碰撞体还包括SpringBoneCollisionSphere3D球形碰撞体属性为radius与insideSpringBoneCollisionPlane3D无限大 XZ 平面碰撞体法线方向为 YSpringBoneCollision3D上述三种碰撞体的抽象基类承载与骨骼绑定的通用属性。属性总览SpringBoneCollisionCapsule3D 一共暴露四个属性其类型、默认值与说明如下表属性类型默认值说明heightfloat0.5胶囊的完整高度含两端的半球insideboolfalse为true时碰撞体将关节困住在内部mid_heightfloat由height推导除去半球后的圆柱段高度即两端半球球心之间的距离radiusfloat0.1胶囊的半径每个属性都配套了标准的 setter / getter 方法对例如height对应set_height(value)与get_height()inside对应set_inside(value)与is_inside()radius对应set_radius(value)与get_radius()。可以在运行时通过脚本读写这些属性从而动态调整碰撞范围。胶囊几何结构与两个高度属性的关系胶囊体可以理解为一个圆柱 两个半球。文档明确给出了height与mid_height的定义差异height完整高度包含两端半球在内的总长度即胶囊体在纵向上的最大尺寸mid_height中段高度仅指中央圆柱部分的长度几何上等于两个半球球心之间的距离是height的包装属性wrapper。二者满足简单的换算关系height mid_height 2 * radius mid_height height - 2 * radius文档指出mid_height本质上是height的包装器修改其中一个另一个会随之联动。实践中可以直接调height来整体缩放胶囊的纵向范围也可以调mid_height只改中间圆柱段的长度而保持半球尺寸不变。尺寸约束退化为球体的边界条件这是使用胶囊碰撞体时最容易踩坑的地方文档以两条对称的 Note 给出了硬性约束height必须至少是radius的两倍height 2 * radius否则胶囊会退化为球体radius不能大于height的一半radius height / 2否则同样退化为球体。如果属性值越界Godot 不会报错而是自动将属性调整到合法值。也就是说以下三种设置都会触发自动修正非法输入示例结果height 0.3radius 0.2height被抬升到0.4以维持height 2 * radiusradius 0.6height 0.5radius被压回0.25维持2 * radius heightheight与radius同步缩小到越界区间自动修正为合法的最小胶囊理解这一点对调试很有价值当场景中看到胶囊碰撞体表现成球体时先检查这两个属性的比值而不是怀疑模拟逻辑出了问题。inside 属性外壁推挤与内部困锁两种模式inside是一个布尔开关控制碰撞体的作用方向inside false默认碰撞体像一个外壁弹簧骨骼的关节在碰撞体表面外侧滑动关节无法穿透碰撞体进入内部inside true碰撞体像一个笼子关节被困锁在碰撞体内部无法逸出到外部。这两种模式在玩法上各有用途外壁模式适合让头发、衣摆搭在肩膀或躯干上并沿表面滑动内部模式则适合把关节约束在某个封闭区域内例如限制辫子或尾巴的活动范围。Sphere3D 与 Capsule3D 都支持inside开关而 Plane3D 因为是无限平面不提供此属性。与 SpringBoneSimulator3D 的协作方式SpringBoneSimulator3D 是应用于骨骼链的 SkeletonModifier3D用于给头发、布料、尾巴等部位施加惯性摆动其文档明确说明物理模拟所需的碰撞体可以由SpringBoneSimulator3D 的子节点提供它们是独立于 PhysicsServer3D 的自洽碰撞体。SpringBoneCollisionCapsule3D 要生效必须满足以下条件必须是 SpringBoneSimulator3D 的子节点。基类文档明确如果它不是 SpringBoneSimulator3D 的子节点则没有任何效果。必须被列入模拟器的碰撞列表。碰撞与滑动的计算发生在模拟器的修改流程modification process中按碰撞列表的顺序执行。碰撞列表的注册有两种模式由set_enable_all_child_collisions(index, enabled)控制见 class_springbonesimulator3d.rstenabled true模拟器自动把所有子级 SpringBoneCollision3D 节点加入碰撞列表此时碰撞顺序与 SceneTree 中的顺序一致同时启用排除列表exclusion list可通过set_exclude_collision_path()排除个别子节点enabled false必须手动注册使用set_collision_count()设定数量、set_collision_path()逐一写入碰撞体节点路径。相关的查询与清理接口还包括get_collision_count()/get_collision_path()读取手动注册的碰撞列表clear_collisions()清空手动注册的碰撞列表get_exclude_collision_count()/get_exclude_collision_path()读取排除列表clear_exclude_collisions()清空排除列表are_all_child_collisions_enabled()查询当前是否处于全部子碰撞体生效模式。节点结构与示例场景一个典型的场景树如下Skeleton3D (根骨骼) └─ SpringBoneSimulator3D (骨骼弹簧模拟器) ├─ SpringBoneCollisionCapsule3D (躯干胶囊外壁模式) ├─ SpringBoneCollisionSphere3D (肩部球体) └─ SpringBoneCollisionPlane3D (地面平面限制头发最低点)手动注册模式的 GDScript 示例# 在 SpringBoneSimulator3D 上手动注册碰撞体 var sim: SpringBoneSimulator3D $SpringBoneSimulator3D sim.set_enable_all_child_collisions(0, false) # 关闭自动收录 sim.set_collision_count(0, 2) # 碰撞列表注册 2 个碰撞体 sim.set_collision_path(0, 0, $SpringBoneSimulator3D/Capsule.get_path()) sim.set_collision_path(0, 1, $SpringBoneSimulator3D/Sphere.get_path()) # 运行时动态调整胶囊尺寸 var capsule: SpringBoneCollisionCapsule3D $SpringBoneSimulator3D/Capsule capsule.radius 0.15 capsule.height 0.8关节半径与滑动碰撞体并非让整个骨骼链参与碰撞而是以关节球的形式与碰撞体表面做移动与滑动。SpringBoneSimulator3D 的set_radius()方法文档指出关节半径用于与碰撞列表中的 SpringBoneCollision3D 进行移动和滑动其数值还可通过set_radius_damping_curve()提供的 Curve 沿骨骼链逐关节缩放。因此调参时要注意胶囊的radius决定碰撞壁的厚度而模拟器的关节radius决定骨骼链与碰撞壁之间保留的间隙。若关节半径过大即使碰撞体尺寸正常关节也可能被明显顶开。与骨骼绑定bone 与 offset基类 SpringBoneCollision3D 提供了将碰撞体绑定到骨骼的能力胶囊碰撞体同样继承这些属性boneint默认-1绑定骨骼的索引bone_nameString默认绑定骨骼的名称position_offsetVector3相对绑定骨骼姿态位置的偏移rotation_offsetQuaternion相对绑定骨骼姿态旋转的偏移get_skeleton()返回父 SpringBoneSimulator3D 的父 Skeleton3D 节点若存在。文档说明一旦设置了bone碰撞体就会**在模拟器的修改流程之前作为预处理**与祖先 Skeleton3D 的骨骼姿态同步。这非常适合让碰撞体跟随角色身体运动例如把躯干胶囊绑定到Spine骨骼当角色弯腰时碰撞体随之移动头发自然沿躯干表面滑动。示例var capsule: SpringBoneCollisionCapsule3D $SpringBoneSimulator3D/TorsoCapsule capsule.bone_name Spine capsule.position_offset Vector3(0, 0.05, 0) # 相对骨骼位置再抬高一点 capsule.radius 0.18 capsule.height 0.7 capsule.inside false另外基类将physics_interpolation_mode覆盖为2即按插值模式处理以保证物理插值下碰撞体的运动与模拟结果一致。缩放警告为什么缩放的碰撞体不可靠基类文档对此给出了明确的 Warning被缩放的 SpringBoneCollision3D 很可能无法按预期工作。请确保父级 Skeleton3D 及其骨骼没有被缩放。SpringBoneSimulator3D 的文档也有同样的警告。原因是弹簧骨骼模拟基于骨骼姿态空间与关节距离计算非均匀缩放会破坏胶囊体几何圆柱段与半球的相对比例以及碰撞距离计算的一致性。如果确实需要更大的碰撞范围请优先调整height/radius属性而不是缩放节点。这条约束同样适用于整个 SpringBoneSimulator3D 节点本身。三种碰撞体的选型建议碰撞体适用场景关键属性SpringBoneCollisionCapsule3D躯干、手臂、腿部等长条形障碍适合头发/衣摆沿身体表面滑动height、mid_height、radius、insideSpringBoneCollisionSphere3D肩部、头部等点状障碍radius、insideSpringBoneCollisionPlane3D地面、桌面等无限平面约束限制摆动最低点无尺寸属性无限平面Y 为法线对于角色头发这类典型需求一个常用组合是躯干用胶囊外壁模式 头部用球体外壁模式 地面用平面再配合 SpringBoneSimulator3D 的stiffness刚度越大越快速恢复原姿态、drag阻尼越大摆动越受抑制、gravity重力速度非 0 时姿态不会完全归位三个核心调参项完成整体效果。版本与兼容性备注Godot 4.6 的升级文档 upgrading_to_godot_4.6.rst 记录了 SpringBoneSimulator3D 相关的 API 变更get_end_bone_direction、get_joint_rotation_axis、get_rotation_axis等方法的枚举返回类型从SpringBoneSimulator3D.BoneDirection/SpringBoneSimulator3D.RotationAxis迁移到了基类SkeletonModifier3D下。如果项目从 4.4/4.5 升级到 4.6脚本中引用这些枚举时需要使用新的SkeletonModifier3D.BoneDirection与SkeletonModifier3D.RotationAxis命名空间。SpringBoneCollisionCapsule3D 本身的 API 在这期间保持稳定不受影响。参考文档索引主文档class_springbonecollisioncapsule3d.rst基类class_springbonecollision3d.rst模拟器class_springbonesimulator3d.rst球形碰撞体class_springbonecollisionsphere3d.rst平面碰撞体class_springbonecollisionplane3d.rst骨骼修改器基类class_skeletonmodifier3d.rst以上全部文档均位于仓库classes/目录是 Godot 引擎官方类参考的一部分可随时查阅以核对更细粒度的 API 行为。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 弹簧骨骼碰撞体 SpringBoneCollision3D 完全指南为 SpringBoneSimulator3D 配置头发、布料与尾巴的物理碰撞Godot 弹簧骨骼碰撞体 SpringBoneCollision3D 完全指南为 SpringBoneSimulator3D 配置头发、布料与尾巴的物理碰撞文档教程游戏开发Godot 2D 物理碰撞完全指南CapsuleShape2D 胶囊碰撞体属性、约束与实战用法Godot 2D 物理碰撞完全指南CapsuleShape2D 胶囊碰撞体属性、约束与实战用法 导读 本文基于 Godot 官方文档godot docs中文档教程游戏开发Godot Engine角色碰撞体积胶囊体与精确碰撞Godot Engine角色碰撞体积胶囊体与精确碰撞 在游戏开发中角色与环境的交互精度直接影响玩家体验。你是否曾遇到角色穿墙、卡住或碰撞判定不准确的问题本游戏开发图形学跨平台上一篇Pwndbg终极升级指南5分钟完成自动化版本更新下一篇TinyTroupe文化馆系统模拟群众行为优化文化馆活动组织创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考