在 Windows 上搭建 Lumina 开发环境
约 2081 字
前言与平台定位
在 RoboCup 小型组(SSL)日常训练、比赛与全真模拟中,Ubuntu 依然是我们的核心主流平台。绝大多数国内赛队及官方工具链均以 Linux 为第一优先。
然而,对于没有双系统条件、需要临时在 Windows 笔记本上进行战术开发、Lua 脚本调试或单兵测车的同学,Lumina 也为 Windows + MSVC 适配,支持以纯原生方式在 Windows 10/11 64 位系统上构建并运行。
但是各位需要注意,Lumina 在 Windows 平台的适配并不完善,使用时会遇到非常多的bug,需要进一步优化,有条件的同学还是推荐使用 Ubuntu 进行开发。
本套教程独立成章,指引你从零搭建 Windows 下的 Lumina 编译与运行环境。
核心架构与技术路线
在 Windows 平台下,Lumina 采用以下技术选型:
- 编译器:Microsoft Visual C++ (MSVC 2022,x64 架构)
- GUI / QML 框架:Qt 6(基于 MSVC 2022 64-bit 构建的组件库)
- 依赖包管理:微软官方的 vcpkg(管理 Protobuf、ODE、Eigen3、yaml-cpp、fmt、zstd 等)
- 预编译第三方库(3rdParty):Windows 专用的 Lua 5.1 与 tolua++ 绑定工具、二进制静态库与头文件由本 Wiki 统一打包提供,解压即用
- 算力加速(可选):NVIDIA CUDA Toolkit(支持消费级 RTX/GTX 显卡,也支持纯 CPU 运行)
- 构建与输出体系:统一通过 CMake 进行工程配置,所有可执行文件(
Client.exe、Medusa.exe、Aurora.exe)及运行时依赖动态库统一汇聚于根目录下的ZBin/目录
1. 安装 Visual Studio 2022
Visual Studio 2022 是 Windows 下构建 Lumina 的基础编译器与工具链提供者。
前往微软官方网站下载 Visual Studio 2022 Community(社区版):
下载 Visual Studio 2022免费、全功能的 IDE 与 MSVC 编译器套件

运行 Visual Studio Installer,在“工作负荷”页面勾选 “使用 C++ 的桌面开发”:

在右侧“安装详细信息”面板中,确保勾选了以下关键组件:
- MSVC v143 - VS 2022 C++ x64/x86 生成工具
- Windows 10 SDK 或 Windows 11 SDK(最新版本即可)
- 用于 Windows 的 C++ CMake 工具
- C++ 核心桌面功能
点击“安装”或“修改”,等待安装完成:

2. 安装与配置 vcpkg
Lumina 依赖的很多三方开源库在 Linux 下可以通过 apt 直接安装,在 Windows 下我们统一使用微软开源的 vcpkg 包管理器。
2.1 克隆并初始化 vcpkg
建议将 vcpkg 安装在一个路径简短、没有中文、没有空格的目录下(例如 C:\vcpkg 或 D:\vcpkg)。在 PowerShell 中执行:
# 切换到你希望放置 vcpkg 的目录,例如 C:\
cd C:\
# 克隆官方 vcpkg 仓库
git clone https://github.com/microsoft/vcpkg.git
# 进入目录并初始化
cd vcpkg
.\bootstrap-vcpkg.bat路径提示
请记下你的 vcpkg 安装绝对路径,稍后 CMake 配置时需要引用其工具链文件: <vcpkg安装路径>\scripts\buildsystems\vcpkg.cmake
2.2 安装 Lumina 所需依赖项
以 64 位 Windows (x64-windows) 为目标安装所有依赖:
.\vcpkg.exe install protobuf eigen3 ode yaml-cpp fmt zstd --triplet x64-windows依赖说明
- protobuf:用于 Client、Medusa 与仿真器/裁判系统之间的数据序列化通信,安装时会自动拉取 abseil、utf8-range 等依赖。
- eigen3:高性能 C++ 矩阵与线性代数算法库。
- ode(Open Dynamics Engine):物理碰撞仿真计算引擎。
- yaml-cpp:YAML 格式配置文件解析器。
- fmt & zstd:现代 C++ 高性能格式化输出库与高速压缩库。
3. 使用 Qt Online Installer 安装 Qt 6
Qt Online Installer 的下载、登录、镜像源和组件安装步骤直接参照已有教程:
按现有图文教程完成安装;Windows 选择 MSVC 2022 64-bit 套件
Windows 下下载 Windows x64 安装器,桌面套件选择 MSVC 2022 64-bit,附加库与 Qt Creator 按上述教程安装,并保持组件属于同一 Qt 版本。
记下套件路径
安装完成后,记下实际的 Qt MSVC 套件目录,例如 C:/Qt/6.8.0/msvc2022_64。后续 Qt Creator 或 Visual Studio 中的 CMAKE_PREFIX_PATH 填写这个目录;不要填 C:/Qt、版本目录 C:/Qt/6.8.0 或套件下的 bin 目录。
该目录下应存在 lib/cmake/Qt6/Qt6Config.cmake。套件必须与 MSVC x64 编译器匹配,不能选用 MinGW 或 Linux 的 gcc_64 套件。构建脚本的 -QtRoot 参数则按下文示例填写 Qt 版本目录,与这里的套件前缀不同。
4. 安装 NVIDIA CUDA Toolkit(可选)
如果你的电脑配备了 NVIDIA 独立显卡(支持 Compute Capability 7.5+,即 GTX 16 系列、RTX 20/30/40/50 系列),可以安装 CUDA 开启 Medusa 策略底层 GPU 算力加速。
在终端中输入 nvidia-smi 检查当前显卡驱动支持的最高 CUDA 版本:

- 下载地址:NVIDIA CUDA Toolkit 官方归档页面(推荐 CUDA 12.x 系列)
- 安装选项:选择“自定义”安装,确保勾选 Visual Studio Integration(这样 MSVC CMake 才能顺利识别
nvcc)。 - 无独显 / AMD 显卡用户:直接跳过此步!在后续 CMake 中设置
-DUSE_CUDA_MODULE=OFF即可使用纯 CPU 模式运行。
5. 获取 Lumina 源码与依赖包配置
5.1 克隆仓库
请确认你已取得私有仓库权限,并使用 Git 拉取源码:
git clone https://github.com/lkhcode/lumina.git
cd lumina5.2 下载并解压 3rdParty 依赖包(必做项)
为什么仓库里没有 3rdParty 目录?
在 Windows 平台上,Medusa 的策略引擎深度依赖 tolua++(用于将 C++ 数据结构与算法绑定并导出给 Lua 策略层)和 Lua 5.1。 由于这些三方库在 Windows 下包含预编译的可执行程序(如 tolua++.exe)及静态库文件,为了避免污染 Git 仓库历史并精简拉取体积,仓库的 .gitignore 默认忽略了 3rdParty。
我们在下方提供了完整的 Windows 专用 3rdParty 依赖压缩包,包含已适配 MSVC 的 tolua++、lua、ODE、protobuf 和 zlib:
包含 tolua++.exe、lua5.1 等 Windows 预编译依赖,下载后直接解压至 Lumina 根目录
解压放置要求: 下载完成后,将压缩包内的 3rdParty 文件夹解压到你的 Lumina 项目根目录 下。解压后的目录结构应如下所示:
lumina/
├── 3rdParty/ <-- 确保该目录存在于 Lumina 项目根目录下
│ ├── lua/ <-- 包含 lua5.1 头文件与 lua5.1.lib
│ ├── ODE/
│ ├── protobuf/
│ ├── tolua++/ <-- 包含 tolua++.exe 工具及 tolua++.lib
│ └── zlib/
├── Client/
├── Medusa/
├── CMakeLists.txt
└── ...验证解压
若解压正确,在进行 CMake 配置时,系统将自动识别到 tolua++.exe 并顺利生成 tolua_zeus.cpp,不会出现 Findtoluapp: not found 报错。
5.3 准备 AutoReferee 运行环境(可选)
Lumina 内置了自动化准备 AutoReferee 及对应 Java 运行时的脚本。在 PowerShell 中运行:
powershell -ExecutionPolicy Bypass -File .\scripts\setup-autoref-windows.ps1该脚本会自动检测并下载匹配的 OpenJDK 25 运行时与 AutoRef 核心组件,并安置于 ZBin/java 与 ZBin/autoReferee,供 Client 内部一键拉起自动裁判盒。
6. 快捷通道:PowerShell 一键构建脚本
如果你希望快速验证环境是否完备,Lumina 根目录提供了现成的自动化构建脚本 scripts/build-windows.ps1。
在 PowerShell 中进入项目根目录,传入你的 Qt 和 vcpkg 路径执行:
# 纯 CPU 模式构建 Release
.\scripts\build-windows.ps1 -QtRoot "C:\Qt\6.8.0" -VcpkgRoot "C:\vcpkg" -Configuration Release
# 若启用 CUDA 加速
.\scripts\build-windows.ps1 -QtRoot "C:\Qt\6.8.0" -VcpkgRoot "C:\vcpkg" -Configuration Release -UseCuda脚本会自动调用 CMake 配置、生成 Visual Studio 解决方案并执行多核并行编译。构建完成后的二进制程序和依赖库会自动输出到 ZBin/。
7. 选择你的集成开发环境(IDE)
基础依赖准备就绪后,你可以根据日常使用习惯选择以下两种主流开发方式之一:
使用 VS2022 与 VSCode 的各种插件协作开发
使用VS2022 与 Qt Creator 协作开发