Piccolo Engine 编译构建与开发环境搭建完全指南:从零构建 GAMES104 迷你游戏引擎

原创2026-10-14 14:33:551,438 阅读
文章标签:游戏开发图形学3D渲染

Piccolo Engine 编译构建与开发环境搭建完全指南:从零构建 GAMES104 迷你游戏引擎

Piccolo Engine 是 GAMES104 游戏引擎课程配套的迷你游戏引擎(前身为 Pilot Engine),采用 C++17 与 Vulkan 技术栈,以 CMake 驱动多平台构建。本文以仓库根目录 README.md 为主线,完整覆盖 Windows / macOS / Ubuntu 三平台的前置依赖安装、工程生成与编译命令,并深入源码层解析构建脚本、CMake 组织方式、编辑器配置与进阶调试选项(Vulkan 验证层、compile_commands.json、物理调试渲染器),读完即可在本地复现完整构建并上手开发。

Piccolo Engine 是什么

Piccolo Engine 定位是面向教学场景的迷你游戏引擎,用于 [GAMES104] 课程(课程主页见 README.md 顶部链接),仓库描述为 "mini game engine for games104"。从源码结构可以推断,它并非单线程的渲染示例,而是一套包含运行时(Runtime)与编辑器(Editor)双层架构的完整引擎骨架:

  • 运行时核心位于 engine/source/runtime,包含 engine.cpp 主循环(logicalTick → swapLogicRenderData → rendererTick)、core(数学库、日志、元数据反射)、function(动画、角色、物理、粒子、渲染、UI、输入等子系统);
  • 编辑器位于 engine/source/editor,基于 ImGui 实现场景管理、输入管理与 UI 面板(见 editor.cpp 与 editor_ui.cpp);
  • 渲染后端采用 Vulkan + RHI 抽象层(rhi.h),渲染管线在 render_pipeline.cpp 中同时实现了 forward 与 deferred 两套流程,并包含 FXAA、色调映射、色彩分级、点/平行光阴影、粒子、UI 合成、拾取(pick)等多个 Pass。

构建成功后,产出物为 PiccoloEditor.exe / PiccoloEditor(可执行编辑器),运行时所需的资源与配置由 bin 目录统一组织。

构建前的环境准备

README 明确了三平台的工具链基线,这是构建的硬性前提:

Windows 10/11

依赖 版本要求
Visual Studio 2019 或更新
CMake 3.19 或更新
Git 2.1 或更新

Windows 上 CMake 会生成 Visual Studio 解决方案(项目配置见 CMakeLists.txt,要求 cmake_minimum_required(VERSION 3.19 FATAL_ERROR),并启用 C++17)。注意 engine/CMakeLists.txt 中针对 MSVC 开启了 /MP 并行编译,并将 PiccoloEditor 设为 VS 启动项目,方便直接 F5 运行。

macOS >= 10.15(x86_64)

依赖 版本要求
Xcode 12.3 或更新
CMake 3.19 或更新
Git 2.1 或更新

硬件限制:README 明确声明,macOS 的构建说明仅在 x86_64 硬件上验证过,暂不支持 M1 芯片(后续版本会提供兼容支持)。构建时 CMake 将生成 Xcode 工程。

Ubuntu 20.04

需要安装如下系统包(README 原样列出):

sudo apt install libxrandr-dev
sudo apt install libxrender-dev
sudo apt install libxinerama-dev
sudo apt install libxcursor-dev
sudo apt install libxi-dev
sudo apt install libglvnd-dev
sudo apt install libvulkan-dev
sudo apt install cmake
sudo apt install clang
sudo apt install libc++-dev
sudo apt install libglew-dev
sudo apt install libglfw3-dev
sudo apt install vulkan-validationlayers
sudo apt install mesa-vulkan-drivers

此外还需安装 NVIDIA 驱动(README 说明:AMD 与 Intel 驱动为开源驱动,已随 mesa-vulkan-drivers 自动安装,NVIDIA 则需手动安装)。这些依赖与引擎的渲染栈一一对应:libvulkan-dev / mesa-vulkan-drivers 提供 Vulkan 运行时,libglfw3-dev 对应窗口系统层(window_system.cpp 直接调用 GLFW API),libglew-dev 服务于物理调试渲染器的旧式渲染,libxrandr/xrender/xinerama/xcursor/xi 则是 GLFW 在 X11 下工作所需的扩展库。

三种平台的完整构建流程

构建 Windows

最简方式:直接执行仓库根目录的 build_windows.bat。该脚本会自动生成工程并以 Release 配置编译,成功后可在 bin 目录找到 PiccoloEditor.exe。脚本内容(build_windows.bat)只有两步:

cmake -S . -B build
cmake --build build --config Release

也可以手动分步执行,先生成 Visual Studio 工程再打开解决方案构建:

cmake -S . -B build

构建 macOS

先用 CMake 生成 Xcode 工程:

cmake -S . -B build -G "Xcode"

再编译(--config Release 指定 Release 配置;Debug 同理):

cmake --build build --config Release

或直接运行 build_macos.sh,脚本接受一个参数指定配置:

./build_macos.sh release    # 等价于 cmake --build build --config " Release"
./build_macos.sh debug

从 build_macos.sh 源码可见,脚本内部同样执行 cmake -S . -B build -G "Xcode",随后按传入参数调用 cmake --build build --config "<Debug|Release>",非法参数会输出用法并退出。

构建 Ubuntu 20.04

直接运行 build_linux.sh:

./build_linux.sh release

脚本用法为 ./build_linux.sh <config> [build-tool],其中:

  • config:debug 或 release(对应 -DCMAKE_BUILD_TYPE=Debug/Release);
  • build-tool(可选):make(Unix Makefiles)或 ninja(Ninja)。不指定时自动检测:系统存在 ninja 则默认使用 Ninja,否则回退到 Unix Makefiles。

脚本关键行为(源码佐证,build_linux.sh):

mkdir -p "engine/shader/generated/spv"        # 预建着色器输出目录

export CC=clang
export CXX=clang++
cmake -S . -B build "${CMAKE_ARG_BUILD_TYPE_CONFIG}" "${CMAKE_ARG_BUILD_TOOL_TYPE_CONFIG}" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build "${MY_DIR}/build" -- all -j$(nproc)

值得注意的两点:

  1. 强制使用 clang 工具链:脚本显式 export CC=clang / CXX=clang++,这是引擎在 Linux 上默认推荐的编译器组合;
  2. 预创建 SPIR-V 目录:着色器在构建期由 glslangValidator 编译为 .spv 并进一步生成 .h 头文件(见 ShaderCompile.cmake 与 engine/shader/CMakeLists.txt),engine/shader/generated/spv 目录若不存在会导致编译失败——这正是 ReleaseNotes 中曾修复的 "Shader 目录不存在可能导致编译失败" 问题;
  3. 自动导出 compile_commands.json:-DCMAKE_EXPORT_COMPILE_COMMANDS=ON 让 Linux 构建默认附带编译数据库,直接受益于 clangd 等语言服务器。

构建产物与 bin 目录

根 CMakeLists.txt 将 CMAKE_INSTALL_PREFIX 指向 ${PICCOLO_ROOT_DIR}/bin,即所有产物、资源与配置统一落在 bin 下。运行 PiccoloEditor 时,程序按 main.cpp 中的逻辑,从可执行文件同目录加载 PiccoloEditor.ini 配置文件(configs/development/PiccoloEditor.ini),其中通过相对路径声明了资源根目录、默认世界、全局渲染/粒子配置等关键入口:

BinaryRootFolder=../../../../../bin
AssetFolder=asset
SchemaFolder=schema
BigIconFile=resource/PiccoloEditorBigIcon.png
SmallIconFile=resource/PiccoloEditorSmallIcon.png
FontFile=resource/PiccoloEditorFont.TTF
DefaultWorld=asset/world/hello.world.json
GlobalRenderingRes=asset/global/rendering.global.json
GlobalParticleRes=asset/global/particle.global.json
JoltAssetFolder=jolt-asset

从 config_manager.cpp 源码看,BinaryRootFolder 会被解析为可执行文件父目录下 ../../../../../bin 的实际路径,随后 AssetFolder 等键值均以此为根拼接。0.0.7 版本发布说明中"运行时不再依赖硬编码路径,bin 目录可整体打包拷贝"即源于此设计。

构建系统与工程组织(源码级解读)

根 CMake 工程

CMakeLists.txt 定义了工程级约束:

  • CMake 最低版本 3.19(FATAL_ERROR 强制校验);
  • C++17 标准(set(CMAKE_CXX_STANDARD 17)),静态库构建(BUILD_SHARED_LIBS OFF);
  • 禁止源码内构建:PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR 时直接报错,要求使用独立 build 目录;
  • 仅包含一个子工程 add_subdirectory(engine)。

引擎子工程

engine/CMakeLists.txt 是核心组织层:

  • 定义了可选的 ENABLE_PHYSICS_DEBUG_RENDERER(默认 OFF),且仅 Windows 平台支持——非 Windows 平台打开该选项会被强制关闭并发出警告;
  • 按平台定位 Vulkan SDK 头文件/库与 glslangValidator 可执行文件(Windows 的 vulkan-1.lib、macOS 的 libvulkan.1.dylib + MoltenVK、Linux 的 libvulkan.so.1);
  • 子目录顺序:shader(着色器编译目标 PiccoloShaderCompile)→ 3rdparty → source/runtime → source/editor → source/meta_parser,并建立依赖链 PiccoloRuntime → PiccoloPreCompile → PiccoloParser,确保反射代码生成先于运行时编译。

第三方依赖

engine/3rdparty 采用源码随仓库分发的方式(git submodule 式),3rdparty/CMakeLists.txt 中按需引入:

  • JoltPhysics:物理引擎(JoltPhysics,含 200+ 物理源码文件),并依据 ENABLE_PHYSICS_DEBUG_RENDERER 决定是否编译其 TestFramework;
  • glfw:窗口/输入,构建时关闭 examples/tests/docs;
  • imgui:编辑器 UI(imgui.cmake);
  • spdlog:日志;
  • stb / tinyobjloader:图像加载与 OBJ 网格解析;
  • VulkanSDK / vulkanmemoryallocator:Vulkan 头文件与 VMA;
  • sol2 + lua-5.4.4 + json11:Lua 脚本与 JSON 序列化(游戏中对象资产、LuaComponent 脚本均由此支撑)。

着色器编译链

所有 GLSL 着色器(engine/shader/glsl 下的 .vert/.frag/.comp/.geom)在构建期被 ShaderCompile.cmake 逐一处理:先由 glslangValidator -I<include> -V100 编译为 .spv,再由 GenerateShaderCPPFile.cmake 生成内嵌 SPIR-V 的 .h 文件(如 particle_emit_comp.h),运行时通过头文件直接取用着色器字节码(见 particle_pass.cpp 的 include 方式)。

编辑器运行与示例关卡

构建成功后运行 PiccoloEditor,默认加载 hello.world.json 世界,其唯一关卡为 1-1.level.json:

{
  "gravity": { "x": 0, "y": 0, "z": -15 },
  "character_name": "Player",
  "objects": [ ... ]
}

关卡中摆放了 Player(角色)、Emitter(GPU 粒子发射器)、Wall_1..17、WallWithDoor_*、Ground、Stairs、Fence 等对象;每个对象由 TransformComponent(位置/旋转/缩放)实例化组件叠加 definition 指向的对象定义资产(如 player.object.json 中声明了 Animation、Mesh、Motor、Camera、Lua 等组件)。引擎主循环在 engine.cpp 中按"逻辑 tick → 逻辑/渲染数据交换(swapLogicRenderData)→ 渲染 tick → 物理调试渲染(可选)→ 轮询事件"的顺序运转,窗口标题会实时显示 FPS。

若需调整全局渲染参数(FXAA 开关、天空盒 HDR、方向光、相机配置等),可修改 rendering.global.json;粒子参数(发射间隔、粒子数、时间步长、重力)在 particle.global.json 中配置。其中 enable_fxaa 的取值会沿 render_system.cpp → render_pipeline_base.h → main_camera_pass 一路传递(见 render_system.cpp 中的 pipeline_init_info.enable_fxaa = global_rendering_res.m_enable_fxaa),从而在 main_camera_pass.cpp 中控制 FXAA Pass 的创建与执行。

进阶开发配置

Vulkan Validation Layer:Validation Error

README 记录了一个常见问题:部分 Windows 开发者运行 PiccoloEditor.exe 正常,但调试时抛出异常 Vulkan Validation Layer: Validation Error。解决办法是安装官方最新版 Vulkan SDK(engine/3rdparty/VulkanSDK 仓库自带的是精简头文件与库,完整验证层由 SDK 提供)。

生成编译数据库(compile_commands.json)

compile_commands.json 是 clangd 语言服务器(Emacs cpp lsp-mode 的后端)所需的编译信息文件,可用如下命令生成(需要 Unix Makefiles 生成器可用):

Windows PowerShell:

cmake -DCMAKE_TRY_COMPILE_TARGET_TYPE="STATIC_LIBRARY" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S . -B compile_db_temp -G "Unix Makefiles"
copy compile_db_temp\compile_commands.json .

仓库同时提供了封装脚本 scripts/generate_compile_db.bat,内容与上述命令等价。-DCMAKE_TRY_COMPILE_TARGET_TYPE="STATIC_LIBRARY" 用于规避交叉环境下 CMake 链接探测失败的问题;Linux 下 build_linux.sh 已在生成阶段默认带上 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON,无需额外操作。

使用物理调试渲染器(仅 Windows)

物理调试渲染器当前仅 Windows 可用,用于可视化 Jolt 物理场景。生成带该项目的解决方案:

cmake -S . -B build -DENABLE_PHYSICS_DEBUG_RENDERER=ON

启用后,engine/CMakeLists.txt 会额外设置 JOLT_ASSET_DIR=/jolt-asset(对应 PiccoloEditor.ini 中的 JoltAssetFolder=jolt-asset),3rdparty/CMakeLists.txt 会同时编译 Jolt 的 TestFramework 供调试渲染使用,physics_manager.cpp 中的 renderPhysicsWorld 在每一帧被调用以绘制物理世界(该函数以 #ifdef ENABLE_PHYSICS_DEBUG_RENDERER 包裹)。

使用须知(README 原文要点):

  1. 重新生成前请清理 build 目录:直接复用旧的 CMakeCache 重新生成会遭遇构建问题;
  2. Physics Debug Renderer 会随 PiccoloEditor 启动,两个场景的相机位置已同步,但调试渲染器的初始相机模式有误——向下滚动一次鼠标滚轮即可切换到正确模式。

小结

从环境准备、三平台构建命令到源码级工程组织,Piccolo Engine 提供了一条清晰的学习与实践路径:Windows 用 build_windows.bat 一键产出 Release 版编辑器,macOS 用 Xcode 工程或 build_macos.sh,Linux 用 build_linux.sh(自动选择 Ninja/Make 并默认导出编译数据库)。构建成功后,可通过 PiccoloEditor.ini 与 rendering.global.json 快速体验默认关卡并调整渲染/粒子参数;进阶开发者可结合 compile_commands.json 接入 clangd,或按需打开 ENABLE_PHYSICS_DEBUG_RENDERER 观察 Jolt 物理世界,从构建到运行再到调试形成完整闭环。

登录后查看全文
Piccolo