企业官网建设流程全解析

• 物理引擎
• 游戏开发
• 机器人

本篇指南围绕 Rapier 仓库中的website/USER_GUIDE_AUDIT.md审计文档展开，系统梳理该审计针对website/docs/user_guides/templates/下的官方用户指南与引擎实现之间的一致性核对结果，包括已确认的过期内容清单、缺失内容清单、修复后的最终状态，以及对应的引擎源码级证据。读者在读完本篇后，将能够理解 Rapier 文档版本管理的核对方法、掌握各审计项背后涉及的 API 变更（如PhysicsWorld入口、Intersect查询改名、CCD 默认行为变化、求解器特性开关等），并可直接对照当前仓库验证每一项修复的落地情况。

审计文档的背景与核对范围

website/USER_GUIDE_AUDIT.md是一份面向文档维护者的用户指南审计记录，其审计对象是website/docs/user_guides/templates/目录下的全部指南模板，核对基准为soft-bodies分支上的引擎实现（文档撰写时对应的 rapier 版本为 0.35.3，@dimforge/rapier为 0.17.3，与website/docs-examples中锁定的版本一致）。

审计的核心方法论是逐项对照源码：

• 指南中引用的每一个 API 名称，都与仓库根目录src/下的 Rust 实现逐一比对；
• 指南中引用的每一个默认值，都与bindings/typescript/src.ts中的 TypeScript 绑定实现比对；
• 审计遵循"每个条目一个提交"（One commit per item）的粒度，便于追溯与回滚。

需要注意的是，审计文档本身是在某一历史版本上编写的，而当前仓库已推进到rapier 0.36.1（见 Cargo.toml 的version.workspace = true）。从当前仓库的模板文件看，审计清单中的大部分条目已标记完成（[x]），且修复内容已实际落地到website/docs/user_guides/templates/的对应.mdx文件中。本篇将逐类解读审计发现，并结合当前源码验证修复后的最终状态。

审计发现之一：过期内容（Outdated content）

审计文档把"指南描述与当前实现不一致"的问题归为过期内容，共列出 13 项。以下是每一类的核心内容与当前仓库的验证结果。

1. CCD 语义更新（rigid_body_ccd.mdx）

原审计指出：rigid_body_ccd.mdx中关于 CCD 默认关闭、ccd_enabled的作用、运动钳制（motion clamping）描述以及max_ccd_substeps的说明已经过时。当前仓库中 rigid_body_ccd.mdx 已按新语义重写，其核心内容如下：

• 自动 CCD（默认开启）：每个快速移动的动态刚体都会对场景中的固定 collider 和软体进行扫掠检测，这不需要任何开关，用于防止落下的箱子穿透地板、子弹穿透墙壁等典型隧穿问题；
• 子弹 CCD（按需开启）：启用了ccd_enabled的动态刚体（即子弹）还会对运动学刚体和动态刚体进行扫掠，成本更高，应只保留给绝不能穿过移动障碍物的对象。文档也如实说明：两个都启用 CCD 的对象之间仍可能发生隧穿，因为当前实现不会同时考虑双方的连续运动；
• 全局开关：将 IntegrationParameters 中的max_ccd_substeps设置为0，即可关闭该世界的一切 CCD 形式（包括自动扫掠），其默认值为1。

当前引擎源码 integration_parameters.rs 中pub max_ccd_substeps: usize字段与文档描述一致，验证了"0 为全局开关"这一语义。值得注意的是，文档还专门提醒：只有相对另一个 collider 快速移动的刚体 CCD 才会起作用，因此在固定刚体或预期缓慢移动的刚体上开启 CCD 没有意义。

2. 非有限状态与隔离机制（common_mistakes.mdx）

审计指出：common_mistakes.mdx中描述的"宽相（broad-phase）panic"已不存在，取而代之的是隔离（quarantine）机制。当前模板 common_mistakes.mdx 已按新机制描述：

当刚体、collider 或软体的状态出现非有限值（NaN或无穷大）时，Rapier 不再让整个模拟崩溃或让坏值传播，而是在每个时间步的开始和结束时检测，并将受影响对象放入隔离区：重置到最后一次有效位置、速度清零、并禁用对象。隔离报告在 Rust 中通过PhysicsWorld::quarantine（或自行驱动管线时的PhysicsPipeline::quarantine）获取，且每次时间步后清空，因此必须在产生隔离的那一步之后立即读取。

源码级证据在 src/pipeline/physics_pipeline/quarantine.rs：Quarantine结构体分别记录上一步被隔离的刚体、collider 与软体（文档注释明确说明软体被隔离时"禁用、速度清零、非有限粒子位置保留"），并通过PhysicsWorld::quarantine（见 physics_world.rs）暴露。最常见的触发场景是两个零质量动态刚体开始接触，因此文档反复强调：动态刚体必须具有非零质量。

3. 质量属性计算规则的澄清（common_mistakes.mdx）

审计指出：common_mistakes.mdx中"三角形网格 collider 不计算质量属性"的描述有误。当前模板已修正为：

• **三角形网格（triangle-mesh）**的 mass properties 会按其面所包围的体积计算，前提是网格封闭且三角形朝向一致；
• 不包围任何体积的形状——折线（polylines）、半空间（half-spaces）、线段（segments）以及 3D 中的三角形（triangles）——无论密度多少，质量都为零。若刚体只挂了这类 collider，必须手动设置质量/角惯性。

4. 摩擦与恢复系数的合并规则补齐（collider_friction.mdx / collider_restitution.mdx）

审计指出：CoefficientCombineRule枚举中缺少ClampedSum与GeometricMean，且规则优先级说明不完整。当前 collider_friction.mdx 已列出全部六种合并规则：

并给出了完整的优先级链：GeometricMean > ClampedSum > Max > Multiply > Min > Average（C API 中即"值最大的规则胜出"）。例如一个Multiply规则 collider 与一个Average规则 collider 接触时，该接触将采用Multiply。文档同时提示：若这套规则仍不够灵活，可通过接触修改（contact modification）获得对每个接触点摩擦系数的完全控制，例如模拟非均匀摩擦系数的 collider。此外文档明确说明 Rapier 目前不区分静摩擦与动摩擦系数。

5. 场景查询方法改名（scene_queries_point_projection.mdx / scene_queries_intersection_test.mdx）

审计指出：QueryPipeline的查询方法已更名为intersect_point、intersect_shape与intersect_aabb_conservative。当前源码 query_pipeline.rs 中这三个方法均存在，且PhysicsWorld也做了同样的转发（physics_world.rs），与审计结论一致。

6. 序列化 API 与并行求解器确定性（determinism.mdx）

审计指出两点：World.createSnapshot不存在（应为takeSnapshot）；未提及并行求解器的跨平台确定性。当前 determinism.mdx 已覆盖：

• JS/WASM 版本使用world.takeSnapshot()，并说明对快照字节数组取 MD5 哈希，在不同机器上会得到完全相同的哈希值；
• Rust 版本默认是本地确定性（local determinism）：同一台机器、相同版本、相同编译器下重复运行完全相同的模拟，结果完全一致；但不同电脑上可能完全不同。
• 跨平台确定性需要额外条件：启用enhanced-determinism特性；目标平台严格遵守 IEEE 754-2008 浮点标准；初始化数值若涉及超越函数，必须使用 nalgebra 的ComplexField/RealField提供的实现（例如ComplexField::sin(0.4)而非0.4.sin()）。
• 并行求解器（parallel特性）可以与enhanced-determinism组合：并行求解器的结果与串行求解器完全相同，且不依赖 rayon 线程池的线程数，因此也不依赖机器核心数。但simd8（改变 SIMD 通道宽度）不能与enhanced-determinism同时启用，因为它本身就是独立的确定性域。

该描述在 determinism.mdx 的 Bevy、C、Python 分节中都有对应的平台化表述（例如 C 中使用r3Sin/r3Cos而非sinf/cosf，并通过r3BuildFeatures()的enhanced_determinism字段核对实际加载库的构建特性）。

7. 关节删除 API 更名（rigid_body_sleeping.mdx）

审计指出：World.removeJoint已拆分为removeImpulseJoint/removeMultibodyJoint。当前 rigid_body_sleeping.mdx 的 JS 分节已使用World.removeImpulseJoint(joint, true)与World.removeMultibodyJoint，Rust 侧对应ImpulseJointSet::remove(..., true)，与源码 physics_world.rs 中的remove_impulse_joint/remove_multibody_joint保持一致。该文档还给出了一条实用的唤醒语义：wake_up参数推荐恒为true，唯一的例外场景是用add_force(force, false)模拟自定义恒定重力——这样刚体在达到动态平衡后仍能正常入睡。

8. Cargo 特性列表更新（getting_started.mdx）

审计指出：getting_started.mdx中的特性列表仍提到已移除的wasm-bindgen，且漏掉了simd8、fem、block-solver、unsync-callbacks、debug-render、profiler。当前仓库 rapier3d/Cargo.toml 中的特性定义验证了审计结论：

• block-solver：为接触流形启用 2x2 分块求解器（把接触对的法向约束耦合成单个 2x2 MLCP 求解）。3D 默认不启用，因为它在 3D 多米诺示例中会引入抖动，作为可选的实验性开关暴露；
• fem：为软体增加基于应变能密度的隐式欧拉 FEM 求解路径，通过SoftBodyBuilder::solver(SoftBodySolver::Fem)按刚体选择，默认关闭且仍属实验性；
• parallel：启用 rayon 并行；
• unsync-callbacks：去掉回调（PhysicsHooks、EventHandler）的Sync约束，副作用是移除专用线程池 API；
• simd8：把求解器 SIMD 从 4 通道扩到 8 通道（仅 f32），需要parry3d/simd8，在 AVX 目标上才真正发出 256 位指令；
• debug-render、profiler：分别启用调试渲染与内部性能分析器；
• enhanced-determinism：通过simba/libm_force与parry3d/enhanced-determinism强制 libm 语义，是跨平台确定性的基础。

9. 事件收集器实现说明（advanced_collision_detection.mdx）

审计指出：ChannelEventCollector使用std::sync::mpsc通道而非 crossbeam，且构造时接收第三个发送端用于软体撕裂事件。源码 physics_world.rs 的文档示例证实了这一点：

let (collision_send, collision_recv) = channel(); let (contact_force_send, contact_force_recv) = channel(); let (soft_body_tear_send, soft_body_tear_recv) = channel(); let event_handler = ChannelEventCollector::new(collision_send, contact_force_send, soft_body_tear_send);

撕裂事件的回调handle_soft_body_tear_event在 event_handler.rs 中有明确文档，撕裂事件类型定义在 tearing_event.rs。

10. 仿真结构补齐（simulation_structures.mdx）

审计指出两点：管线所需结构中缺少SoftBodySet；PhysicsWorld完全未被提及。当前 simulation_structures.mdx 已大幅重写，两个问题均已解决（详见下一节"新增内容"）。

11. 侧边栏版本号（sidebar_docs.js）

审计指出：Rust 用户指南在侧边栏标注为 0.32 而非 0.35。该问题属于构建期配置修复，当前仓库根 Cargo.toml 的 workspace 版本已是 0.36.1，说明版本号维护已跟上引擎迭代。

12. 集成参数页重写（integration_parameters.mdx）

审计指出：integration_parameters.mdx中只有dt和min_ccd_dt仍存在，必须针对当前字段重写并在侧边栏重新启用。当前 integration_parameters.mdx 已是完整参数手册，源码 integration_parameters.rs 中dt、min_ccd_dt、length_unit、num_solver_iterations、num_internal_pgs_iterations、max_ccd_substeps、warmstart_coefficient、friction_model等字段均有对应实现。

审计发现之二：缺失内容（Missing content）

审计文档的第二类问题是被完全遗漏的主题，共 10 项。这些内容在审计后均已补写进模板目录，当前仓库website/docs/user_guides/templates/下可以找到对应文件。

1. PhysicsWorld——推荐的入口（对应条目 14）

这是审计最重要的结论之一：PhysicsWorld是拥有一场模拟全部集合的结构体，也是自 getting-started 示例仍手工接线所有结构以来的推荐入口。当前模板 simulation_structures.mdx 已专门成节，源码 physics_world.rs 证实其公有字段包括：gravity、integration_parameters、physics_pipeline、collision_pipeline、islands、broad_phase、narrow_phase、bodies、colliders、impulse_joints、multibody_joints、soft_bodies、ccd_solver。

模板文档给出了关键设计说明：PhysicsWorld是门面（façade），其拥有的每个结构仍作为公有字段可访问，因此切换到PhysicsWorld不会放弃任何能力（例如在整体借用PhysicsWorld会造成借用冲突的场景中，仍可直接操作其字段）。PhysicsWorld::step()会以默认的 gravity、集成参数、空 hooks 与空事件处理器推进一个时间步，step_with_events则接受自定义 hooks 与事件处理器（physics_world.rs）。Python 绑定中也存在对应的PhysicsWorld（PhysicsWorld.step、PhysicsWorld.integration_parameters等属性），且PhysicsWorld()不带 gravity 参数时完全没有重力——这是 Python 绑定与其他语言版本不同的陷阱，被记录在 common_mistakes.mdx 中。

2. 车辆控制器（条目 15）

缺失的DynamicRayCastVehicleController已补写为 vehicle_controller.mdx，其实现位于 ray_cast_vehicle_controller.rs，属于src/control/目录下的控制器家族。

3. PID 控制器（条目 16）

缺失的 PID 控制器已补写为 pid_controller.mdx，实现位于 pid_controller.rs。文档将其定位为"基于速度的角色控制器的构建模块"。

4. Rapier 自身的调试渲染器（条目 17）

审计指出指南只提到了 Bevy 插件的调试渲染器。当前模板目录已有 debug_render.mdx，对应的实现位于src/pipeline/debug_render_pipeline/（5 个源文件）与src_testbed/debug_render.rs。

5. 每刚体求解器设置（条目 18）

缺失的每刚体求解器设置——额外求解迭代、额外 PGS 迭代、软 CCD 预测、快速旋转与陀螺力——已补写为 rigid_body_solver_settings.mdx，并与 rigid_bodies.mdx 中的求解器设置小节联动。

6. 接触皮肤与单侧网格（条目 19）

缺失的 collider 接触皮肤（contact skin）以及单侧（朝向）三角形网格和折线已补写为 collider_contact_skin.mdx，并与 colliders.mdx 等页面形成完整的 collider 文档体系。

7. 场景加载器（条目 20）

缺失的三个场景加载器已补写为 scene_loaders.mdx，对应 crates 分别是：

• rapier3d-urdf：crates/rapier3d-urdf（URDF 机器人描述加载）
• rapier3d-mjcf：crates/rapier3d-mjcf（MuJoCo MJCF 加载）
• rapier3d-meshloader：crates/rapier3d-meshloader（网格加载）

这些 crates 均已在根 Cargo.toml 的 workspace members 中注册，并配有测试用例（如crates/rapier3d-mjcf/tests/下 16 个测试文件）。

8. Python 绑定文档（条目 21）

审计指出 Python 绑定位于bindings/python/且有独立文档。当前仓库的 Python 绑定工程为bindings/python/rapier-py-3d/，其python/子目录下包含 10 个.py、3 个.pyi与 1 个.typed文件，文档与测试位于bindings/python/rapier-py-3d/README.md与bindings/python/tests/（23 个测试文件）。审计后模板目录中还新增了 getting_started_py.mdx，说明 Python 入门流程（包括maturin develop --release -m bindings/python/rapier-py-3d/Cargo.toml的源码构建方式）。

9. 空页面补齐（条目 22、23）

审计发现the_rapier_testbed.mdx只有 front matter、common_recipes.mdx只有章节标题。当前模板目录中这两份文件依然存在但仍是占位结构，属于审计清单中"已标记完成但内容待后续填充"的条目（审计清单本身将其列为[x]完成项，指审计动作完成，而非页面内容补全）。

审计发现之三：示例改进（Examples）

审计的第 24 项指出：Rust 示例手工构建了仿真的每一个结构，而不是使用PhysicsWorld，这使示例冗长且隐藏了推荐的入口。结合 simulation_structures.mdx 的现状，模板文档现在同时呈现两种模式：

• 推荐模式：直接使用PhysicsWorld，创建、步进、查询的样板代码最少；
• 手工模式：每个结构（岛管理器、宽相、窄相、各集合、CCD 求解器、集成参数）自行创建，并在每个时间步全部传给PhysicsPipeline::step——这正是PhysicsWorld内部所做的。文档明确这种模式适用于结构必须由应用不同部分分别持有的场景（例如 ECS 的资源）。

Python 侧的手工模式中，soft_bodies集合、physics hooks 与事件处理器是可选的 keyword 参数，进一步降低了接线成本。

审计发现之四：延后事项（Deferred）

审计文档明确标注了两类不随本次审计处理的延后项：

1. Bevy 插件页面（包括getting_started_bevy.mdx中的simd-stable特性）在bevy_rapier更新之前保持不动；
2. docs-examples的依赖版本：当前锁定@dimforge/rapier0.17.3，而 0.20.0 已发布。升级不被视为纯文档改动——中间的三个大版本存在破坏性变更，JavaScript 代码片段必须相应适配。

这体现了审计的范围纪律：只处理当前基准版本内可由文档修正的事项，涉及跨版本迁移或外部依赖更新的工作单独排期。

从审计清单到维护实践：核对方法与可复用步骤

从USER_GUIDE_AUDIT.md的条目结构中，可以提炼出一套可复用的"文档-引擎一致性审计"流程：

1. 锁定核对基准：明确引擎版本（如 0.35.3）与绑定版本（如@dimforge/rapier0.17.3），并记录docs-examples锁定的依赖版本，避免"文档描述的版本"与"示例运行的版本"错位；
2. 按主题枚举 API 面：对每篇指南，列出其引用的所有 API 名称、默认值、行为描述，形成清单；
3. 对照源码逐项验证：Rust 侧对照src/，JS 侧对照bindings/typescript/src.ts，C 侧对照bindings/c/，Python 侧对照bindings/python/；
4. 区分三类结果：过期内容（行为/API 已变，需重写）、缺失内容（主题从未被文档覆盖，需新写）、延后内容（依赖外部更新，暂不处理）；
5. 保持追溯粒度：每条目一个提交，便于按条目回滚与评审。

当前仓库模板文档本身就是这套流程的输出物：例如collider_friction.mdx中补齐的ClampedSum/GeometricMean与优先级链、determinism.mdx中新增的并行求解器确定性说明、rigid_body_ccd.mdx中重写的 CCD 自动扫掠语义，都能在src/下的对应实现（src/geometry/coefficient_combine_rule.rs、src/pipeline/physics_pipeline/、src/dynamics/integration_parameters.rs）中找到一一对应的源码锚点。

总结

website/USER_GUIDE_AUDIT.md是一份高质量的文档质量审计样本，它展示了 Rapier 项目如何保持"文档-实现"的强一致性：以源码为唯一事实来源，逐 API、逐默认值核对，并将结果组织为过期/缺失/示例/延后四类。审计推动的修复已在当前仓库的website/docs/user_guides/templates/中大量落地，涉及 CCD 语义、隔离机制、合并规则、查询 API 改名、PhysicsWorld入口、求解器特性清单、场景加载器与 Python 绑定文档等关键主题。对于 Rapier 的用户而言，这份审计及其落地产物（各.mdx模板）可以作为权威的使用参考；对于文档维护者而言，它则提供了一套可复制的版本对齐与核对方法论。

• 物理引擎
• 游戏开发
• 机器人