Jolt Physics:多核友好刚体物理引擎特性解析与 C++ 实战集成指南

原创2026-09-14 23:04:151,381 阅读
文章标签:物理引擎游戏开发高性能计算并发编程

Jolt Physics:多核友好刚体物理引擎特性解析与 C++ 实战集成指南

Jolt Physics 是一个用 C++ 编写、面向多核架构的刚体物理与碰撞检测库,专为游戏和 VR 应用设计,被《地平线:西之绝境》(Horizon Forbidden West)和《死亡搁浅 2》(Death Stranding 2: On the Beach)等 3A 作品实际采用。本文以仓库根目录的 README.md 为骨架,结合 HelloWorld、Build/README.md、PhysicsSettings.h 等源码与构建文档,系统讲解其设计理念、功能全貌、编译方式与最小可运行示例,帮助你判断它是否适合你的项目,并掌握从零接入的核心步骤。

项目定位:为什么要"再造一个物理引擎"

Jolt 的诞生既是作者的个人学习项目,也是为了回应已有物理引擎在使用中暴露的问题。围绕"游戏引擎不止在做物理模拟"这一现实,Jolt 在以下四个设计要点上与主流引擎形成差异:

  • 物理数据支持多线程并发访问。游戏的其他系统(渲染、动画、寻路、加载)都在多线程中运行,Jolt 强调在物理主模拟更新之外并发访问物理数据:
    • 关卡区块可以在后台线程"批处理"准备好一批刚体,不锁住也不影响正在进行的模拟,再以极小的性能代价把整批插入模拟世界;
    • 碰撞查询可以与刚体的增删改并行。若修改发生在同一线程,改动立即可见;若发生在其他线程,查询会看到一致的"前"或"后"状态。作者刻意避免了"读写双世界"方案,因为那会导致修改不能立即生效;
    • 碰撞查询可以与物理主模拟并行:模拟步进前先做粗粒度检查(broad phase query),把细粒度检查(narrow phase query)放到后台。这样寻路网格生成等耗时任务可以分摊到多个帧完成。
  • 避免意外的刚体唤醒。加载/卸载内容时,意外唤醒刚体会造成性能问题。因此刚体创建时不会自动唤醒;移除刚体时也不会唤醒相邻刚体。开发者可以按需手动触发。
  • 确定性模拟。通过仅复制模拟的输入,即可把一段模拟复现到远端客户端。确定性的边界条件可以参考架构文档中的 Deterministic Simulation 章节(见 Docs/Architecture.md)。
  • 面向游戏与 VR 的真实感近似。Jolt 尽量模拟现实世界的刚体行为,但保留合理的近似,因此主要定位是游戏与 VR 模拟,而非工程仿真。

功能全貌:从刚体到头发,一条完整的能力矩阵

刚体与形状(支持连续碰撞检测 CCD)

支持多种形状的刚体模拟,全部使用连续碰撞检测(CCD)来避免高速穿透:

球体(Sphere)、盒体(Box)、胶囊体(Capsule)、锥形胶囊(Tapered-capsule)、圆柱(Cylinder)、锥形圆柱(Tapered-cylinder)、凸包(Convex hull)、平面(Plane)、复合体(Compound)、网格(Mesh,三角形)、地形(Height field,高度场)。相关实现位于 Jolt/Physics/Collision/Shape/,例如 SphereShape、BoxShape、MeshShape、HeightFieldShape 等。

约束(Constraints)与马达

约束用于连接两个或多个刚体并限制其相对运动,Jolt 支持:固定(Fixed)、点(Point)、距离(Distance,含弹簧)、铰链(Hinge)、滑块(Slider,即棱柱)、锥形(Cone)、齿条齿轮(Rack and pinion)、齿轮(Gear)、滑轮(Pulley)、光滑样条路径(Smooth spline paths)、摇摆-扭转(Swing-twist,用于人形肩部)、六自由度(6 DOF)。每类约束的源码位于 Jolt/Physics/Constraints/,并以 MotorSettings(MotorSettings.h)驱动约束马达,实现主动施力。

碰撞检测

  • 射线投射(casting rays);
  • 形状 vs 形状测试(testing shapes vs shapes);
  • 形状投射(casting a shape vs another shape);
  • 仅宽相(Broadphase)测试,用于快速判断哪些物体可能相交,对应 BroadPhase/ 目录;
  • 传感器(Sensors,即触发体积)。

动画布娃娃(Ragdolls)

  • 硬关键帧(Hard keying,仅运动学刚体);
  • 软关键帧(Soft keying,对动力学刚体设置速度);
  • 用约束马达把布娃娃驱动到动画姿态;
  • 高细节(动画)骨骼与低细节(布娃娃)骨骼的双向映射,见 Jolt/Skeleton/ 中的 SkeletonMapper。

游戏角色(胶囊体)

  • 刚体角色(Character,Character.h):在物理模拟期间移动,最便宜且与动态刚体的碰撞响应最准确;
  • 虚拟角色(CharacterVirtual,CharacterVirtual.h):不在模拟中占用刚体,而是通过碰撞检测自行模拟,在物理更新之外更新以获得更多控制权,与动态刚体的交互精度较低。

车辆

轮式车辆(Wheeled)、履带车辆(Tracked)、摩托车(Motorcycle),统一基于 VehicleConstraint,使用射线或形状投射检测地面接触,并模拟发动机、变速箱、差速器和悬挂,见 Jolt/Physics/Vehicle/。

软体模拟(Soft Body)

软体可用于软球、布料等,支持:边约束(Edge)、二面角弯曲约束(Dihedral bend)、Cosserat 杆约束(带方向边缘,可用于植物叶片等需要定向几何的结构)、四面体体积约束、远程附着约束(Long range attachment,又称 tether)、限定模拟保持在蒙皮顶点一定范围内、内部压力、与模拟刚体的碰撞、针对软体的碰撞测试。见 Jolt/Physics/SoftBody/。

GPU 头发模拟

基于 Cosserat 杆的逐发丝模拟,运行在 GPU 上:

  • 可使用远程附着约束限制头发的拉伸;
  • 同时支持模拟发(guide)与渲染发(follow);
  • 发丝间碰撞通过在网格中累积平均速度、用该速度驱动发丝实现;
  • 支持与环境碰撞,目前仅支持 ConvexHull 和 CompoundShape;
  • 发根可以蒙皮到头皮网格上。着色器源码见 Jolt/Shaders/ 下 Hair* 系列 HLSL 文件。

其他

  • 水的浮力计算(buoyancy);
  • 可选的双精度模式(定义 JPH_DOUBLE_PRECISION),支持超大世界坐标。

支持的平台与 CPU 指令集要求

平台 架构
Windows x86 / x64 / ARM64
Linux(Ubuntu 上测试) x86 / x64 / ARM32 / ARM64 / RISC-V64 / LoongArch64 / PowerPC64LE
FreeBSD —
Android x86 / x64 / ARM32 / ARM64
Platform Blue(某主流游戏主机) x64
macOS x64 / ARM64
iOS x64 / ARM64
MSYS2 MinGW64 —
WebAssembly 见独立的 JoltPhysics.js 项目

CPU 指令集要求:x86/x64 上最低要求 SSE2,可选编译为 SSE4.1、SSE4.2、AVX、AVX2 或 AVX512;ARM64(AArch64)使用 NEON,兼容 Armv8-A;ARM32(AArch32)不使用任何特殊 CPU 指令。指令集的编译宏定义与 cmake 选项在 Build/README.md 与 Jolt/Jolt.cmake 中说明。

若目标平台为 Platform Blue,由于 NDA 限制需要自行准备构建环境与 PlatformBlue.h(该文件可在 Platform Blue 开发者论坛获取)。

编译要求一览

  • 编译器:Visual Studio 2022+、Clang 16+ 或 GCC 12+;
  • 语言标准:C++ 17(Jolt.cmake 中强制 CMAKE_CXX_STANDARD 17);
  • 仅依赖标准模板库(STL);
  • 不使用 RTTI;
  • 不使用异常(exceptions)。

快速上手:逐段精读 HelloWorld 示例

官方推荐的入门路径是先看 HelloWorld/HelloWorld.cpp。这是一个最小可运行的控制台程序:创建一个地板、一个下落的小球,以 60Hz 步进模拟直到小球入睡。下面按阶段精讲其关键代码(对应 main 函数)。

1. 头文件与命名空间约定

#include <Jolt/Jolt.h>   // 必须先包含 Jolt.h,再包含其他任何 Jolt 头文件
#include <Jolt/RegisterTypes.h>
#include <Jolt/Core/Factory.h>
#include <Jolt/Core/TempAllocator.h>
#include <Jolt/Core/JobSystemThreadPool.h>
#include <Jolt/Physics/PhysicsSystem.h>
#include <Jolt/Physics/Collision/Shape/BoxShape.h>
#include <Jolt/Physics/Collision/Shape/SphereShape.h>
#include <Jolt/Physics/Body/BodyCreationSettings.h>

using namespace JPH;
using namespace JPH::literals; // 提供 0.0_r 这类字面量

关键约定:Jolt 的头文件不会自动包含 Jolt.h,必须先包含它(可放入预编译头加速编译)。所有符号位于 JPH 命名空间。using namespace JPH::literals 让你可以写 0.0_r 得到随 JPH_DOUBLE_PRECISION 自动切换为 double/float 的 Real 类型。

2. 全局初始化:分配器、回调、工厂与类型注册

RegisterDefaultAllocator();          // 注册默认内存分配器,必须在任何 Jolt 调用之前

Trace = TraceImpl;                   // 安装自定义 trace 回调
JPH_IF_ENABLE_ASSERTS(AssertFailed = AssertFailedImpl;)  // 安装 assert 回调

Factory::sInstance = new Factory();  // 负责按名称/哈希创建类实例,主要用于反序列化

RegisterTypes();                     // 向 Factory 注册所有物理类型,并向 CollisionDispatch 安装碰撞处理器
  • 分配器钩子见 Jolt/Core/Memory.h,可覆盖 Allocate/Free/Reallocate/AlignedAllocate/AlignedFree 实现自定义内存管理;
  • trace/assert 回调的安装见 Jolt/Core/IssueReporting.h;
  • RegisterTypes()(RegisterTypes.h)内部会传递 JPH_VERSION_ID 做 ABI 版本校验;UnregisterTypes() 在退出时清理。如果有自定义 Shape 类型,需要在调用 RegisterTypes() 前注册其碰撞处理器;若实现了自定义默认材质 PhysicsMaterial::sDefault,也要先初始化。

3. 临时分配器与作业系统(多线程基础)

TempAllocatorImpl temp_allocator(10 * 1024 * 1024);   // 预分配 10MB 临时内存

JobSystemThreadPool job_system(cMaxPhysicsJobs, cMaxPhysicsBarriers,
                               thread::hardware_concurrency() - 1);
  • TempAllocatorImpl 预分配内存以避免物理更新过程中的运行时分配,10MB 对示例偏大,是典型工程值;也可用 TempAllocatorMalloc 直接回退到 malloc/free;
  • JobSystemThreadPool 是 JobSystem 接口的一个示例实现,Jolt 官方建议在实际项目中实现自己的 JobSystem 接口,让物理引擎跑在你自己的任务调度器上。cMaxPhysicsJobs/cMaxPhysicsBarriers 的默认值(2048 / 8)定义在 PhysicsSettings.h。

4. 初始化 PhysicsSystem:四个容量参数

const uint cMaxBodies = 1024;              // 最大刚体数,真实项目建议 ~65536
const uint cNumBodyMutexes = 0;            // 保护刚体的互斥锁数量,0 = 默认
const uint cMaxBodyPairs = 1024;           // 宽相检测到的候选刚体对缓冲上限,真实项目建议 ~65536
const uint cMaxContactConstraints = 1024;  // 接触约束缓冲上限,真实项目建议 ~10240

physics_system.Init(cMaxBodies, cNumBodyMutexes, cMaxBodyPairs, cMaxContactConstraints,
                    broad_phase_layer_interface, object_vs_broadphase_layer_filter,
                    object_vs_object_layer_filter);

四个容量参数的含义(对应 PhysicsSystem.h 的 Init 注释):

  • inMaxBodies:最多支持的刚体数量,超出会报错;
  • inNumBodyMutexes:刚体并发访问互斥锁数量,应为 [1, 64] 的 2 的幂,0 表示自动检测;
  • inMaxBodyPairs:同时处理的刚体对数量,通常应远大于接触点数(大量刚体彼此靠近但并未接触),否则"溢出的物体会穿透世界";
  • inMaxContactConstraints:最大接触约束数,超出后接触被忽略、刚体开始互相穿插或掉出世界。

后三个参数都传入的是虚接口实例,PhysicsSystem 只保存引用,因此这些实例必须在系统生命周期内保持存活。

5. 图层系统:三个过滤器

Jolt 通过三件套决定"谁和谁碰撞"(详见 HelloWorld.cpp 与 Samples 中更完整的 Samples/Layers.h):

namespace Layers {
    static constexpr ObjectLayer NON_MOVING = 0;
    static constexpr ObjectLayer MOVING = 1;
    static constexpr ObjectLayer NUM_LAYERS = 2;
};
  • ObjectLayer:对象所属的逻辑层,决定它与其他对象层是否碰撞,由 ObjectLayerPairFilter 实现 ShouldCollide;
  • BroadPhaseLayer:每个宽相层对应一棵独立的包围盒树。至少应区分"非移动"与"移动"两层,避免每帧更新装满静态物体的树。若层很多,可定义 JPH_TRACK_BROADPHASE_STATS 查看 TTY 上的统计来微调;多个对象层也可映射到同一个宽相层;
  • 三个过滤器接口分别是 BroadPhaseLayerInterface(对象层→宽相层映射)、ObjectVsBroadPhaseLayerFilter(对象层 vs 宽相层是否碰撞)、ObjectLayerPairFilter(对象层两两是否碰撞)。

Samples 的 Samples/Layers.h 展示了更完整的 8 层设计(含 DEBRIS 只与 NON_MOVING 碰撞、SENSOR 只与 MOVING 碰撞等玩法级分层)。若不想手写这三个接口,Jolt 还提供了更简单的表驱动/掩码实现:BroadPhaseLayerInterfaceTable、BroadPhaseLayerInterfaceMask、ObjectVsBroadPhaseLayerFilterTable、ObjectLayerPairFilterTable、ObjectLayerPairFilterMask(见 BroadPhase/ 与 Collision/ObjectLayerPairFilterTable.h)。

6. 可选监听器:接触与激活

MyBodyActivationListener body_activation_listener;  // OnBodyActivated / OnBodyDeactivated
physics_system.SetBodyActivationListener(&body_activation_listener);

MyContactListener contact_listener;                 // OnContactValidate / OnContactAdded / OnContactPersisted / OnContactRemoved
physics_system.SetContactListener(&contact_listener);

两个监听器都是可选的。注意它们从 job 线程回调,回调内的操作必须线程安全。OnContactValidate 允许在接触创建前忽略它(但用图层过滤更便宜)。接口定义见 BodyActivationListener.h 与 ContactListener.h。

7. 创建刚体:形状设置 → 形状 → 刚体设置 → 刚体

// 地板:一个 200x2x200 的大盒子(静态)
BoxShapeSettings floor_shape_settings(Vec3(100.0f, 1.0f, 100.0f));
floor_shape_settings.SetEmbedded();   // 栈上的引用计数对象需标记,防止引用计数归零时被释放
ShapeSettings::ShapeResult floor_shape_result = floor_shape_settings.Create();
ShapeRefC floor_shape = floor_shape_result.Get();

BodyCreationSettings floor_settings(floor_shape, RVec3(0.0_r, -1.0_r, 0.0_r),
                                    Quat::sIdentity(), EMotionType::Static, Layers::NON_MOVING);
Body *floor = body_interface.CreateBody(floor_settings);
body_interface.AddBody(floor->GetID(), EActivation::DontActivate);

// 小球:动态,用简写接口一步创建并加入世界
BodyCreationSettings sphere_settings(new SphereShape(0.5f), RVec3(0.0_r, 2.0_r, 0.0_r),
                                     Quat::sIdentity(), EMotionType::Dynamic, Layers::MOVING);
BodyID sphere_id = body_interface.CreateAndAddBody(sphere_settings, EActivation::Activate);

body_interface.SetLinearVelocity(sphere_id, Vec3(0.0f, -5.0f, 0.0f)); // 给小球一个向下初速度
  • 创建链路是"形状设置(Settings)→ 形状(Shape)→ 刚体设置(BodyCreationSettings)→ 刚体(Body)";简单形状也可直接构造(如 new SphereShape(0.5f));
  • BodyCreationSettings 里还可设置摩擦、恢复系数等属性;
  • EActivation::DontActivate / Activate 对应 README 中"刚体创建时不自动唤醒"的设计——地板不需要唤醒,小球需要立即参与模拟;
  • 所有与刚体的交互通过 BodyInterface(锁定版 GetBodyInterface() 或非锁定版 GetBodyInterfaceNoLock())进行。若先用 CreateBody 再 AddBody,可以在加入世界前直接对 Body 设置属性。

8. 模拟主循环

const float cDeltaTime = 1.0f / 60.0f;   // 60Hz 是推荐的物理步长

physics_system.OptimizeBroadPhase();     // 首次模拟前可选优化宽相(本例只有 2 个刚体,无意义)

uint step = 0;
while (body_interface.IsActive(sphere_id))
{
    const int cCollisionSteps = 1;       // 步长超过 1/60 秒时应增加碰撞子步数
    physics_system.Update(cDeltaTime, cCollisionSteps, &temp_allocator, &job_system);
}
  • Update(float inDeltaTime, int inCollisionSteps, TempAllocator*, JobSystem*) 是物理模拟的唯一入口:总时长被分成 inCollisionSteps 次迭代,每次迭代 = 碰撞检测 + 积分步;函数内部通过 JobSystem 派发并等待全部 job 完成,返回时不会再有运行中的 job(签名见 PhysicsSystem.h);
  • 从 PhysicsSystem.h 的私有 job 入口可看到一次 Update 内部的流水线:JobStepListeners → JobDetermineActiveConstraints → JobApplyGravity → JobSetupVelocityConstraints → JobBuildIslandsFromConstraints → JobFindCollisions → JobFinalizeIslands → JobSolveVelocityConstraints → JobIntegrateVelocity → JobFindCCDContacts/JobResolveCCDContacts → JobContactRemovedCallbacks → JobSolvePositionConstraints,以及软体相关的 JobSoftBodyPrepare/Collide/Simulate/Finalize;
  • OptimizeBroadPhase() 不应每帧调用,也不应在流式加载关卡区块时调用;批量插入(AddBodiesPrepare/AddBodiesFinalize)本身就能构建高效的包围体层次。

9. 清理

body_interface.RemoveBody(sphere_id);   // 从世界移除,刚体保留状态可随时重新加入
body_interface.DestroyBody(sphere_id);  // 销毁,之后 BodyID 失效
UnregisterTypes();                      // 注销类型并清理默认材质
delete Factory::sInstance;              // 销毁工厂

物理参数调优:PhysicsSettings 逐项解读

PhysicsSystem::SetPhysicsSettings / GetPhysicsSettings 控制模拟核心常量,全部字段与默认值见 PhysicsSettings.h:

字段 默认值 说明
mMaxInFlightBodyPairs 16384 同时处理的潜在刚体对数量;调低省内存但线程可能缺少窄相工作而变慢
mStepListenersBatchSize 8 每批通知的 PhysicsStepListener 数量
mBaumgarte 0.2 Baumgarte 稳定化系数(一次更新修正多大位置误差,0=不修正,1=100%)
mSpeculativeContactDistance 0.02 m 推测接触点检测半径;过大可能导致"幽灵碰撞"
mPenetrationSlop 0.02 m 允许刚体互相陷入的深度
mLinearCastThreshold 0.75 LinearCast 运动质量下,每步位移超过内半径的比例才启用投射
mLinearCastMaxPenetration 0.25 LinearCast 下允许的最大穿透比例
mManifoldTolerance 1.0e-3 m 判断两个接触点是否共面以合并接触流形的距离容差
mMaxPenetrationDistance 0.2 m 求解位置约束时单次迭代最多修正的距离
mNumVelocitySteps 10 速度迭代次数;需 ≥2 摩擦才能正确工作(摩擦使用上一迭代的非穿透冲量)
mNumPositionSteps 2 位置迭代次数
mMinVelocityForRestitution 1.0 碰撞恢复弹性的最小相对速度阈值,低于则恢复系数按 0 处理,让物体更快安定
mTimeBeforeSleep 0.5 s 进入睡眠前的静置时间
mPointVelocitySleepThreshold 0.03 m/s 用质心与包围盒远端面中心共 3 点判断入睡的速度阈值
mConstraintWarmStart true 约束热启动(沿用上一帧冲量)
mUseBodyPairContactCache true 刚体对相对姿态未变时复用窄相碰撞结果
mUseManifoldReduction true 合并法线相近的接触流形
mUseLargeIslandSplitter true 把大岛拆成可并行处理的小组以提升性能
mAllowSleeping true 是否允许刚体入睡
mCheckActiveEdges true 是否对非激活(共享)边做碰撞抑制,主要调试用

编译与构建:从脚本到 CMake 选项

完整的构建说明在 Build/README.md,仓库 Build/ 目录提供了各平台一键脚本:

平台 脚本
Windows MSVC(VS2026) cmake_vs2026_cl.bat(另有 32 位、ARM、ARM EC、double、no-object-stream 变体)
Windows MSVC Clang cmake_vs2026_clang.bat
Linux(make) cmake_linux_clang_gcc.sh
Linux(ninja) cmake_ninja.sh
Windows MinGW / MSYS2 cmake_windows_mingw.sh
macOS / iOS cmake_xcode_macos.sh / cmake_xcode_ios.sh
WebAssembly(Emscripten) cmake_linux_emscripten.sh

例如 Linux + ninja 的完整流程:

apt-get install clang cmake ninja-build
# 若构建 Samples/JoltViewer 或使用 ComputeSystem,还需安装 Vulkan SDK(含 dxc,见 ubuntu24_install_vulkan_sdk.sh)
./cmake_ninja.sh
cd Ninja_MultiConfig
cmake --build . --config Debug && ./UnitTests
./Debug/Samples

构建类型(Build Types)

  • Debug:开断言;
  • Release:无断言,含 profiling 支持,可绘制世界与模拟属性;
  • ReleaseASAN / ReleaseUBSAN / ReleaseTSAN / ReleaseCoverage:在 Release 基础上开启 Address/UndefinedBehavior/Thread Sanitizer 或覆盖率(仅 clang),用于找 bug;
  • Distribution:可发布版本,关闭全部调试支持。

关键编译宏(Defines)

JPH_* 系列宏控制功能开关,多数与同名 cmake 选项对应,三组要点:

通用选项(节选):

  • JPH_CROSS_PLATFORM_DETERMINISTIC:尝试跨平台确定性,开启后忽略 JPH_USE_FMADD;
  • JPH_DEBUG:额外内部检查,NDEBUG 未定义时默认开启;
  • JPH_DEBUG_RENDERER:支持绘制线条与三角形,用于调试绘制世界状态;
  • JPH_DOUBLE_PRECISION:所有位置改用 double,支持超大世界;
  • JPH_ENABLE_ASSERTS:编译期开启断言(否则失败被忽略);
  • JPH_OBJECT_LAYER_BITS:ObjectLayer 位宽,必须为 16 或 32;
  • JPH_OBJECT_STREAM:ObjectStream 序列化支持(示例代码常用);
  • JPH_PROFILE_ENABLED / JPH_EXTERNAL_PROFILE:内置/外置 profiler;
  • JPH_TRACK_BROADPHASE_STATS / JPH_TRACK_NARROWPHASE_STATS / JPH_TRACK_SIMULATION_STATS:向 TTY 输出宽相/窄相/逐刚体模拟统计;
  • JPH_SHARED_LIBRARY / JPH_BUILD_SHARED_LIBRARY:以共享库方式使用/构建 Jolt。

CPU 指令集:JPH_USE_SSE4_1、JPH_USE_SSE4_2、JPH_USE_AVX、JPH_USE_AVX2、JPH_USE_AVX512(默认关)、JPH_USE_F16C、JPH_USE_FMADD、JPH_USE_LZCNT、JPH_USE_TZCNT(x86/x64);JPH_USE_NEON(ARM64 默认开)、JPH_USE_RVV(RISC-V,默认关)。

Compute 后端:JPH_USE_CPU_COMPUTE(CPU 回退实现,主要调试用)、JPH_USE_DX12、JPH_USE_MTL、JPH_USE_VK,对应 Jolt/Compute/ 下的 DX12/MTL/VK/CPU 实现。

注意:指令集与功能宏必须与库保持一致,否则会产生链接错误(见下节)。cmake 侧 EMIT_X86_INSTRUCTION_SET_DEFINITIONS(Jolt.cmake)会把这些定义传播给子项目以避免不一致。

常见错误排查(来自 Build/README.md)

  • libJolt.a: file format not recognized:你的应用没有开启链接期优化(LTO)。开启 INTERPROCEDURAL_OPTIMIZATION cmake 选项(Jolt 静态库以 LTO 编译);
  • Apple 平台 Unknown header: 0xb17c0de:-flto=thin 产生 LLVM bitcode,打包进 XCFramework 会报错;将该选项置 OFF 即可(代价是失去跨翻译单元优化)。直接链接静态库不会触发此问题,可保持 ON;
  • unresolved external symbol ... GetSubmergedVolume:你的代码与库的宏不一致,典型是 JPH_DEBUG_RENDERER(Debug/Release 默认定义,Distribution 不定义)。可用 cmake 选项 DEBUG_RENDERER_IN_DEBUG_AND_RELEASE / DEBUG_RENDERER_IN_DISTRIBUTION 覆盖;
  • undefined symbol: typeinfo for JPH::DebugRenderer:RTTI 设置不匹配。Jolt 默认无 RTTI,若你的项目开 RTTI,要么关闭它,要么用 CPP_RTTI_ENABLED 给 Jolt 打开;
  • DirectX 错误 "The GPU device instance has been suspended":Windows 需在"可选功能"中安装 Graphics Tools;
  • Illegal instruction 异常:CPU 不支持编译时启用的指令。Linux 上 lscpu 查看 flags,然后关闭不支持的指令集,例如:
./cmake_linux_clang_gcc.sh Release clang++ \
  -DUSE_SSE4_1=OFF -DUSE_SSE4_2=OFF -DUSE_AVX=OFF -DUSE_AVX2=OFF -DUSE_AVX512=OFF \
  -DUSE_LZCNT=OFF -DUSE_TZCNT=OFF -DUSE_F16C=OFF -DUSE_FMADD=OFF

仓库目录结构导航

生态与集成

  • 其他语言绑定:C(多个社区实现)、C#(JoltPhysicsSharp)、Java/Kotlin、JavaScript(JoltPhysics.js)、Rust、Python、Zig、Jai,README 中均有对应仓库链接(见 README.md);
  • 引擎集成:Godot、Source Engine(VPhysics-Jolt)、以及多个 Unreal 插件;
  • 使用 Jolt 的项目清单:见 Docs/ProjectsUsingJolt.md。

许可证与贡献

项目以 MIT 许可证发布(见 LICENSE)。欢迎一切贡献:较大的改动建议先在 GitHub Discussion 中讨论;非平凡改动需要签署 ContributorAgreement.md,提交 PR 时 CLA assistant 会提示签署;所有 PR 合并前会被 squash,因此无需刻意保持提交历史整洁。

结语

从设计取舍(多线程并发访问、确定性、惰性唤醒)到功能矩阵(刚体、约束、角色、车辆、软体、GPU 头发、浮力、双精度),再到 HelloWorld 的完整接入流程,Jolt Physics 在"多核友好"与"游戏可用"之间做了清晰的取舍。若你的项目需要 C++17、无 RTTI/异常、仅依赖 STL 的轻量依赖物理方案,并且看重主模拟之外的高并发访问能力,那么从 README 出发、以 HelloWorld 为起点、用 Samples 与 UnitTests 作为学习与验证素材,是一条高效的实践路径。

登录后查看全文
JoltPhysics