orkige

# 奥奇吉 **奥奇吉游戏引擎** — 一款适用于桌面、移动和网络游戏的 C++20 游戏引擎（macOS、Windows、Linux、iOS、Android 和浏览器 via WebAssembly — 所有六种平台均通过 CI 验证），具有 AI 原生编辑器，允许代理创建、运行、测试和调试游戏，支持 MCP 服务。最初编写于 2009-2012 年，并在应用商店上发布（*Pudding Panic*），在 2026 年复兴并完全现代化。采用 [Apache-2.0](LICENSE) 许可。    -purple)  **网站和文档：** [orkige.orkitec.com](https://orkige.orkitec.com) — 本文档作为可搜索的站点，以及生成的 C++ API 参考。 ## 功能概述 一个完整的 3D 引擎，顶部有一个一流的 2D 层 — 不是 2D 引擎。 - **渲染** — 双后端架构：**Ogre-Next（默认 — macOS/iOS 上的 Metal，Android 上的 Vulkan）** 和经典 OGRE 14.6（桌面上的 GL3+，macOS 上的 Vulkan-via-MoltenVK，iOS/Android 上的 GLES2），像素级相同的输出在构建时选择，并通过一致性测试强制执行。SDL3 窗口/输入，glTF 资产加载（assimp）。自家 **gui** 运行时 UI 通过后端的 `DrawLayer2D` 渲染，因此它在 **两个** 后端上运行（与 ImGui 编辑器一样）— **显示比例感知** （文本和触摸目标在 2×-3× 屏幕上保持物理大小）和 **安全区域感知** （HUDs 在凹槽/首页指示器框内锚定），具有 **运行时烘焙 TTF 字体** （大型字符集的惰性字形分页）和 **矢量栅格化 UI 艺术** ，在任何密度下保持清晰，一个 **矩形锚点布局系统** （锚点/枢轴/拉伸，布局组，九切片和瓷砖面板，滚动视图，文本输入），以及整个屏幕作为声明式 **`.oui` 文件** — 每个屏幕一个代理可写文本文件。 - **场景模型** — GameObject/组件系统，具有 **父/子层次结构** 和活动/非活动状态，**预制件** （`.oprefab` 资产，具有实例级结构 + 属性覆盖，应用/恢复），**稳定 ID 资产数据库** （`.orkmeta` 边车文件，以便引用在重命名后存活），以及命名 XML 场景序列化（`.oscene`）。 - **2D 管道** — 精灵，**翻页动画** ，一个批处理的 **2D 粒子系统** （每个发射器一个绘制调用），精灵图集 + 每个平台的 **纹理导入设置** ，**平面矢量形状** （`.oshape` 路径资产或导入的 SVG，镶嵌抗锯齿边缘 — 分辨率无关有机艺术），可以 **挤压、拉伸、波动和变形** 为软体（物理驱动变形，约 4 µs 每形状每帧，变形姿势从 SVG 序列烹饪），以及正交 2D 相机，具有 **宽高比适应策略** （从 4:3 平板电脑到 21:9 手机的确定性构图）和画家顺序 z 排序。 - **物理引擎** — Jolt 物理引擎（具有平面“2D 模式”），数据驱动的 **碰撞层矩阵** ，对象 **标签** ，以及 **传感器/触发器接触事件** 传递给脚本（`onContactBegin`/`onContactEnd`）。 - **游戏玩法系统** — **命名输入操作** （按键/倾斜 → 操作，移动 + 桌面统一，具有 **倾斜校准** ），**音频混音器** （组 + 主混音）与 **流式 OGG 音乐** ，在关卡切换时存活，**补间/缓动库** ，**字符串表本地化** （Lua 中的 `loc()`），用于脚本的 **保存 API** （原子性，崩溃感知），**屏幕抖动，时间缩放和全屏渐变** ，**触觉** （iOS 和 Android 上的真实手机振动），**控制台变量** 用于实时调整，**崩溃记录** （一个持久的事件轨迹，在进程死亡时存活），一个定义的 **移动生命周期** （后台暂停，刷新和挂起；脚本获取 `onAppPause`/`onAppResume`），以及 **Lua 和 `.oui` 热重载** 在运行时（编译/解析前交换：损坏的保存保持旧版本运行）。 - **脚本** — sol2 背后的 Lua，具有后端中立的缝隙；游戏逻辑存在于每个对象的 `ScriptComponent` 中。`projects/roller` 是一个纯 Lua 的完整游戏，零编译代码。 - **编辑器** — 一个完整的场景创作工具，构建在引擎本身之上：嵌入式层次结构 / 检查器 / 控制台 / 统计 / RTT 场景视口，一个两窗格的 **资产浏览器** （文件夹树，纹理缩略图，创建/导入，拖放），一个 **2D 编辑器模式** （正交，平面锁定 gizmos），一个 **图块调色板和网格绘画** 用于基于图块的关卡（绘制/擦除预制实例，每个笔画一个撤销步骤），带有 Q/W/E/R 的变换 gizmos，撤销/重做，多选，原生 macOS 菜单 + 文件对话框，以及帮助 > 奥奇吉帮助，打开引擎的 **已发布文档站点** ，位于 [orkige.orkitec.com](https://orkige.orkitec.com)。作为 `Orkige.app` 发布。 - **运行时调试** — 运行时调试以单独进程运行，基于 TCP 调试协议：实时远程层次结构/检查器，暂停/逐步/停止，实时属性 + 控制台变量编辑，脚本热重载。崩溃的游戏永远不会导致编辑器崩溃。相同的协议可用于 **iOS 模拟器，Android 设备和浏览器** — 按下播放，选择目标，在那里调试正在运行的游戏（浏览器选项卡通过 WebSocket 调用相同的协议）。 - **AI 原生** — 编辑器公开一个 **模型上下文协议（MCP）** 服务器，以便 AI 代理可以打开项目，编辑场景，添加/重新父对象，驱动播放，并读取状态和视口截图（参见 `Docs/mcp.md`）。 - **项目和移动** — 游戏是一个带有 `project.orkproj` 清单，场景，资产，脚本和可选项目配置资产的文件夹；编辑器打开项目，播放器运行它们，构建菜单导出可分发的 macOS `.app`，iOS 模拟器应用，Android APK 或 **自包含浏览器构建** （WebAssembly + WebGL，可从任何静态主机提供）— 每个项目都有 **图标和启动屏幕** ；可提交商店的 Android 应用包和签名的 iOS `.ipa` 只需一个 CLI 标志即可创建。配置了 Apple 开发者证书后，播放直接部署到 **真正的 iPhone** （签名导出 + 安装 + 启动）。 - **示例** — `samples/hello_orkige` （功能演示）和 `samples/jumper` （一个有纹理的跳跃运行）；`projects/` 包含真正的游戏，重点是 **`roller`** （一个 2D 物理谜题：倾斜重力球 + 滑动世界瓷砖，多级进度与移动持久保存）。 ## 构建 需要 CMake ≥ 3.28，Ninja 和 [vcpkg](https://github.com/microsoft/vcpkg) 在 `~/Development/vcpkg` （或设置 `VCPKG_ROOT`），以及 python3 ≥ 3.10 用于开发时的资产/构建工具（仅限标准库 — 发布的游戏永远不需要 Python）。所有依赖项都来自 vcpkg 清单 — 没有任何内容被移植，没有系统安装的内容被使用（例外：MoltenVK 作为 macOS 上的 Vulkan 驱动程序，`brew install molten-vk`）。 ```sh cmake --preset macos-debug # 配置（第一次运行构建依赖项） cmake --build --preset macos-debug # 构建 ctest --preset desktop # 验证 open build/macos-debug/tools/editor/Orkige.app # 编辑器（使用 macos-release 以获得速度） ./build/macos-debug-classic/samples/jumper/jumper # 运行 jumper（经典树） ``` 预设：`macos-debug`，`macos-release` 构建 **默认 Ogre-Next 渲染后端** ；`macos-debug-classic`，`macos-release-classic` 构建完全支持的 **经典 OGRE 兼容性版本** — 它仍然拥有原生游戏模块和 Vulkan 运行时选择，并且两个版本必须渲染像素相同的输出（通过一致性测试强制执行），并将项目导出。发布预设下工作在编辑器中时速度快约 19 倍。移动预设：`ios-simulator-debug`，`android-debug` 是 Ogre-Next（iOS 上的 Metal，Android 上的 Vulkan — 默认）；`ios-simulator-debug-classic`，`android-debug-classic` 构建经典 GLES2 移动版本。部署流程在 CLAUDE.md 中有记录。 ## 测试 所有内容都通过自检测试套件验证（Catch2 单元测试 + 应用级集成运行，断言真实行为 — 渲染的三角形计数，物理位置通过调试协议测量，截图转储）： ```sh ctest --preset unit # 无头单元测试（~3s） ctest --preset desktop # 默认（Ogre-Next）套件 ctest --preset desktop-classic # 经典风格套件（导出，Vulkan，原生模块） ctest --preset all # 经典 + 模拟器/模拟设备测试 ``` 每次推送都会运行一个 **十二作业 CI 矩阵** — 每个平台 × 风格一个作业，因此失败的作业会自行命名（`.github/workflows/ci.yml`）。两个 Linux 渲染风格都在虚拟显示下运行其完整的窗口化套件；Ogre-Next 还拥有无脚本和 ASan + UBSan 传递。macOS（Metal）和 Windows（Mesa lavapipe 软件 Vulkan）运行完整的桌面套件。Android 播放器在硬件加速的 x86_64 模拟器中运行，iOS 播放器在 arm64 iPhone 模拟器中运行 — 而且 **浏览器播放器构建为 WebAssembly，并在无头 Chrome 中启动，带有像素检查** ，每次推送。 ## 仓库布局 ``` orkige_core/ 平台无关的核心：元/类型系统，事件，游戏对象，序列化，Lua 脚本，调试网络协议，项目 orkige_engine/ 面向 OGRE 的层：图形，输入，声音，物理，GUI tools/editor/ 奥奇吉编辑器 tools/player/ 独立运行时（桌面，移动，网络） samples/ hello_orkige，jumper projects/ .orkproj 游戏项目（roller，benchmark，jumper-lua，...） tests/ 单元测试 + 集成套件 Util/ 资产生成器 + 构建/导出工具（python，仅限标准库） ports/ triplets/ vcpkg 叠加端口和三元组 Docs/ 文档集（在 orkige.orkitec.com 上发布） ``` 现代工作发生在 `main` 上；深层历史承载了引擎的 2009-2012 年起源。原始引擎上发布的游戏存放在私有档案中。 ## 上游 在复兴期间发现的修复程序会回馈 OGRE 和 Ogre-Next；直到修复程序在固定的发布版本中发布，它们作为文档化的叠加端口补丁被携带。运行记录 — 每个 PR，其状态和匹配的补丁生命周期 — 存放在 [Docs/ports.md](Docs/ports.md) 中。 ## 许可证 Apache License 2.0 — 参见 [LICENSE](LICENSE)。© 2009–2026 orkitec / Steffen Römer 及贡献者。