简介：面向VS2017 64位环境下的三维仿真与游戏开发场景，该资源提供了一套编译完成的OSG、osgWorks、Bullet3及osgbullet库。它解决了开发者在Windows平台自行编译这些开源库时步骤繁琐、版本匹配困难的问题，可直接集成到C++工程中。包体为RAR压缩格式，整体约228MB，核心内容包括动态库（.dll）与静态库（.lib）两类产物，并配有相应头文件，方便工程以不同方式链接。已有801人学习下载，适合具备一定C++基础、正在搭建渲染与物理引擎工作流的开发者。其中Bullet3负责高效碰撞检测与刚体动力学解算，osgbullet则作为桥接层，使物理世界与OpenSceneGraph图形场景同步联动，能够快速实现物体跌落、碰撞反弹等可交互效果。资源还包含osgWorks扩展模块，可丰富场景表现力。通过使用这套编译好的库，可显著缩短项目前期环境配置时间，更专注于上层功能开发。

1. VS2017 64位下这套库的编译链路：它解决的是一整条依赖，不是一个命令

在 VS2017 的 64 位环境里，把 osg、osgWorks、bullet3、osgBullet 这四套东西串起来编译成动态库和静态库，是很多 OSG 用户做碰撞检测时的第一道坎。原因很简单：OSG 自带的 IntersectionVisitor 只解决“射线与模型求交”，解决不了两个刚体之间的碰撞、反弹、摩擦。osgBullet 把 Bullet 物理引擎封装成 OSG 节点，但 osgBullet 又依赖 osgWorks 做节点辅助，osgWorks 依赖 osg，bullet3 是唯一的底层物理引擎。决定用这条方案的从业者，通常已经确认 bullet3 的碰撞检测能力比自己去写包围盒精确得多，也认了花费两三个小时按顺序把这几个库编出来、调通链接参数的成本。这篇文章就按我实际在 VS2017 x64 下做的事写：每个库的 CMake 配置、动态/静态库的分支，以及我踩过的链接和运行期坑。

2. 编译前的选型与依赖顺序：先决定动态库还是静态库，再动手

2.1 bullet3 的碰撞检测能力：为什么 OSG 自带求交器替代不了

OSG 的 osgUtil::IntersectionVisitor 适合做射线拾取、视锥裁剪，它本质是几何求交：给一条射线或一个平面，返回场景中相交的三角形。这类检测适合鼠标点选、可见性判断，但做不了物理碰撞。比如一辆小车在斜坡上侧翻，车身持续和地面接触，姿态变化每一步都依赖上一帧的速度和质量；你不可能每帧对所有三角形对做完整相交，那性能会直接崩掉。

Bullet3 用的是另一种模型：碰撞体是 box、sphere、convex hull、static plane 这类形状，而不是原始网格。引擎维护每个刚体的速度、角速度、质量、碰撞响应，按固定时间步推进，输出接触点、法线和穿透深度。这套能力在 robotics、机械臂防碰撞、仿真训练里已经验证了很多年；opencv 和 unreal 的物理模块都吸收过类似思路。把它接到 OSG 里的意义在于：渲染继续用 OSG 的节点树，物理计算交给 Bullet，两者之间由 osgBullet 做双向同步。

常见误区是以为 osgBullet 是一个独立的物理引擎。实际上 osgBullet 是胶水层，它把 Bullet 的刚体对象和 OSG 的 MatrixTransform 绑定：你移动 OSG 节点，物理世界里的刚体也跟着移动；物理世界 step 一步，再反向把新姿态写回 OSG 节点。所以这里的“碰撞检测”效果，最终取决于 Bullet 的碰撞算法，而不是 osg 的求交代码。

2.2 VS2017 x64 工具链检查：CMake 生成器、工作负载和命令行验证

VS2017 默认使用 v141 工具集，对应 CMake 里的生成器是 “Visual Studio 15 2017 Win64”。注意别选成 Win32，那会生成 32 位库；也别选成 “Visual Studio 15 2017” 不带 Win64，默认 x86。如果机器上还装了 vs2019、vs2022，CMake 可能会自作主张选新的生成器，所以命令行里一定要写全。

安装 VS2017 时，很多人只选了 Python 或 Web 开发，没勾 “使用 C++ 的桌面开发”，后面打开 CMake 配置时找不到 v141 编译器，只能重装。正确的工作负载里要包含 MSVC v141 编译器和 “Windows 10 SDK”。装完以后打开 “Developer Command Prompt for VS2017”，先验证环境：

cl /? cmake --version

正常输出里 cl 会显示 “x64” 还是 “x86”。如果显示 x86，说明打开的是 32 位开发者命令提示符，请在开始菜单里选 “x64 Native Tools Command Prompt for VS2017”。这里的版本差异非常关键，后面所有库的库文件都会带着平台标记，你混一个 x86 的 lib 进 x64 工程，链接器报的错会非常难查。

CMake 版本建议高于 3.12。更早的版本对 VS2017 的 “Ninja + Clang” 支持不完整，用 Visual Studio 生成器倒是问题不大。我一般直接用官方最新稳定版，同时把系统 PATH 里的旧 CMake 清理掉，避免 CMake GUI 和命令行版本不一致，生成出来的 cache 互相覆盖。四个库的源码目录不要有空格和中文路径，比如 D:/src/osg、D:/src/bullet3。路径带空格会让 CMake 的 find_path 系列命令在某些模块里抽风，是玄学问题的高发区。

2.3 动态库与静态库的预判：一个决定后面所有 CMake 开关的分支表

在动手之前，先想清楚你要给谁用。如果只是自己团队内部链接，动态库省心；如果要交付给客户，或者客户环境不允许你安装 VS2017 运行时，那静态库更省事。但注意，静态库不是把所有东西塞进一个 lib 就完了，运行库和预处理器宏必须配套。

在 Windows 上，MSO 的/MD和/MT混用是最典型的崩溃源。MSVC 的 debug 模式默认用/MDd，release 用/MD，如果你编译 osg 时用了/MT（多线程静态运行库），而你的应用是/MD，那么 STL 容器和堆分配器在不同二进制之间传递内存，运行到 string 赋值或 vector 析构时直接 0xC0000005。这条依赖贯穿 osg、osgWorks、bullet3、osgBullet 四个库，必须全部一致。

我常用的策略是：先决定主输出版本。团队应用是 release /MD，那么所有第三方库都编译成 release /MD。如果确实需要 debug 库，就四个库整体再编一遍 debug /MDd，不要 debug 应用链接 release 库，也不要 release 应用链接 debug 库。这个决定做得越早，后面避坑越少。

3. 逐个编译 bullet3、osg 与 osgWorks：CMake 配置和最小命令

3.1 bullet3 编译命令与输出布局

Bullet3 本身定位就是物理引擎，不依赖 OSG，所以第一个编译它最合适。它编译快，库文件也少。你下载的源码根目录里会有一个 CMakeLists.txt，打开看 option 的名称，不同 release 的开关名略有差别。比较常见的是 BUILD_BULLET2_DEMOS 和 BUILD_EXAMPLES，有时候两个都存在，老版本喜欢用前者。建议关闭示例和测试，只留库，编译时间能缩短大半。

在 x64 Native Tools Command Prompt 里建一个独立 build 目录，然后执行：

mkdir D:/build/bullet-x64 cd D:/build/bullet-x64 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/bullet3 ^ -DBUILD_SHARED_LIBS=ON ^ -DBUILD_BULLET2_DEMOS=OFF ^ -DBUILD_UNIT_TESTS=OFF ^ -DCMAKE_BUILD_TYPE=Release ^ D:/src/bullet3 cmake --build . --config Release --target INSTALL

这里的BUILD_SHARED_LIBS=ON会生成动态库。如果你要的是静态库，把它改成 OFF 再编译，这是最关键的动态/静态分支。CMAKE_INSTALL_PREFIX是安装目录，不是源码目录，后面 osgBullet 找依赖全靠这个目录。

编译完成后去 D:/3rdparty/bullet3 看目录布局：include 下是头文件，lib 下是 .lib，bin 下是 .dll。Bullet3 的 CMake package 会把 BulletConfig.cmake 放在 lib/cmake/bullet 下，这样 osgBullet 可以用 find_package(Bullet) 找到它。如果安装目录里没有 cmake 子目录，说明 INSTALL 没执行成功，或者你的 Bullet 版本很老。老版本通常只有头文件和库，没有 package 文件，那 osgBullet 的 CMake 会报 Could NOT find Bullet，后面我们手动指路径。

注意别用源码目录里的 build 直接编译，多项目同时构建时，CMakeCache.txt 相互干扰。每个库一个独立 build 目录，这个习惯能救你很多次。

3.2 osg 编译开关：DYNAMIC_OPENSCENEGRAPH 与插件

OSG 是这条链里最重的库。源码 OpenSceneGraph 的 CMake 配置项很多，但我们只需要关注几个和后续链接强相关的。DYNAMIC_OPENSCENEGRAPH=ON决定 OSG 本体是动态库，这个开关建议保持 ON，因为 osgDB 的插件系统设计上就是动态加载，如果把这个关了，大部分第三方插件都连不起来。BUILD_OSG_APPLICATIONS=ON会编译 osgviewer、osgconv 这些工具，我建议开，后面加载模型、转格式、验证场景图都要用。BUILD_OSG_EXAMPLES=OFF关掉示例，缩短编译时间。

另外一个容易被忽略的是CMAKE_USE_WIN32_API=ON。在 Windows 上 OSG 默认会用 Win32 API 处理事件和窗口，如果误关了，后面的 osgViewer 在 viewer.run() 时可能崩溃。新版 OSG 也有用 GLFW 的错误示范，但既然你在 VS2017 里用，就老老实实走 Win32。

命令如下：

mkdir D:/build/osg-x64 cd D:/build/osg-x64 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/osg ^ -DDYNAMIC_OPENSCENEGRAPH=ON ^ -DBUILD_OSG_APPLICATIONS=ON ^ -DBUILD_OSG_EXAMPLES=OFF ^ -DCMAKE_USE_WIN32_API=ON ^ D:/src/OpenSceneGraph cmake --build . --config Release --target INSTALL

OSG 编译时间比较长，第一次建议只编译 Release，先别碰 Debug。编译完成后，安装目录里会有 bin/osgviewer.exe，bin/osgPlugins-3.x 下有一堆 plugin 的 dll，lib 下有一批 .lib。如果你下载的 OSG 版本较新，CMake 里还分出了 osgDB 和 osgUI 子库；如果不看 plugin 目录，不知道有没有加载成功。验证方式很简单：

D:/3rdparty/osg/bin/osgviewer.exe D:/3rdparty/osg/bin/osglogo.osg

能弹出一个可旋转的 logo 窗口，说明 OSG 本体和插件系统是正常的。

这里还要提一句 zlib、libpng、libjpeg 依赖。OSG 在编译插件时会检查这些库，找不到就跳过对应格式插件。如果你后面要加载 .obj，其实不依赖 png/jpeg；要加载带贴图的模型，就建议通过 vcpkg 装上 zlib、libpng、libjpeg 和 freetype。装好后重新跑 CMake，它会自动发现 vcpkg 目录里的依赖，不需要太多手动干预。

3.3 osgWorks 编译：通过 CMAKE_PREFIX_PATH 找到 osg

osgWorks 这个库在 osg 圈子里熟悉的人相对少，它提供了一些方便的工具集，比如节点浅拷贝、事件处理辅助、视口切换等等。osgBullet 内部会使用 osgWorks 的规则来把 OSG 节点转成 Bullet 碰撞体，所以这条依赖躲不开。编译 osgWorks 时，只要确保它 find_package(OpenSceneGraph) 能找到 osg 的安装路径。新版 OpenSceneGraph 会把 OpenSceneGraphConfig.cmake 放到安装目录的 lib/cmake/OpenSceneGraph 下，所以 CMAKE_PREFIX_PATH 指到 D:/3rdparty/osg 就行。

我一般这么干：

mkdir D:/build/osgWorks-x64 cd D:/build/osgWorks-x64 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_PREFIX_PATH=D:/3rdparty/osg ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/osgWorks ^ -DBUILD_SHARED_LIBS=ON ^ D:/src/osgWorks cmake --build . --config Release --target INSTALL

如果 CMake 还不认，可以在 CMake GUI 里搜 OpenSceneGraph_DIR，手动指到 D:/3rdparty/osg/lib/cmake/OpenSceneGraph。老版本 osgWorks 的 FindOpenSceneGraph.cmake 写的没那么智能，它可能要求你填 OSG_INCLUDE_DIR 和 OSG_LIBRARY。遇到这种情况，打开 CMake GUI，把三个变量一起填：include 目录、lib 目录、bin 目录。指向后 Configure 会变红，把红色项都填完，Generate 出来再用 VS 编译。

这里有一个大坑：osgWorks 构建时如果找不到 OSG，CMake 会继续但自动禁用 osgWorks 的某些源文件，最后生成一个空壳库。你编译成功却没有任何 osgWorks 符号，链接 osgBullet 时才知道凉了。所以编译完后一定要检查生成的 .lib 文件大小，如果只有几 KB，重新检查上面的依赖路径。一个正常的 osgWorks release 动态库导入 .lib 在几十 KB 左右，静态库更高。

4. 编译 osgBullet 并让动态库和静态库并存：CMake 配置、产物检查与验证

4.1 osgBullet 的依赖查找：手动指路径的方案

当 bullet3、osg、osgWorks 三个库都安装好以后，编译 osgBullet 才能顺利。osgBullet 源码包里通常有以下子目录：osgbCollision、osgbDynamics、osgbInteraction、osgbTerrain、osgbSolid 等，名字里的 osgb 前缀就是 osgBullet。它会分别生成对应的 .lib 和 .dll，核心是 osgbCollision 和 osgbDynamics。

先试标准做法，把三个 prefix 都塞给 CMAKE_PREFIX_PATH：

mkdir D:/build/osgBullet-x64 cd D:/build/osgBullet-x64 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_PREFIX_PATH="D:/3rdparty/osg;D:/3rdparty/osgWorks;D:/3rdparty/bullet3" ^ -DBUILD_SHARED_LIBS=ON ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/osgBullet ^ D:/src/osgBullet cmake --build . --config Release --target INSTALL

如果 CMake 报 Could NOT find Bullet，或者 Could NOT find osgWorks，说明某个库安装时没有生成 cmake config 文件。常见的处理是到 CMake GUI 里手动添加BULLET_INCLUDE_DIR和BULLET_LIBRARY_RELEASE。BULLET_INCLUDE_DIR 指向包含 btBulletDynamicsCommon.h 的那一级目录，通常是 D:/3rdparty/bullet3/include/bullet。BULLET_LIBRARY_RELEASE 指向 lib 下的一个核心库，比如 BulletDynamics.lib。注意 osgBullet 找 Bullet 的方式在不同版本里还分为 Bullet 和 Bullet3 两种 package 名，如果第一条命令失败了，观察 CMakeError.log，它会告诉你具体卡在哪个 Find 脚本上。

对于 OSG，旧指令是设置OpenSceneGraph_DIR。对于 osgWorks，一般会设置osgWorks_DIR。CMAKE_PREFIX_PATH 和具体 xxx_DIR 是互不排斥的，能填具体地址就不依赖 PATH 搜索，减少玄学。

4.2 两个 build 目录分别出动态库和静态库：别再改 CMakeCache

很多人的需求是动态库和静态库都要。比如团队内部开发用动态库，项目部署时换成静态库。最可靠的做法是建两个 build 目录，分别跑一次 CMake，分别指定不同的 BUILD_SHARED_LIBS 值。不要在同一个目录里把 BUILD_SHARED_LIBS 从 ON 改成 OFF 直接生成，CMakeCache.txt 会保留大量上次配置的中间路径，生成出来的 output 目录混乱，甚至多个 target 链接错乱。

两个目录的命令差别只在 BUILD_SHARED_LIBS 和安装前缀：

:: 动态库版 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_PREFIX_PATH="D:/3rdparty/osg;D:/3rdparty/osgWorks;D:/3rdparty/bullet3" ^ -DBUILD_SHARED_LIBS=ON ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/osgBullet-dyn ^ D:/src/osgBullet

:: 静态库版 cmake -G "Visual Studio 15 2017 Win64" ^ -DCMAKE_PREFIX_PATH="D:/3rdparty/osg;D:/3rdparty/osgWorks;D:/3rdparty/bullet3" ^ -DBUILD_SHARED_LIBS=OFF ^ -DCMAKE_INSTALL_PREFIX=D:/3rdparty/osgBullet-stat ^ D:/src/osgBullet

注意：这里的静态库版，只是 osgBullet 本身是静态库。osg、osgWorks、bullet3 仍然可以保持动态库，因为静态库在链接时会把依赖 dll 的导入信息带进生成物。也就是说静态 osgBullet 库在最终链接你的应用时，仍然会要求操作系统在运行期能找得到 osg 的 dll，这是很多人理解错的地方。如果你真要全静态，需要把 osg、osgWorks、bullet3 的 BUILD_SHARED_LIBS 全部改为 OFF，并且 OSG 的 DYNAMIC_OPENSCENEGRAPH 也要关掉；这个组合的插件系统会有新的坑，建议除非部署环境极端受限，否则不要轻易走全静态路线。

更现实的做法是：给用户交付时，静态链接 osgBullet 和 bullet3，但 OSG 自身仍然用动态库。因为 osg 的插件系统注定了很难做全静态压缩，强行静态 osg 会让 osgDB 读不了模型格式。所以网上常见的 osg 全静态说法大多是宣传话术，落地时反噬很重。

4.3 验证产物：用 dumpbin 看库类型和依赖

编译完成并不代表库能直接用。先到安装目录检查文件。动态库版本下，osgBullet 的 lib 文件夹里会出现 osgbCollision.lib、osgbDynamics.lib 等文件，bin 下对应的是 osgbCollision.dll。静态库版本下，D:/3rdparty/osgBullet-stat/lib 里只有一堆很大的 .lib，没有对应的 .dll。

用 dumpbin 验证库架构和类型：

dumpbin /headers D:/3rdparty/osgBullet-dyn/lib/osgbDynamics.lib | findstr "machine DLL"

输出里能看到 “machine (x64)” 和 FILE HEADER VALUES 中包含 DLL 字样，这就是动态库的导入库。如果只有 machine x64 而没有 DLL 字样，那是静态库。还可以看：

dumpbin /dependents D:/3rdparty/osgBullet-dyn/bin/osgbDynamics.dll

这个命令会列出该 DLL 依赖的其它 DLL，比如 osg*.dll、bullet 的 dll。如果依赖里出现 osgw.dll 或 osgWorks，说明 osgWorks 编进去了；如果只有 OpenThreads.dll 和 osgCore 的 dll，那 osgBullet 里可能有些功能没被编译，回头查 osgWorks 是不是空壳库。

验证完库本身，还要验证你的测试工程，可以用一个最简单的 CMakeLists.txt：

cmake_minimum_required(VERSION 3.12) project(physics_test) set(CMAKE_PREFIX_PATH "D:/3rdparty/osg;D:/3rdparty/osgWorks;D:/3rdparty/osgBullet-dyn;D:/3rdparty/bullet3") find_package(OpenSceneGraph REQUIRED) find_package(Bullet REQUIRED) find_package(osgWorks REQUIRED) add_executable(physics_test main.cpp) target_link_libraries(physics_test osgbDynamics osgbCollision)

这里的 find_package(osgWorks) 和 target_link_libraries 里的 osgbDynamics 是 CMake 目标名，如果 osgBullet 没有安装 package 文件，也可以用绝对路径链接 lib。但用绝对路径要小心 debug/release 同名库，最好在配置阶段用 generator expression 区分，否则 debug 链接成 release 库又是崩溃现场。

5. 编译 osgBullet 常见问题排查：链接失败、运行崩溃、穿透抖动

5.1 现象：LNK2019 unresolved external symbol osgbDynamics 相关符号

现象：编译你自己的碰撞检测程序时，报几十个 LNK2019，符号名里都带 osgbDynamicsDynamicsWorld 或 osgbCollision 前缀。原因多半是链接器输入里少了 osgbDynamics.lib 和 osgbCollision.lib，或者误把源码目录里的 build 产物当成安装目录的库。另一个可能是 osgBullet 生成的是静态库，但你的工程没有定义对应的 OSGBULLET_STATIC 宏，导致头文件里的 dllimport 声明和静态库符号不匹配。

解决：先用 dumpbin /exports 查看 osgbDynamics.lib 里的导出符号，确认这个库真的有内容；然后在工程的预处理定义里，根据 osgBullet 头文件顶部的条件编译标记，补上静态库需要的宏。不同版本可能用 OSGBULLET_STATIC 或 OSGBULLET_LIBRARY_STATIC，直接打开 osgbDynamicsExports.h 看，它会在 #ifdef 里提示你定义哪个。最终在 CMake 里用 target_compile_definitions 加进去，不要在源码手工 define。

5.2 现象：链接通过，运行时报“无法加载 DLL”或 0xC000007B

现象：链接毫无错误，一运行就弹窗找不到 osgBullet.dll 或 osgViewer.dll，点确定后进程退出；有时候报 0xC000007B（应用程序无法正常启动）。原因很直白：DLL 搜索路径没覆盖安装目录。Windows 加载 DLL 的顺序是 exe 所在目录、系统目录、PATH 环境变量。VS2017 调试环境下只把 exe 所在目录放进去，而你的 osg 和 osgBullet 全在 D:/3rdparty 下，自然找不到。

解决：在 VS 工程“调试”配置里把环境变量 PATH 设为：

PATH=D:/3rdparty/osg/bin;D:/3rdparty/osgWorks/bin;D:/3rdparty/osgBullet-dyn/bin;D:/3rdparty/bullet3/bin;$(PATH)

或在 main 函数开头调用 SetDllDirectory，指定每个 dll 所在目录。不要用 Copy 到系统目录这种办法，系统目录权限会和杀毒软件打架。另一个隐蔽点：64 位进程只能加载 64 位 dll，如果你链接的某个依赖是 x86，表现为 0xC000007B；用 dumpbin /headers 逐个检查 dll 的 machine 字段。

5.3 现象：CMake 反复提示 Could NOT find Bullet 或 Could NOT find osgWorks

现象：配置 osgBullet 时，尽管你确定已经安装了 Bullet3，CMake 还是报找不到。原因：你安装 Bullet3 的时候只编译了 ALL_BUILD，没有执行 INSTALL 目标；或者安装目录里确实没有 cmake package 文件。新版 Bullet3 会把 BulletConfig.cmake 放在安装目录的 lib/cmake/bullet 下，而 osgBullet 的 FindBullet 脚本可能从旧版复制来的，它优先找 BULLET_INCLUDE_DIR 和 BULLET_LIBRARY 两个变量。

解决：回到 CMake GUI，把 BULLET_INCLUDE_DIR 设置为 D:/3rdparty/bullet3/include/bullet，把 BULLET_DYNAMIC_LIBRARIES 设置为 D:/3rdparty/bullet3/lib/BulletDynamics.lib，BULLET_COLLISION_LIBRARIES 设为 BulletCollision.lib，BULLET_MATH_LIBRARIES 设为 LinearMath.lib。设置后再 Configure，看 CMakeCache.txt 里的 Bullet_DIR 是否被认出来。如果仍然失败，打开生成的 CMakeError.log，看具体是哪个 try_compile 没过，多数情况是头文件路径给得太深或太浅。

5.4 现象：碰撞检测结果不对，球体直接穿透地面，或者贴地抖动

现象：运行你的 osg+bullet 场景，球体从空中落下，却直接穿过地面，或者在地面附近疯狂抖动，接触面没有明显反弹。原因有两个维度。第一，Bullet 默认使用离散碰撞检测，一个 fast moving object 在一帧内位移超过碰撞体厚度，就不会被检测到穿透。第二，你没有给 DynamicsWorld 设置固定时间步，stepSimulation 每帧传的 dt 是渲染帧时间，帧率波动大，物理求解不稳定。

解决：为高速物体（球体、子弹、车辆）启用 CCD（连续碰撞检测）：

bulletBody->setCcdMotionThreshold(0.5); bulletBody->setCcdSweptSphereRadius(0.2);

同时在每次 stepSimulation 时，用固定步长分解：

world->stepSimulation(dt, 4, 1.0 / 60.0);

第二个参数最大子步数，第三个参数固定步长。这意味着无论渲染帧率是 30 还是 200，物理都按 60Hz 推进，不会因为掉帧导致穿透。另一个常见问题是碰撞组掩码没设，默认所有物体都互相碰撞；如果你把地面和球的 collisionGroup 都设成 0，Bullet 会认为它们在同一个碰撞组，反而忽略了 static 环境，导致穿模。

5.5 现象：Debug 和 Release 混合链接，运行期 _ITERATOR_DEBUG_LEVEL 不匹配

现象：在 Debug 配置下编译你的程序，链接时没有报错，但运行到 STL 容器构造或字符串比较时直接崩溃，崩溃点随机，有时候在 osg 内部。原因：第三方库编成 Release 使用 /MD，你的 Debug 程序使用 /MDd，两者之间的 STL 符号定义不同，内存布局也不同。比如 std::string 在 debug 和 release 下内部成员变量多了 debug 标记，你从 release 库返回一个 string，在 debug 程序里析构就是未定义行为。

解决：要么把 osg、osgWorks、bullet3、osgBullet 全编一遍 Debug 库，要么让你的程序也用 Release 配置。把四套库的 debug 版本全部安装到 D:/3rdparty/xxx-debug，然后在你的 CMake 里用 debug 配置指向 debug 库，release 配置指向 release 库。千万不要图省事只编一套 release 库然后 debug 应用去链接，这属于省时间一时爽，调试一晚上。另外注意 VS2017 默认的运行库设置，在 属性 -> C/C++ -> 代码生成 -> 运行库 里，确认四个库和你自己的工程都是 “多线程 DLL (/MD)” 或 “多线程调试 DLL (/MDd)”，交叉搭配非常难排查。

6. 碰撞检测接入验证：一个小球落到地面的最小场景

当所有库编译完成，并且你的测试程序能正常链接运行后，最后一步是在 OSG 场景树里接上 osgBullet。这里用一个最小场景验证碰撞检测链路是否真的通了：地面上方放一个球体，让它自由落体，观看到达地面后是否停止。为了保证代码可复现，下面是核心骨架：

#include <osg/ShapeDrawable> #include <osg/MatrixTransform> #include <osgViewer/Viewer> #include <osgbDynamics/DynamicsWorld.h> #include <osgbCollision/CollisionShapes.h> int main() { osg::ref_ptr<osg::Group> root = new osg::Group; osg::ref_ptr<osg::MatrixTransform> floor = new osg::MatrixTransform; floor->addChild(osg::createShapeGeode(new osg::Box(osg::Vec3(0, 0, -0.5), 10, 10, 1))); root->addChild(floor.get()); osg::ref_ptr<osg::MatrixTransform> ball = new osg::MatrixTransform; ball->addChild(osg::createShapeGeode(new osg::Sphere(osg::Vec3(0, 0, 3), 0.5))); root->addChild(ball.get()); osg::ref_ptr<osgbDynamics::DynamicsWorld> world = new osgbDynamics::DynamicsWorld; world->setGravity(osg::Vec3(0, 0, -9.81)); world->addNode(root.get()); osgViewer::Viewer viewer; viewer.setSceneData(root.get()); viewer.setUpViewInWindow(100, 100, 800, 600); double last = 0.0; while (!viewer.done()) { double now = viewer.getFrameStamp()->getReferenceTime(); double dt = now - last; world->stepSimulation(dt, 4, 1.0 / 60.0); world->syncNodes(); last = now; viewer.frame(); } return 0; }

这里的 addNode 和 syncNodes 是 osgBullet 不同版本里出现过的接口名。有些版本叫 DynamicsWorld::addRigidBody，有些直接用 addNode 自动创建刚体。按你下载头文件里的真实声明调整即可。逻辑不难：先把 OSG 节点注册进物理世界，物理引擎根据节点的包围盒或碰撞形状生成 Bullet 刚体；每帧先用固定步长推进物理，再把 Bullet 刚体的新姿态写回对应的 MatrixTransform。

验证方法不复杂：如果球体落地后停在 y=0.5，不再继续下沉，说明碰撞响应已经工作。如果球体下落时没有碰到地面直接穿出，按避坑 5.4 的方法给刚体开 CCD。如果想确认每次碰撞是否触发回调，可以用 DynamicsWorld 的 setInternalTickCallback 或 contactAddedCallback 打印 contact manifold 信息。

最后说一条我自己的教训：第一次把 osgBullet 接进项目时，我把 osg 编成动态库、osgBullet 编成静态库，却忘了在工程里加 OSGBULLET_STATIC 宏，链接器把静态库里的符号忽略了一半，查了整整一天才发现是导入导出宏不一致。后来我把这套环境固化成一串批处理文件，每次新机器上重编，只跑一遍脚本，再没因为库本身翻车。希望帮到你。

本文还有配套的精品资源，点击获取