LÖVR物理引擎API设计演进与Jolt集成思考

引言

LÖVR作为一款基于Lua的VR开发框架，其物理引擎模块的设计直接影响着开发者的使用体验。随着项目计划从现有物理引擎迁移到Jolt物理引擎，开发团队对物理API进行了深入思考与重新设计。本文将全面剖析LÖVR物理引擎API的演进历程、设计理念以及未来发展方向。

API设计优化方向

简化世界创建

原设计中，创建物理世界时需要显式指定重力参数，这在实际开发中显得冗余。新设计将重力设置改为可选参数，默认使用标准重力加速度-9.81，开发者可通过World:setGravity方法在需要时调整。

碰撞检测系统重构

原有的自定义碰撞系统包含World:update回调、World:computeOverlaps等方法，功能上既处理碰撞过滤又负责碰撞检测，架构上不够清晰。Jolt引擎提供了更完善的接触点回调机制，包括接触忽略、接触添加/持续/移除等事件，新设计将基于这些原生功能重构碰撞系统。

查询接口统一化

物理查询API经历了多次迭代优化：

1. 射线检测：从最初的三方法设计(raycast、raycastAny、raycastClosest)演变为单一方法的多模式设计。最终方案允许通过回调函数的有无和返回值控制查询行为：

   • 无回调：返回最近命中
   • 有回调：遍历所有命中
   • 回调返回true：提前终止(模拟原raycastAny)

2. 形状查询：将原本分散的collidePoint、collideTriangle等方法统一为shapecast的特例：

   • 零方向shapecast等效于碰撞检测
   • 三角形检测可通过网格形状shapecast实现

3. 空间查询：保留queryBox和querySphere作为快速宽相位查询，支持：

   • 球形查询的零半径特例(点查询)
   • 盒形查询的可选旋转参数(OBB查询)

物理参数规范化

移除了多个Jolt不支持的参数和功能：

• 响应时间和紧密度相关参数
• 全局线性/角度阻尼设置
• 睡眠允许阈值
• 阻尼方法的阈值参数

同时将"忽略重力"改为更符合物理直觉的"重力因子"概念。

Jolt集成关键技术点

复合形状支持

Jolt通过CompoundShape支持单个碰撞体的多形状组合，这与LÖVR现有API存在映射关系。经过讨论，团队决定保持现有Collider:addShape设计，在内部自动管理CompoundShape的创建和切换，避免暴露底层实现细节。

运动约束

新增了自由度限制功能，通过Collider:setLockedAxes方法可以锁定特定平移或旋转轴。底层利用Jolt的MotionProperties::SetMassProperties实现，虽然仅支持世界空间约束，但已能满足大部分用例需求。

性能优化考虑

1. 早期终止：Jolt支持查询过程中的早期终止优化，虽然Lua回调引入的性能损耗使得完全暴露该功能意义不大，但通过raycast的单结果返回和回调提前返回仍保留了基本优化能力。

2. 接触检测：Jolt提供了高效的"两物体是否接触"的哈希查询，比手动跟踪碰撞回调更高效。

3. 批量查询：所有查询方法都支持标签过滤，可通过World:getTagMask生成多标签位掩码，减少重复查询开销。

新增功能特性

1. 凸包形状：新增ConvexHull形状类型，扩展碰撞检测能力。

2. 运动质量设置：通过Collider:get/setMotionQuality控制离散或连续碰撞检测。

3. 静态碰撞体：在原有运动学和动力学类型基础上，增加真正的静态碰撞体支持。

4. 冲量应用：新增applyLinearImpulse和applyAngularImpulse方法，提供更直接的物理控制。

5. AABB查询：添加获取所有碰撞体包围盒的快捷方法，辅助调试和优化。

设计决策背后的思考

API设计过程中，团队在"功能完整性"和"易用性"之间不断权衡。例如在复合形状支持上，虽然暴露CompoundShape更贴近Jolt原语，但会引入额外的概念负担；而自动管理方案虽然隐藏了实现细节，但可能限制高级用法。

最终设计倾向于"约定优于配置"的理念：

• 常见用例提供简洁接口
• 保留必要的底层控制能力
• 通过合理的默认值减少样板代码
• 统一相似功能的方法签名

这种设计既照顾了新手开发者的上手体验，又不牺牲高级用户对物理引擎的精细控制需求。

未来展望

虽然当前API设计已趋于稳定，但物理模块仍有发展空间：

1. 物理材质系统：支持不同碰撞表面的音效和粒子触发
2. 高级约束特性：如关节限制的弹簧行为
3. 扩展模块：车辆系统、软体模拟、角色控制器等可作为插件形式提供
4. 大世界支持：基于Jolt的分区和大世界坐标能力

这些特性将随着核心API的稳定逐步引入，保持LÖVR物理系统的持续进化。