获取、配置与运行 Lumina
约 3751 字
使用前必读
开始前,请确认以下准备工作已经完成:
- 拥有 GitHub 账号,完成双重身份验证(2FA)及 Git 访问配置,参见配置 Git 来访问私有仓库。
- 已安装依赖环境,并通过 Qt Online Installer 安装 Qt6 开发环境。
- 如果准备使用 NVIDIA CUDA 加速,已安装驱动与 CUDA Toolkit,参见在 Ubuntu 中安装显卡驱动与 CUDA。使用纯 CPU 模式时无需安装 CUDA;AMD 显卡也不使用 CUDA,需另行准备 ROCm 环境。
1. 确认 Lumina 仓库的访问权限
在进行操作前,请确认你已经获取了 Lumina 的访问权限。Lumina 是私有仓库,请先联系管理员获取访问权限。你需要向管理员提供你的Github邮箱或用户名,我们会将你添加进仓库。
收到邀请后,登录被邀请的 GitHub 账号,通过邮件或以下页面接受邀请:
Invitation to join lkhcode/lumina

Accept Invitation
确认可以在浏览器中打开仓库页面后,再继续克隆。若显示 404,先检查登录账号和邀请状态。
2. 拉取 Lumina
你可以尝试通过终端拉取 Lumina。不过 Lumina 是私有仓库,使用第一行的HTTPS直接拉取,可能会出现访问权限问题。使用第二行拉取,需要为电脑配置 SSH 密钥后,才可以使用。想要追求方便的同学,可以使用 VSCode 进行拉取。
# HTTPS
git clone https://github.com/lkhcode/lumina.git
# SSH
git clone git@github.com:lkhcode/lumina.git各位同学打开 VSCode 后,登录自己的 Github 账号。然后使用 VSCode 欢迎界面的克隆 Git 仓库功能,选择从 Github 克隆。你就可以从列表中找到 Lumina。
找不到欢迎界面
可以通过菜单 帮助 → 欢迎 重新打开,或在命令面板中执行 Git: Clone。

克隆 Git 仓库

从 GitHub 选择 Lumina
建议将项目放在便于查找的开发目录中,路径尽量避免空格和中文。后文的“项目根目录”指克隆得到的 lumina 文件夹,其中应包含顶层 CMakeLists.txt、Client、Medusa 和 ZBin 等文件或目录。
3. 配置 Lumina
各位可以使用 Qt Creator 进行 Lumina 的构建。使用终端构建Lumina的方法与之大同小异,不再赘述。
打开 Qt Creator,点击 打开项目,选择项目根目录下的 CMakeLists.txt。请打开顶层工程,方便同时构建 Client、Medusa 等程序。

在 Qt Creator 中打开项目

选择顶层 CMakeLists.txt
在配置页面选择 Qt Online Installer 安装的 Desktop Qt 6.x GCC 64bit 套件(Kit),首次使用可以只勾选 Release,然后点击 Configure Project。
- Release:启用编译优化,适合日常仿真与比赛。
- Debug:方便设置断点、检查变量,适合排查 C++ 问题。
- RelWithDebInfo:保留调试信息并启用优化,可按需要选择。

选择 Kit 与构建类型
没有可用的 Qt6 套件
先检查 Qt6 的 Desktop 组件是否安装。Qt Creator 本身是编辑器,安装了它不等于已经安装 Qt6 开发套件。可以在 首选项 → 构建和运行 → Kits 中检查 Qt 版本、编译器和 CMake 是否有效。
修改 CMake 配置
点击左侧 项目 → 对应 Kit → 构建设置,找到中间的 CMake 配置表格。可以通过过滤框搜索参数名;修改后点击 执行 CMake,等待重新配置完成。界面位置和名称可能随 Qt Creator 版本略有变化,参见 Qt Creator 的 CMake 构建设置说明。

CMake 构建设置
表格中既有 Lumina 自己的选项,也有 CMake 自动生成的编译器和依赖路径。首次配置主要检查下表中的参数,其他参数通常保持默认。默认值指新建构建目录时的值,已有缓存可能保留之前的设置。
| 参数 | 默认值 | 含义与使用建议 |
|---|---|---|
CMAKE_PREFIX_PATH | 由 Kit、环境或工程自动检测提供 | Qt 安装前缀;找不到 Qt 或检测到错误版本时,显式填写所选套件目录,见下文 |
LUMINA_QT_SEARCH_ROOTS | 空 | 为工程自动检测补充自定义 Qt 安装位置;已明确设置 Qt 前缀时通常无需再填 |
CMAKE_BUILD_TYPE | 单配置生成器未指定时为 Debug | 本教程选择 Release;Visual Studio 等多配置生成器在构建时选择配置 |
USE_CUDA_MODULE | ON | 启用 Medusa 的 NVIDIA CUDA 计算模块;不使用 CUDA 时改为 OFF |
USE_ROCM_MODULE | OFF | 启用 Medusa 的 AMD ROCm/HIP 计算模块;仅在对应环境准备好后开启 |
USE_DIV_A | OFF | 使用 Division A 国赛场地参数, 12 m × 9 m |
USE_DIV_B | ON | 使用 Division B 省赛场地参数, 9 m × 6 m |
IS_TECH | OFF | 启用技术挑战赛模式,人工介入,允许手动控制传球点及相关策略;普通仿真和比赛保持关闭 |
CUDA_TARGET_ARCH | native | CUDA 模块使用的目标架构;本机编译通常保持 native,该项在启用 CUDA 后出现 |
LUMINA_ENABLE_FIELD3D | OFF | 启用实验性的 3D 场地视图,开启时需要同版本 Qt Quick 3D;按需开启 |
LUMINA_QT_MIN_VERSION | 6.7 | 工程要求的最低 Qt6 版本;应安装符合要求的 Qt,而不是调低此值绕过检查 |
两组互斥选项
USE_CUDA_MODULE与USE_ROCM_MODULE不能同时开启,否则 CMake 会报错。两者均关闭即为纯 CPU 模式。USE_DIV_A与USE_DIV_B不能同时开启。请按实际场地选择其中一项,不要只开启 A 而忘记关闭默认的 B。
场地参数会参与编译,修改后需要重新构建,并确认仿真器或实际场地与之对应。
指定 Qt 的 CMAKE_PREFIX_PATH
Kit 通常会提供 Qt 路径,Lumina 也会尝试自动检测 Qt。但在 Qt 安装于自定义目录、同时装有多个 Qt 版本,或日志提示找不到 Qt6Config.cmake 时,需要检查并显式设置 CMAKE_PREFIX_PATH。
在上面的 CMake 表格中搜索该参数;如果没有,点击 添加(Add)→ String,名称填写 CMAKE_PREFIX_PATH,值填写实际的 Qt 套件目录。例如:
| 平台与 Kit | CMAKE_PREFIX_PATH 示例 |
|---|---|
| Ubuntu / GCC 64bit | /home/lkh/Qt/6.8.0/gcc_64 |
| Windows / MSVC 2022 64-bit | C:/Qt/6.8.0/msvc2022_64 |
版本号、用户名和安装位置都要换成自己的实际值。前缀下应有 lib/cmake/Qt6/Qt6Config.cmake,不要填 Qt 安装根目录、版本目录或 bin。该参数用于 CMake 查找依赖,不能代替 Kit 中的编译器选择,也不能补装缺少的 Qt 组件。
CMAKE_PREFIX_PATH 支持多个前缀,在 CMake 变量值 中用英文分号 ; 分隔,已有其他必要依赖路径时应保留。Qt Creator 表格中只填写路径值,无需加 -D 或引号。若在终端中传入多个前缀,应将整个值用引号括起。
Qt6_DIR 与前缀不同,它直接指向包含 Qt6Config.cmake 的目录,例如 /home/lkh/Qt/6.8.0/gcc_64/lib/cmake/Qt6。通常设置 CMAKE_PREFIX_PATH 即可,不必同时手动填写多个 Qt 路径参数。若缓存中的 Qt6_DIR、Qt6Core_DIR 等仍指向旧版本,请使用新的独立构建目录,或在确认初始参数已保存后清除 CMake 配置并重新配置;单纯清理编译产物不会清除这些路径。
重新执行 CMake 后,核对配置表格中的 Qt6_DIR 是否指向预期套件,再确认日志出现 Configuring done 和 Generating done。如果套件路径正确但缺少 Core5Compat、SerialPort 或 WebSockets,请用 MaintenanceTool 补装同版本组件。
Windows 还需要 vcpkg 工具链
本页默认使用 Ubuntu + GCC。Windows + MSVC 除了检查 Qt 前缀,还需在初始配置中设置 CMAKE_TOOLCHAIN_FILE(如 C:/vcpkg/scripts/buildsystems/vcpkg.cmake)及 VCPKG_TARGET_TRIPLET=x64-windows,详见 Windows Qt Creator 构建教程。工具链与 Qt 前缀分别解决 vcpkg 依赖和 Qt 的查找问题,需要时应同时设置。
根据电脑选择计算后端
| 使用场景 | USE_CUDA_MODULE | USE_ROCM_MODULE |
|---|---|---|
| 无可用 GPU 加速环境,或先完成首次构建 | OFF | OFF |
| NVIDIA 显卡,已配置驱动与 CUDA Toolkit | ON | OFF |
| AMD 显卡,已配置兼容的 ROCm/HIP 环境 | OFF | ON |
这里的 GPU 加速用于 Medusa 的策略计算,与 Client 的界面渲染是不同的设置。纯 CPU 模式也能启动 Client 和运行策略。
使用 CUDA 时,可以在终端检查:
nvidia-smi
nvcc --version前者检查驱动与显卡是否可用,后者检查 CUDA 编译器。CUDA_TARGET_ARCH=native 需要能检测到本机 GPU;若是在无 GPU 的机器上交叉准备构建产物,需要按目标设备显式指定架构。不要直接照抄截图中的 CMAKE_CUDA_ARCHITECTURES 数字,当前工程的 CUDA 模块使用的是 CUDA_TARGET_ARCH。
不需要逐项修改的参数
截图中的 AUTOREFEREE_* 参数用于自动裁判的获取与安装。普通使用保持默认即可:
AUTOREFEREE_BUILD_FROM_SOURCE默认关闭,使用预构建发行包;维护自动裁判源码时才需要考虑开启。AUTOREFEREE_ARCHIVE默认留空,离线安装时才填写对应发行包的本机路径。- 仓库地址、提交版本和安装目录由工程指定,通常无需修改。
CMAKE_CXX_COMPILER 通常由 Kit 提供,无需在表格中手动改编译器。Qt 路径检测有误时,按上文检查 Kit、CMAKE_PREFIX_PATH 和旧缓存;缺少模块时再补装对应组件。
配置日志出现 Configuring done、Generating done,且没有阻止配置的错误后,就可以开始构建。配置成功只表示构建文件已生成,还没有完成编译。
4. 构建 Lumina
在 Qt Creator 中选择 构建 → 构建所有项目,或按 Ctrl+Shift+B。首次构建建议使用顶层工程的 all 目标,确保 Client、Medusa 等程序一起生成。
在 项目 → 构建设置 → 构建步骤 中,展开构建步骤右侧的 详情,可以查看目标列表与并行编译参数。如下图,勾选 all;CMake arguments 中的 -j12 表示最多同时执行 12 个编译任务,请根据电脑的内存和处理器情况调整。

构建目标与并行任务设置
勾选 all 构建完整工程,并按电脑配置调整 CMake arguments 中的 -j 参数
首次配置或构建时可能需要从网络获取 FluentUI、grSim、ssl-game-controller 等外部组件,耗时通常比后续增量构建长。遇到下载失败时,先查看日志中的具体地址和错误,确认网络恢复后再重试。
构建时内存不足
如果日志出现 Killed 或 cc1plus 被终止,可能是并行编译占用了过多内存。可以在上图的 CMake arguments 中降低并行任务数,例如将 -j12 改为 -j2,然后重新构建。
构建结束后,检查 编译输出 中是否仍有错误。当前工程将可执行程序输出到项目根目录下的 ZBin/,CMake 缓存和中间文件则保存在所选的构建目录中。
AutoReferee 使用独立的 install_autoreferee 目标,普通构建不会自动完成它的安装。需要联调自动裁判时,再构建该目标,并继续阅读 AutoRef 自动裁判教程。
5. 运行 Client
在 Qt Creator 中运行
- 在左下角的运行配置中选择 Client。
- 打开 项目 → 运行设置,确认可执行文件指向本次构建生成的 Client。
- 将 工作目录(Working directory) 设为项目根目录下的
ZBin/的绝对路径。 - 点击绿色运行按钮,或按
Ctrl+R。
工作目录可在 Qt Creator 的运行设置中指定,参见 Qt Creator 桌面运行设置。Lumina 会读取配置、Lua 脚本并启动其他程序,因此运行时请保留完整的 ZBin 目录结构。
也可以在终端中运行 Release 版本:
# 在 lumina 项目根目录下执行
cd ZBin
./Client请以实际生成的可执行文件名为准。使用 Qt Creator 运行时通常更方便继承 Kit 的运行环境;若终端启动提示缺少 Qt 动态库,先检查是否加载了正确的 Qt 环境。
首次检查:连接本机仿真
看到 Client 界面后,可以先检查本机内置仿真链路:
- 在 Vision 区域选择网卡
lo、IP127.0.0.1,模式设为 Simulation,然后点击 Connect。 - 检查场地画面与视觉帧率。使用内置 ZSimulator 时,无需再启动外置 grSim。
- 在 Medusa 区域核对队伍颜色和进攻方向,再选择需要的战术包;正常运行时关闭 Test Mode,专项测试时再选择对应脚本。
- 启动对应队伍的 Medusa,检查进程和状态信息。车辆是否运动还取决于裁判指令与当前策略,请继续按 Client 使用教程操作。
6. 常见问题
| 现象 | 排查方法 |
|---|---|
克隆提示 Repository not found 或 404 | 检查是否接受邀请,以及终端或 VSCode 使用的账号是否具有访问权限 |
SSH 提示 Permission denied (publickey) | 检查本机密钥及 GitHub 公钥配置,参见 Git 配置教程 |
找不到 Qt6、Core5Compat、SerialPort 或 WebSockets | 先检查 Kit 和 CMAKE_PREFIX_PATH,清除旧 Qt 路径缓存;缺少组件时通过 Qt 的 MaintenanceTool 为同一 Qt 版本补装组件,不要混用系统 Qt 和 Online Installer 的不同版本 |
| 找不到 Protobuf、ODE、Eigen、fmt 等依赖 | 回到安装依赖环境核对,并根据日志补齐缺失的软件包 |
| CUDA 配置或编译失败 | 检查驱动、nvcc、工具链兼容性及目标架构;暂不使用加速时将两种 GPU 后端均关闭,再重新配置 |
| 下载依赖失败 | 检查日志中的网络错误;自动获取的依赖仍需要可访问对应下载源 |
| Client 能打开,但找不到脚本或无法启动 Medusa | 检查运行工作目录是否为 ZBin/,并确认已构建完整工程,相关程序确实存在 |
| 切换 Kit 或计算后端后仍沿用旧配置 | 使用新的独立构建目录重新配置,避免旧的编译器、Qt 或 GPU 检测结果继续生效 |
排查时优先查看 CMake 输出、编译输出、应用程序输出 中的第一处具体错误。若需要向队友求助,请同时提供所用分支、Kit、构建类型、关键 CMake 参数及错误上下文。