godot-physics-3d

3D 物理（Jolt/Native）

高性能 3D 模拟：刚体选择、CCD、台阶、载具、布娃娃、SoftBody——通过脚本实现。

绝对不要

• 绝对不要在 _process() 中移动 PhysicsBody3D 节点——请使用 _physics_process()。在物理步之外移动刚体会导致画面抖动和碰撞检测不可靠 [12, 13]。
• 绝对不要直接缩放碰撞形状——缩放物理形状会导致不稳定、法线不准确和抖动。请改用 shape 属性（高度、半径、尺寸）。
• 绝对不要直接修改 RigidBody3D 变换——这会绕过物理求解器。请使用 apply_impulse()、apply_torque() 或 _integrate_forces() 回调进行安全操作 [17]。
• 绝对不要将 RigidBody3D 用于平台游戏的玩家控制器——RigidBody 用于由物理驱动的物体。要实现精细的移动控制，请使用 CharacterBody3D 和 move_and_slide() [move_and_slide]。
• 绝对不要让静态网格启用连续 CD（CCD）——这会大幅增加 CPU 开销。仅对高速小物体（子弹）启用，以防其穿过墙壁。
• 绝对不要在未手动清理的情况下使用 PhysicsServer3D RID——RID 不会被垃圾回收。如果通过服务器创建刚体，完成后必须调用 free_rid()，以避免内存泄漏。
• 绝对不要使用 RayCast3D 在台阶上精确检测地面——单条射线太细。请使用带圆柱体或球体形状的 ShapeCast3D，以可靠地检测可行走的台阶 [Stair Logic]。
• 绝对不要依赖 VehicleBody3D 实现非赛车类的街机载具——它是复杂的模拟系统。对于街机气垫船或简单汽车，使用带射线检测的自定义 CharacterBody3D 通常更容易调校。
• 绝对不要忘记正确设置 collision_layer 和 collision_mask——如果所有物体都在第 1 层，冗余检查会严重拖累性能。请对世界进行分类。
• 绝对不要将 Area3D 用于高频阻挡——Area 用于检测。墙壁或屏障应使用 StaticBody3D，以确保即时且可靠地阻挡。

---

刚体 / 症状决策树

必须——编写移动或模拟代码前，先加载所选行对应的脚本。

不要为一个控制器加载所有物理脚本。

需求 / 症状	刚体 / API	脚本
玩家移动、台阶、斜坡	CharacterBody3D	必须 kinematic_3d_stairs_logic.gd + shapecast_3d_ground_check.gd
碎片、道具、冲量驱动的物体	RigidBody3D	绝对不要 + 冲量；通过 physics_layers_3d_config.gd 设置层
赛车 / 轮式模拟	VehicleBody3D	必须 vehicle_simulation_tuning.gd
街机气垫船 / 简单汽车	自定义 CharacterBody3D + 射线	优先使用台阶 / 射线脚本；避免使用完整的 VehicleBody
死亡 / 混合到物理姿势	PhysicalBone3D / 骨架	必须 ragdoll_manager.gd
斗篷、软布、柔软植被	SoftBody3D	必须 soft_body_3d_interaction.gd
穿透物体的子弹	CCD / 服务器子弹	必须 physics_ccd_3d_projectile.gd 或 physics_server_3d_bullets.gd
关节断开 / 可破坏物体	Joint3D 应力	joint_3d_breakage_logic.gd
重力井 / 零重力	区域优先级	custom_gravity_well_3d.gd
视线 / AI 视觉	直接空间状态	ray_query_3d_vision.gd
调试命中法线	可视化工具	raycast_visualizer.gd

3D 层的注意事项（并非 2D 入门指南）

• 层 = 对象是什么；遮罩 = 对象会碰到什么。在 physics_layers_3d_config.gd 中为位命名。
• 不要在此重复与 2D 相同的层教程；官方文档涵盖了共通的思维模型。

可用脚本

kinematic_3d_stairs_logic.gd

为 CharacterBody3D 实现程序化阶梯行走和贴合。

shapecast_3d_ground_check.gd

使用体积检测地面和台阶（射线会穿透）。

ragdoll_manager.gd

动画 → PhysicalBone 模拟的转换、冲量和清理。

vehicle_simulation_tuning.gd

VehicleBody3D / VehicleWheel3D 的街机模式与模拟模式调节项。

soft_body_3d_interaction.gd

SoftBody3D 标志、固定，以及 Jolt 质量/刚度调节。

physics_ccd_3d_projectile.gd

对小型高速刚体使用 CCD / 子步进防止穿透。

physics_server_3d_bullets.gd

大规模发射 RID 子弹，必须调用 free_rid()。

physics_layers_3d_config.gd

命名 3D 碰撞矩阵架构。

custom_gravity_well_3d.gd

行星 / 零重力 Area3D 重力优先级。

joint_3d_breakage_logic.gd

关节应力监测和程序化断裂。

ray_query_3d_vision.gd

底层视线 / AI 视觉查询。

raycast_visualizer.gd

在游戏中调试绘制射线命中点/法线。

专家提示（Jolt）

• 除非需要特定节点的用户体验，否则优先使用 Generic6DOFJoint3D，而不是叠加专用关节。
• 布娃娃、载具和软体示例都在上面的脚本中——不要在本文中扩展创建物理骨架的编辑器教程。
• 特定版本的 Jolt / 软体升级步骤： migration-notes.md。

深入内容（按需阅读）

• 悬浮射线约束、Jolt 悬架调节、布娃娃影响混合 → expert-3d-constraints.md
• 脚本：hover_constraint_3d.gd、ragdoll_blender.gd

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作分配给相邻领域时再加载相关技能——不要预先加载整个技能网络。

官方文档

• 物理简介 — 图层与掩码、物体类型，以及所有 3D 设置都依赖的 2D/3D 碰撞通用思维模型。
• 碰撞形状（3D） — 基本形状与凸形／凹形的区别，以及缩放 CollisionShape3D 为何会破坏法线和接触。
• 使用 Jolt Physics — 引擎切换、相较于 Godot Physics 的关节属性差异，以及稳定 3D 模拟所需注意的项目设置。
• 使用 RigidBody — 通过力、冲量和 _integrate_forces 安全地控制物体，而不是每帧修改变换来对抗求解器。
• 布娃娃系统 — 用于死亡模拟和动画↔物理切换的 PhysicalBoneSimulator3D / PhysicalBone3D 设置。
• 使用 SoftBody3D — 布料／旗帜形变、固定点，以及 Jolt 为何更适合提升软体物理的稳健性。
• 射线投射 — RayCast3D 与 PhysicsDirectSpaceState3D 查询、排除项，以及在物理帧期间访问空间。
• 物理问题排查 — 隧穿、抖动、CCD 误用，以及常见的图层／掩码配置错误。
• 物理插值简介 — 固定物理帧为何会在高刷新率显示器上出现卡顿，以及插值何时能平滑 3D 运动。
• PhysicsServer3D — 基于 RID 的物体／形状 API，可用于群体规模的投射物，并且必须使用 free_rid 清理。
• PhysicsDirectSpaceState3D — 用于视线检测、悬浮约束和自定义悬架的射线／形状／点查询，无需永久查询节点。
• ShapeCast3D — 用于台阶／地面检测的体积投射，适合细窄的 RayCast3D 无法检测到边缘或不平整地面的情况。

相关技能

前置要求

• godot-project-foundations — 必须先设置 3D 物理引擎选项、帧率、重力和具名图层位，才能合理设置矩阵和 Jolt 参数。
• godot-gdscript-mastery — 类型化 RID、位掩码枚举和 _physics_process 使用规范，是本文服务器端与 CharacterBody3D 模式的基础。
• godot-signal-architecture — body_entered / 接触监视器的连接需要清晰的所有权管理，以免 Area3D 重力井和 CCD 命中事件反复触发。

补充

• godot-2d-physics — 在跨维度共享策略或移植机制时，配套参考层/掩码和物体类型契约。
• godot-raycasting-queries — 当视觉/命中扫描系统超出基础需求时，深入了解查询参数的用法（掩码、排除项、形状投射）。
• godot-3d-world-building — GridMap/CSG/网格的静态碰撞必须与角色和弹丸使用的同一套 3D 层矩阵保持一致。
• godot-animation-tree-mastery — AnimationTree 姿势和状态机为 PhysicalBoneSimulator3D 提供布娃娃启动/停止和影响混合所需的信息。
• godot-performance-optimization — 当 PhysicsServer3D 群集、软体或 CCD 数量成为瓶颈时，参考性能分析和对象池建议。
• godot-debugging-profiling — 诊断抖动、穿透或台阶检测失败时，参考可视化碰撞形状、接触法线和性能分析器陷阱。

下游 / 使用方

• godot-combat-system — 3D 命中箱/受击箱和弹丸 CCD 沿用此领域中的层/掩码及空间查询选择。
• godot-genre-racing — VehicleBody3D 悬架/摩擦力调校和漂移手感会用到这里的车辆和 Jolt 指南。
• godot-genre-shooter-fps — 命中扫描射线、CharacterBody3D 移动和高速弹丸 CCD 都会直接用到这些契约。
• godot-navigation-pathfinding — Agent 仍需要物理层来处理阻挡物和视线（LOS）；确保导航网格与碰撞世界保持一致。
• godot-monte-carlo-balancer — 重力、CCD、关节断裂阈值和命中箱尺寸都会影响胜率；应模拟这些物理参数，而不是凭空猜测。

主入口

• godot-master — 库路由器和镜像入口，用于查找 3D 物理及其相关领域。