文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载导读SpringBoneCollisionPlane3D是 Godot 引擎中弹簧骨骼模拟Spring Bone体系的核心碰撞体之一它提供一个无限大的 XZ 平面法线方向固定为Y用于与 SpringBoneSimulator3D 驱动的骨骼链如毛发、布料、尾巴进行碰撞与滑动交互。读完本文你将掌握该节点的继承关系、几何语义、骨骼绑定方式、与模拟器的配合流程以及在实际角色骨骼上搭建碰撞场景的完整思路。类概览继承链与核心语义SpringBoneCollisionPlane3D的继承链如下SpringBoneCollisionPlane3D SpringBoneCollision3D Node3D Node Object对应源码定义位于 class_springbonecollisionplane3d.rst。它本身没有额外的属性和方法全部能力继承自基类 SpringBoneCollision3D。在 Godot 的弹簧骨骼体系中共有三种碰撞体子类全部继承自SpringBoneCollision3D子类几何形状文档路径SpringBoneCollisionPlane3D无限 XZ 平面法线为 Yclass_springbonecollisionplane3d.rstSpringBoneCollisionCapsule3D胶囊体含圆柱中段与半球端帽class_springbonecollisioncapsule3d.rstSpringBoneCollisionSphere3D球体class_springbonecollisionsphere3d.rstSpringBoneCollisionPlane3D的几何语义非常明确它是一个尺寸无限大的 XZ 平面因此Node3D的 Scale 对它没有传统意义上的缩放碰撞体效果平面始终贯穿世界空间其Y 方向被当作碰撞法线。这意味着它最适合用来模拟地面、桌面、衣领内衬这类无限延伸的阻挡面防止头发、裙摆、尾巴的关节穿过角色身体或地面。碰撞体的生效前提必须作为模拟器的子节点与物理引擎的碰撞体如CollisionShape3D不同弹簧骨骼碰撞体系完全独立于PhysicsServer3D它不使用物理层、碰撞掩码或刚体而是由SpringBoneSimulator3D在骨架修改阶段自行完成的纯数学求解。基类 SpringBoneCollision3D 明确规定了生效条件碰撞体可以是SpringBoneSimulator3D的子节点。如果它不是SpringBoneSimulator3D的子节点则不产生任何效果。因此搭建时的标准节点结构如下Character (Node3D) └── Skeleton3D ├── SpringBoneSimulator3D # 弹簧骨骼模拟器继承自 SkeletonModifier3D │ ├── SpringBoneCollisionPlane3D # 无限平面碰撞体本文主角 │ ├── SpringBoneCollisionSphere3D # 球形碰撞体 │ └── SpringBoneCollisionCapsule3D # 胶囊碰撞体 └── (骨骼 / 蒙皮网格等)注意SpringBoneSimulator3D本身继承自 SkeletonModifier3D而SkeletonModifier3D通过存在一个Skeleton3D父节点来获取目标骨架。所以模拟器和碰撞体都要挂在Skeleton3D之下。碰撞与滑动求解的底层执行顺序碰撞并非在主循环中独立计算而是被内嵌进SpringBoneSimulator3D的骨架修改流程中。理解这个顺序对排查碰撞不生效问题至关重要其流程分两个阶段预处理阶段碰撞体姿态同步如果碰撞体的bone属性被设置碰撞体会与祖先Skeleton3D对应骨骼的**骨骼姿态bone pose**同步位置与朝向这一步发生在模拟器修改流程之前。修改阶段碰撞求解碰撞与滑动按碰撞体列表的顺序执行。该列表由SpringBoneSimulator3D.set_collision_path()指定如果调用set_enable_all_child_collisions(index, true)启用了所有子碰撞体模式则列表顺序与SceneTree中的节点顺序一致。基类还给出了一条重要警告警告被缩放的SpringBoneCollision3D很可能不会按预期工作。请确保父级Skeleton3D及其骨骼未被缩放。这同样适用于SpringBoneCollisionPlane3D由于平面是无限大小的缩放节点或骨骼不仅没有意义还可能引入姿态同步误差应在制作管线中保持骨骼与骨架单位缩放。绑定骨骼让平面跟随骨骼移动SpringBoneCollisionPlane3D继承自基类的核心属性共有四个其中前两个用于把碰撞体绑定到某根骨骼上boneint默认-1附加骨骼的索引。设置后碰撞体在模拟器的预处理阶段会自动与祖先Skeleton3D中该骨骼的骨骼姿态位置同步。默认值-1表示未绑定。bone_nameString默认附加骨骼的名称。提供名称方式的好处是当骨架导入顺序变化时名称引用仍然稳定Godot 内部会将其解析为骨骼索引。position_offsetVector3相对骨骼姿态位置的偏移量。例如把平面放在角色胸腔骨骼上再通过position_offset将平面下移几厘米让衣领平面恰好位于脖子与胸部之间。rotation_offsetQuaternion相对骨骼姿态旋转的偏移量。由于SpringBoneCollisionPlane3D的法线固定为本地 Y通过旋转偏移可以让平面法线指向任意方向——例如把地面平面倾斜成一个斜坡或者让衣领内衬平面朝向斜上方。四个属性均有对应的 setter/getterset_bone/get_bone、set_bone_name/get_bone_name、set_position_offset/get_position_offset、set_rotation_offset/get_rotation_offset可直接在代码中动态调整。此外基类还提供一个查询方法func get_skeleton() - Skeleton3D返回父级SpringBoneSimulator3D所属的Skeleton3D节点如果找到否则返回null。这在运行时检查碰撞体是否处于有效骨架下非常实用。与模拟器的协作碰撞列表与排除列表SpringBoneCollisionPlane3D要真正参与求解必须被纳入模拟器的碰撞列表。相关 API 全部位于 SpringBoneSimulator3D以下方法均接收index参数多套设置时的条目序号对应settings/index/...配置项API作用set_enable_all_child_collisions(index, enabled)true时所有子碰撞体自动参与碰撞并通过set_exclude_collision_path()维护排除列表false时需要手动用set_collision_path()注册set_collision_path(index, collision, node_path)在碰撞列表中登记指定节点路径的碰撞体are_all_child_collisions_enabled为false时生效set_exclude_collision_path(index, collision, node_path)在排除列表中登记碰撞体启用全部子碰撞体模式时生效set_collision_count(index, count)/set_exclude_collision_count(index, count)预先设置列表条目数量get_collision_path/get_exclude_collision_path读取列表中的节点路径clear_collisions(index)/clear_exclude_collisions(index)清空对应列表are_all_child_collisions_enabled(index)查询当前模式两种模式的使用建议全部子碰撞体模式推荐编辑器工作流直接在SpringBoneSimulator3D节点下挂多个碰撞体碰撞顺序即场景树顺序个别不需要的碰撞体放入排除列表。手动列表模式适合运行时动态控制用代码精确控制哪些碰撞体参与适合多套骨骼设置复用同一批碰撞体的场景。关节半径平面碰撞的实际作用对象平面碰撞体本身没有半径属性——真正有粗细的是骨骼链上的关节。SpringBoneSimulator3D.set_radius()设置骨骼链的关节半径模拟时关节会被当作一个球与碰撞体表面进行**移动与滑动move and slide**求解。radius的值还可以通过set_radius_damping_curve()用 Curve 按关节位置逐段缩放。因此平面碰撞体的厚度感完全取决于关节半径关节半径越大头发或裙摆关节就越早被平面推开视觉上像被一层更厚的气垫托住。平面碰撞的典型应用场景结合SpringBoneCollisionPlane3D的无限平面 Y 法线特性以下是几种实践中验证有效的用法1. 裙摆防穿地在角色脚踝附近放置一个绑定到骨盆或大腿骨骼的平面position_offset.y设为一个略高于地面的负偏移让裙摆骨骼链的关节永远无法穿过地面——即便裙摆因为惯性大幅下垂。2. 衣领内衬阻挡头发把平面绑定到头部或脖颈骨骼通过rotation_offset将平面法线Y朝向身体外侧前方长发关节会沿着平面滑动避免插进脖子或锁骨区域。3. 尾巴防穿身把平面绑定到髋部骨骼并略微前倾作为尾巴根部的挡板。需要说明的是平面是无限大的不存在平面边缘所以在制作流程中更依赖bone绑定 姿态同步让平面跟随角色移动而不是试图靠节点位置摆放一个有限区域。与其他碰撞体的取舍在实际项目中三种碰撞体通常组合使用各有侧重SpringBoneCollisionPlane3D平面适合无限延伸的阻挡面如地面、衣领、肩颈挡板参数最少只有继承来的绑定与偏移属性。SpringBoneCollisionSphere3D球体带radius默认0.1与inside默认false两个属性。inside true时碰撞体会把关节困在球体内部适合模拟头部内部、胸部腔体等封闭空间。SpringBoneCollisionCapsule3D胶囊带height默认0.5、radius默认0.1、mid_height与inside属性。mid_height是排除半球后的圆柱中段高度即两个半球球心之间的距离是height的包装属性且胶囊约束height必须至少是radius的两倍否则会自动调整为合法值退化为球。属性SpringBoneCollisionPlane3DSpringBoneCollisionSphere3DSpringBoneCollisionCapsule3D几何参数无无限平面radius默认 0.1radius默认 0.1、height默认 0.5、mid_heightinside陷阱模式不适用支持支持继承自基类的绑定属性bone、bone_name、position_offset、rotation_offset同左同左调参要点与版本注意事项要让平面碰撞与弹簧骨骼配合出自然效果需同时理解模拟器侧的几个核心参数它们直接决定关节在碰撞前后的运动行为stiffness刚度值越大恢复初始姿态越快若为0修改后的姿态永远不会回到原始姿态可用来做垂死布料效果。drag阻尼值越大摆动被抑制得越明显。gravity重力注意它不是加速度而是沿gravity_direction方向的恒定速度若不为0姿态将始终受重力影响而无法完全复原适合制作自然下垂的头发。external_force外力恒定施加于骨骼的力等效于父Skeleton3D以反方向同速移动的结果常用来模拟风力或反重力。rotation_axis旋转轴设为特定轴时关节像铰链一样受限ROTATION_AXIS_ALL为无约束旋转ROTATION_AXIS_CUSTOM允许自定义任意轴。文档特别提醒旋转轴向量与骨骼前向向量不应共线因为模拟器不考虑扭转力共线会导致意外旋转。mutable_bone_axes可变动骨骼轴默认true为false时求解器从骨骼 Rest 姿态读取并缓存骨骼轴性能略有提升但会忽略修改流程之前对骨骼姿态的位移变化。另外还有一个容易踩坑的细节set_end_bone_name()要求末端骨骼必须是根骨骼或根骨骼的子骨骼如果两者相同则必须通过set_extend_end_bone(index, true)扩展出尾巴扩展尾巴的配置会分配在关节列表的最后一个元素上骨骼才能产生抖动。关于版本从 Godot 4.6 开始SpringBoneSimulator3D的get_end_bone_direction、get_joint_rotation_axis、get_rotation_axis、set_end_bone_direction、set_joint_rotation_axis、set_rotation_axis的枚举类型由SpringBoneSimulator3D.BoneDirection/RotationAxis迁移为SkeletonModifier3D.BoneDirection/RotationAxis见 upgrading_to_godot_4.6.rst迁移时注意 GDScript 直接兼容、C# 需要源码级适配。最小可用场景示例下面给出一个 GDScript 代码层面的最小搭建流程演示如何用代码把平面碰撞体接入模拟器编辑器中也完全可以通过场景树完成同样配置# 假设 skeleton 是角色的 Skeleton3D 节点 var simulator : SpringBoneSimulator3D.new() skeleton.add_child(simulator) # 1. 定义骨骼链从根骨骼到末端骨骼中间骨骼自动生成关节列表 simulator.set_root_bone_name(0, Hair_Root) simulator.set_end_bone_name(0, Hair_Tip) # 2. 基础参数按需调整 simulator.set_stiffness(0, 0.8) # 恢复力 simulator.set_drag(0, 0.6) # 阻尼 simulator.set_radius(0, 0.05) # 关节半径决定碰撞体厚感 simulator.set_gravity(0, 0.5) # 重力速度 simulator.set_gravity_direction(0, Vector3.DOWN) # 3. 注册碰撞体启用所有子碰撞体模式碰撞顺序场景树顺序 simulator.set_enable_all_child_collisions(0, true) # 4. 添加无限平面碰撞体并绑定到骨骼 var plane : SpringBoneCollisionPlane3D.new() simulator.add_child(plane) plane.bone_name Neck # 跟随颈部骨骼姿态 plane.position_offset Vector3(0, 0.1, 0) # 相对骨骼位置偏移 plane.rotation_offset Quaternion() # 保持法线为本地 Y # 5. 需要排除某个子碰撞体时加入排除列表 simulator.set_exclude_collision_count(0, 1) simulator.set_exclude_collision_path(0, 0, simulator.get_path_to(inner_collider))总结SpringBoneCollisionPlane3D是 Godot 弹簧骨骼碰撞体系中结构最简单、用途却很关键的碰撞体一个无限延伸、法线恒为 Y 的平面。它的实战价值在于作为无限阻挡面与SpringBoneSimulator3D的关节半径求解器协作防止毛发、布料、尾巴等惯性模拟物体穿入地面或身体。使用时牢记三条铁律必须是模拟器的子节点、父Skeleton3D与骨骼不能被缩放、碰撞顺序由碰撞列表或场景树顺序决定。配合bone/position_offset/rotation_offset的骨骼绑定能力它就能稳定地跟随角色移动并持续提供碰撞约束。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 弹簧骨骼碰撞体 SpringBoneCollision3D 完全指南为 SpringBoneSimulator3D 配置头发、布料与尾巴的物理碰撞Godot 弹簧骨骼碰撞体 SpringBoneCollision3D 完全指南为 SpringBoneSimulator3D 配置头发、布料与尾巴的物理碰撞文档教程游戏开发Godot 4 骨骼弹簧物理SpringBoneCollisionCapsule3D 胶囊碰撞体完全指南Godot 4 骨骼弹簧物理SpringBoneCollisionCapsule3D 胶囊碰撞体完全指南 SpringBoneCollisionCapsule文档教程游戏开发Godot 3D 粒子碰撞指南GPUParticlesCollision3D 四种碰撞体全解析Godot 3D 粒子碰撞指南GPUParticlesCollision3D 四种碰撞体全解析 GPU 粒子完全在显卡上运行天然无法访问引擎的物理世界 G文档教程游戏开发上一篇Stability-AI/StableLM 项目常见问题解决方案下一篇【亲测免费】 Mistral开源项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考