Repo ↗ · 原始 README ↗ · 文件包（Markdown／授權）

來源維護者： erincatto · 版本： 5d83df83ab47 · 整理日期： 2026-10-12

文件授權： MIT · LICENSE · 本文形式： README 翻譯

下文為來源 README 的繁中翻譯，由 Kirikirin 使用 AI 輔助整理；功能、完成度與測試結果均為原作者描述，本站未逐項實機驗證。圖片改為來源連結，指令與技術識別保留原文。

Box3D

[README 圖片：Build Status](https://github.com/erincatto/box3d/actions)
[README 圖片：CLA assistant](https://cla-assistant.io/erincatto/box3d)

README 圖片：Box3D Logo

Box3D 是一款用於遊戲的 3D 物理引擎。

[README 圖片：Introducing Box3D](https://www.youtube.com/watch?v=jr_Fzl2XwKU)

功能

碰撞

  • 連續碰撞偵測
  • 接觸事件
  • 凸包、膠囊、球體、三角形網格和高度場
  • 每個剛體可有多個形狀
  • 碰撞過濾
  • 射線投射、形狀投射和重疊查詢
  • 感測器系統
  • 角色移動器

物理

  • 穩健的 Soft Step 剛體求解器
  • 針對快速平移和旋轉的連續物理
  • 基於島嶼的睡眠
  • 旋轉、平移、距離、馬達、焊接和車輪關節
  • 關節限制、馬達、彈簧和摩擦
  • 關節和接觸力
  • 剛體移動事件和睡眠通知

系統

  • 資料導向設計
  • 以可攜式 C17 撰寫
  • 大量多執行緒和 SIMD
  • 針對大量剛體堆疊進行最佳化
  • 跨平台確定性
  • 錄製和重播

範例

  • 使用 sokol 在 Windows 上以 D3D11、macOS 上以 Metal、Linux 上以 OpenGL 4.5 執行。
  • 使用 imgui 的圖形化使用者介面。
  • 許多範例可展示功能和效能。

建置所有平台

  • 安裝 CMake
  • 安裝 git
  • 確保這些可從命令列執行

使用 CMake 預設集建置（建議）

這會使用 CMakePresets.json 中的預設集。

  • Windows：cmake --preset windows 然後 cmake --build --preset windows-release
  • Linux：cmake --preset linux-release 然後 cmake --build --preset linux-release
  • macOS：cmake --preset macos 然後 cmake --build --preset macos-release
  • Windows MinGW：cmake --preset mingw-release 然後 cmake --build --preset mingw-release

執行範例應用程式（必須在 Box3D 目錄中）。

  • Windows：.\build\bin\Release\samples.exe
  • Linux：./build/bin/samples
  • macOS：./build/bin/Release/samples

為 Visual Studio 建置

  • 安裝 Visual Studio
  • 執行 build_vs2026.bat
  • 開啟並建置 build/box3d.slnx

為 Linux 建置

  • 從 bash shell 執行 build.sh
  • 結果位於 build 子資料夾中

為 Xcode 建置

  • mkdir build
  • cd build
  • cmake -G Xcode …
  • 開啟 box3d.xcodeproj
  • 選取 samples scheme
  • 建置並執行範例

為 Web 建置

  • Emscripten SDK
  • emcmake cmake -B build -DBOX3D_SAMPLES=OFF
  • cmake --build build

Box3D 在 WebAssembly 中使用 SSE2。定義 BOX3D_DISABLE_SIMD 以停用 SSE2。

建置和安裝

  • mkdir build
  • cd build
  • cmake …
  • cmake --build . --config Release
  • cmake --install .（可能需要 sudo）

在您的專案中使用 Box3D

核心程式庫除了 C 執行階段（以及 Unix 上的 libm）之外沒有其他相依性。連結它
即可獲得 box3d::box3d 目標。

我建議使用 FetchContent：

include(FetchContent)
FetchContent_Declare(box3d
  GIT_REPOSITORY https://github.com/erincatto/box3d.git
  GIT_TAG v0.1.0)
FetchContent_MakeAvailable(box3d)

target_link_libraries(my_app PRIVATE box3d::box3d)

若是 vendored 副本或 git 子模組，請將 add_subdirectory 指向它：

add_subdirectory(extern/box3d)

target_link_libraries(my_app PRIVATE box3d::box3d)

若要使用以 cmake --install 安裝的副本，請尋找套件：

find_package(box3d 0.1 REQUIRED)

target_link_libraries(my_app PRIVATE box3d::box3d)

請參閱 docs/hello.md 以取得最小的第一個程式。

相容性

Box3D 程式庫和範例可在 Windows、Linux 和 Mac 上建置並執行。

您將需要支援 C17 的編譯器來建置 Box3D 程式庫。

您將需要支援 C++20 的編譯器來建置範例。

Box3D 使用 SSE2 和 Neon SIMD 數學來提升效能。可透過定義 BOX3D_DISABLE_SIMD 來停用 SIMD。

在 x86 上，當 CPU 支援時，會在執行階段選用 AVX2 核心。使用 -DBOX3D_AVX2=OFF 進行設定以停用它們。

文件

使用者手冊位於 docs/，並使用 Doxygen 建置。啟用 BOX3D_DOCS CMake 選項並建置 doc 目標。

社群

貢獻

目前停用提取要求。請改為針對錯誤或功能要求提交 issue。如需支援，請造訪 Discord 伺服器。

提供意見回饋

請提交 issue 或在 discord 上開始聊天。您也可以使用 GitHub Discussions。

授權

Box3D 由 Erin Catto 開發，並使用 MIT 授權。

贊助

透過 Github Sponsors 支持 Box3D 的開發。

請考慮為此儲存庫加星，並訂閱我的 YouTube 頻道。

LLM 使用

LLM 用於以下領域：

  • 單元測試
  • 範例應用程式
  • 在 Box2D 和 Box3D 之間遷移程式碼
  • 建置設定
  • 程式碼審查
  • 基準測試

在其他地方，所有程式碼均由我開發和撰寫。我對 Box2D/3D 中的每一行程式碼負責。

授權與來源聲明

原始 README 與翻譯沿用 MIT 授權；本次修改為繁中翻譯、連結與排版調整。可修改的 Markdown、原始 README、LICENSE 與 NOTICE 收錄於頂部文件包。原作遊戲內容與商標不因此獲得授權。

LICENSE

MIT License

Copyright (c) 2026 Erin Catto

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.