Jolt Physics:多核友好刚体物理引擎特性解析与 C++ 实战集成指南
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_OPTIMIZATIONcmake 选项(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
仓库目录结构导航
- Assets:TestFramework、Samples、JoltViewer 使用的资源(字体、着色器、赛道 CSV、人体/地形数据等);
- Build:构建脚本与说明,见 Build/README.md;
- Docs:库文档(Samples.md、Architecture.md、ReleaseNotes.md、APIChanges.md、PerformanceTest.md、ProjectsUsingJolt.md 等);
- HelloWorld:最小使用示例,见 HelloWorld/HelloWorld.cpp;
- Jolt:库的全部源码(核心在 Jolt/Core、Jolt/Math、Jolt/Physics);
- JoltViewer:可视化
DebugRendererRecorder录制的.jor物理输出文件(跨平台对比 PerformanceTest 结果时很有用),目前支持 Windows/macOS/Linux; - PerformanceTest:性能测试应用,见 Docs/PerformanceTest.md;
- Samples:示例应用(Windows/macOS/Linux),见 Docs/Samples.md。运行后按 P 暂停/继续,ESC 打开菜单可切换测试、调整物理与绘制设置、发射小球(B 键)等;
- TestFramework:可视化物理结果的渲染框架,被 Samples 与 JoltViewer 共用(Windows/macOS/Linux);
- UnitTests:验证物理引擎行为的单元测试套件(UnitTests/),例如 Physics/PhysicsTests.cpp、Physics/PhysicsDeterminismTests.cpp,是理解各子系统正确行为与预期边界的绝佳参考。
生态与集成
- 其他语言绑定: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 作为学习与验证素材,是一条高效的实践路径。