面向实时路径追踪、游戏原型与高质量视觉表现的跨平台 3D 引擎
gkNextEngine 是一个基于现代 C++20 与 Vulkan 的跨平台 3D 游戏引擎 / 渲染实验场，重点放在两件事上：
- 用 实时路径追踪、Hybrid Rendering 与 HDR 光照表现 做出真正有展示力的画面
- 用 可运行、可扩展、可用于游戏原型验证的引擎能力 支撑长期演进，而不是停留在单点 demo
项目以渲染器能力为核心，同时持续扩展编辑器、脚本、物理、内容导入与玩法原型。LDraw / BrickPlayer 是当前很有代表性的内容方向：引擎层可以直接导入 LDraw 模型，并把这类结构化资产纳入统一的 Runtime、渲染与交互系统。
如果你关注以下方向，这个项目会比较值得参考：
- 想看实时路径追踪、金属 / 玻璃 / 塑料材质、HDR 环境光和高密度场景的实际画面
- 想研究一套更贴近游戏运行时的 Vulkan 渲染架构，而不是只会离线出图的 demo
- 想看一个引擎如何把 渲染、编辑器、脚本、物理、内容导入与玩法原型 串成完整系统
- 想读一套规模可控、强调工程清晰度、适合学习现代 Vulkan 渲染与引擎实现的代码库
支持平台： Windows x86_64 · Linux x86_64 · macOS arm64 · Android arm64 · iOS arm64
-
实时路径追踪与 Hybrid Rendering
围绕 1spp + temporal reuse、降噪、重投影和多管线切换持续推进，让路径追踪不只停留在离线效果演示，而是面向真实运行时表现。 -
游戏级性能取向的 GPU 架构
通过 Visibility Buffer、全 Bindless、GPU-Driven、Multi-Draw Indirect 等设计，尽量把 CPU 开销留给内容与玩法，把 GPU 算力用在真正影响画面的地方。 -
引擎能力服务于内容与玩法原型
包括 ECS、反射、编辑器、脚本热重载、物理同步、运行时导入和稳定的渲染行为。这些能力共同支撑更完整的可玩内容系统。 -
多格式内容导入与互操作
引擎完整支持 glTF 运行时导入，并支持部分导出；同时也可以直接导入.ldr/.mpd，将结构化的 LDraw 场景纳入统一的 Runtime、渲染与交互系统。
- 实时路径追踪：围绕 1spp + temporal reuse 持续推进，关注真实运行时条件下的画面质量与可用性能
- Hybrid Rendering：在移动平台与游戏级工况下，把传统光栅与光追做合理混合
- 多套渲染器热切换：同一套资产与场景，可直接切换不同管线做对比和验证
- HDR 截图与高质量素材导出：便于做视觉验证、展示与回归对比
- ECS + Reflection：基于 entt 的组件系统，加上反射层，服务于运行时、编辑器和脚本绑定
- ImGui 编辑器：
gkNextEditor面向材质、场景和运行时内容的编辑工作流 - QuickJS 脚本热重载：运行时使用仓库内置
tools/tsc/tsc[.exe]编译 TypeScript（Windows 为tsc.exe，macOS/Linux 为tsc），无需 Node/npm 或全局tsc - Jolt Physics：为交互原型、拖拽玩法和游戏化验证提供更真实的物理基础
- 目标代码规模 < 50k LOC：当前代码量仍然保持在便于理解和持续演进的区间
- 优先清晰实现而非过度设计：尽量用明确的数据流、职责边界和成熟三方库解决问题
- 适合阅读现代引擎实现：从 Vulkan 渲染、资源管理到脚本、编辑器、反射与测试链路，都能看到较完整的工程组织方式
- glTF 完整导入：面向运行时支持 glTF 场景、材质、动画、骨骼蒙皮等完整内容导入
- glTF 部分导出：支持将部分运行时内容回写到 glTF 工作流
- LDraw 直接导入 Runtime：
.ldr/.mpd可直接进入 Runtime - 颜色与材质映射：从
LDConfig.ldr、LGEO realistic color 到引擎 PBR 材质的完整映射 - Shadow / Connector 抽象：不是只导入网格，而是开始把零件连接语义转换成搭建系统可理解的数据
- Visibility Buffer
- 全 Bindless + GPU-Driven
- Multi-Draw Indirect
- Hardware / Software Ray Tracing
- Temporal Reprojection / JBF / OIDN / DLSS RR
- 现代 CMake Presets + vcpkg
- 跨平台运行时：桌面 / Android / iOS
- ImGui Editor + Node-based Material Workflow
- QuickJS Runtime Scripting
- Visual Test / Benchmark / Packager
- 内置 AI Agent 基础设施，可扩展运行时 LLM 能力
- 使用 Codex 进行引擎基础设施与示例 Demo 的原生开发
- 放弃 low-code 叙事，转向更直接的 agentic coding 工作流
示例截图
| 场景 | 截图 |
|---|---|
| still |  |
| livingroom |  |
| ldrawlego |  |
| luxball |  |
| brickplayer |  |
项目使用 CMake + Ninja，依赖由 vcpkg 管理。除了宿主机本身必须具备的基础工具（编译器 / IDE、CMake、平台 SDK 等），项目级依赖、外部工具链和可选资源包现在都尽量交给 gnb 准备。构建依赖下载阶段需要可访问 GitHub 的网络环境。
- 推荐先执行
./gnb doctor（Windows:gnb.bat doctor）检查宿主机缺失的基础工具 ./gnb setup（Windows:gnb.bat setup）会准备 vcpkg、项目外部工具链与可选资源包；如果直接执行./gnb build，首次缺少 toolchain 时也会自动补齐核心依赖- 桌面平台现在通过
gnb统一构建和运行，通常不再需要先cd到out/build/<platform>/bin - 可用 CMake 预设收敛为：
windows、linux、macos-arm64、ios
Windows (Visual Studio 2022)
前置条件：
- CMake 3.26+
- Visual Studio 2022（C++ 工作负载）
- Vulkan SDK 1.4.313.2
- 启用“使用 Unicode UTF-8 提供全球语言支持”
gnb.bat setup
gnb.bat build
gnb.bat run gkNextRenderer除 Visual Studio / Vulkan SDK 这类宿主工具外，其余项目依赖通常都由 gnb 自动准备。
Linux (Ubuntu)
./gnb.sh setup
./gnb.sh build
./gnb.sh run gkNextRenderer- 在 apt / pacman 环境下，
gnb setup与 Linux 首轮gnb build会在 vcpkg bootstrap 前自动安装桌面构建所需系统包 - 如果自动安装不可用，再手动补齐：
sudo apt install build-essential cmake ninja-build curl zip unzip tar pkg-config libxi-dev libxinerama-dev libxcursor-dev libxrandr-dev wayland-protocols libxkbcommon-dev xorg-dev autoconf autoconf-archive automake libtool libsystemd-dev - 非 apt/pacman 发行版仍会给出缺失桌面依赖提示
Steam Deck / Arch Linux
./gnb.sh setup
./gnb.sh build --reconfigure
./gnb.sh run gkNextRenderer说明：
- 如果机器上还没有
slangc，gnb setup会自动下载项目约定的 Slang 工具链到external/ - 在 pacman 环境下，
gnb setup/ Linux 首轮gnb build会在 vcpkg bootstrap 前自动安装系统包；如果自动安装不可用，可手动执行sudo pacman -S --needed base-devel cmake ninja curl zip unzip tar pkgconf libxrandr wayland-protocols libxkbcommon systemd-libs - 如果 vcpkg 阶段遇到 GitHub 归档下载失败，优先直接重试同一条构建命令
- 一次真实 Steam Deck 部署的复盘见 docs/steamdeck-deployment-notes.md
macOS
前置条件：
- Xcode / Command Line Tools
- CMake 3.26+
- Ninja（如果本机的 CMake 发行版未自带）
./gnb.sh setup
./gnb.sh build
./gnb.sh run gkNextRenderergnb setup 会自动下载项目使用的 Slang 与 TypeScript 工具链，无需再单独准备这些项目级依赖。
Android (Windows 构建)
前置条件： JDK 17+、Android SDK、NDK r27
set ANDROID_HOME=C:\Android\Sdk
set ANDROID_NDK_HOME=C:\Android\Sdk\ndk\27.0.12077973
gnb.bat setup --vcpkg-only
gnb.bat androidAndroid 主机侧仍需要提供 JDK / SDK / NDK；项目内的 vcpkg 依赖与外部工具链则继续由 gnb 处理。
# 主渲染器
./gnb.sh run gkNextRenderer
# Editor
./gnb.sh run gkNextEditor
# BrickPlayer（数字乐高 / LDraw 搭建原型）
./gnb.sh run BrickPlayer
# CharacterDemo（角色控制 / AI / 导航实验）
./gnb.sh run CharacterDemo部分较大的二进制资源不随仓库提交，需要按需拉取：
| 选择器 | 内容 | 落盘位置 | 缺失影响 |
|---|---|---|---|
ldraw |
ldraw.pak |
assets/paks/ |
BrickPlayer 缺 LDraw 零件库 |
optional |
optional.pak |
assets/paks/ |
主渲染器 / Editor / CharacterDemo / MagicaLego 缺场景资源 |
sfx |
6 个 mp3/wav | assets/sfx/ |
MagicaLego / BrickPlayer 静音 |
ffmpeg |
ffmpeg.exe |
src/ThirdParty/ffmpeg/bin/ |
Windows 下 MagicaLego 视频录制不可用 |
# Linux / macOS / Git Bash：默认拉取全部可选资源
./gnb.sh paks fetch
# 或只拉指定资源
./gnb.sh paks fetch optional ldraw
./gnb.sh paks fetch ffmpeg sfx
# Windows
gnb.bat paks fetch| 项目 | 说明 |
|---|---|
gkNextRenderer |
主渲染器，路径追踪 / Hybrid Rendering / 多管线对比 |
gkNextEditor |
ImGui 编辑器，服务于材质、场景与运行时工具链 |
BrickPlayer |
基于 LDraw 的数字乐高搭建原型 |
CharacterDemo |
角色控制、AI 行为、导航与战斗交互实验 |
MagicaLego |
更轻量的乐高 / voxel 风格玩法实验场 |
gkNextStillBenchmark |
静态场景渲染基准测试 |
gkNextMotionBenchmark |
动态场景渲染基准测试 |
gkNextVisualTest |
自动化视觉测试与截图报告 |
Packager |
资产打包为 .pkg |
欢迎 Issue / PR。
- 开发协作说明见
AGENTS.md - 如果你对实时路径追踪、现代渲染架构、LDraw、编辑器工具链、AI Native 工作流或玩法原型验证感兴趣，欢迎交流
cpptrace · cxxopts · sdl3 · glm · imgui · stb · curl · nlohmann-json · tinygltf · draco · fmt · meshoptimizer · ktx · joltphysics · xxhash · spdlog · cpp-base64 · catch2 · entt · libwebp · vulkan-loader · libavif