如何为VCMI贡献代码编码规范、测试与线程模型完整指南【免费下载链接】vcmiOpen-source engine for Heroes of Might and Magic III项目地址: https://gitcode.com/gh_mirrors/vc/vcmiVCMI 是一款《英雄无敌 III》Heroes of Might and Magic III的开源游戏引擎采用 C 编写遵循客户端-服务器架构。想为 VCMI 贡献代码这篇文章将完整带你走通全流程从搭建开发环境、遵守 C 编码规范到编写单元测试、理解多线程模型帮助新手开发者快速向开源社区提交高质量补丁。认识VCMI代码库客户端-服务器架构在动手写代码之前先花 10 分钟了解代码库布局能少走 80% 的弯路。VCMI 的核心分为三大部分目录职责lib/核心静态库vcmiMain游戏状态、战斗规则、奖励系统Bonus、序列化、JSON 配置解析等client/游戏客户端UI 渲染、输入处理、地图与战斗画面展示server/游戏服务器唯一有权修改游戏状态的一方处理玩家请求与回合逻辑其他重要目录AI/—— 各 AI 模块BattleAI 战斗 AI、Nullkiller2 冒险地图 AI 等以静态库形式链接进引擎config/—— 游戏配置 JSON 文件及校验模式schemaluascript/与scripts/—— Lua 脚本系统与游戏脚本test/—— 全部单元测试代码mapeditor/、launcher/—— 基于 Qt 的地图编辑器与启动器⚠️ 核心原则只有服务器可以修改游戏状态。客户端只能向服务器发送请求服务器校验后将状态变更广播给所有客户端。所有贡献都需遵守这一约定详见docs/developers/Networking.md与AGENTS.md。快速搭建VCMI开发环境CMake Conan 环境准备只需四步克隆仓库需要 HoMM3 原版游戏文件才能完整运行git clone https://gitcode.com/gh_mirrors/vc/vcmi cd vcmi配置 CMake。VCMI 使用 CMake 构建推荐启用以下选项参见docs/developers/CMake.md-DCMAKE_BUILD_TYPEDebug开启调试信息、关闭优化-DCMAKE_EXPORT_COMPILE_COMMANDSON生成compile_commands.json配合 clangd 语言服务器获得智能提示-DENABLE_CCACHE:BOOLON缓存编译结果大幅加速重复构建-G Ninja用 Ninja 替代 Make构建更快且无需-j参数管理依赖。Windows 下推荐用 Conan 管理依赖见docs/developers/Conan.md与conanfile.py主要依赖包括 SDL2渲染、Qt5/Qt6启动器与地图编辑器、Boost、FFmpeg、TBBAI 并行计算等其他平台可用系统包管理器。编译并跑测试。各平台构建细节可参考docs/developers/Building_Windows.md、docs/developers/Building_Linux.md、docs/developers/Building_macOS.md等文档。 注意VCMI 统一以C20标准构建根CMakeLists.txt中设置CMAKE_CXX_STANDARD为 20支持 GCC 10、Clang 16、MSVC 19.44 等编译器。新代码应优先使用 C20 特性。VCMI编码规范速览C风格要点完整规范见docs/developers/Coding_Guidelines.md以下是最容易被打回补丁的几条 格式类使用Tab缩进行宽上限120 列左花括号另起一行单行分支可省略花括号但内部有多层嵌套时必须加关键字与括号间不留空格if(a)而非if (a)指针声明中*前后各留一个空格CIntObject * images[100]switch的case与switch同级缩进break与case对齐️ 命名类局部变量、方法用小驼峰getHeroesCount类/结构体大写开头CGameState宏与常量全大写源文件名首字母大写并与类名对应目录用小驼峰避免不常见缩写CArtifact而非CArt 文件结构每个.h/.cpp文件头部必须带项目许可证信息块文件内顺序许可证 →#pragma once→ include → 前向声明 → 其他代码统一用#pragma once作为头文件保护每个编译单元第一个 include 应为StdInc.h预编译头 序列化与常量需要跨编译单元共享或被序列化的类使用DLL_LINKAGE宏禁止魔法数字实体 ID 查lib/constants/EntityIdentifiers.h字符串 ID 查lib/constants/StringConstants.h序列化代码中每个h field;独占一行便于调试测试体系为VCMI提交带测试的代码✅ VCMI 的单元测试基于GoogleTest/GoogleMock全部集中在test/目录最终编译为单一可执行文件vcmitest定义于 test/CMakeLists.txt。测试代码按被测模块组织test/battle/—— 战斗系统六角格、单位状态、血量计算test/spells/—— 法术效果与目标条件覆盖猫弩、召唤、传送等test/server/battles/—— 服务器侧战斗处理器如AcidBreathTest.cpp、DeathStareTest.cpptest/entity/—— 英雄、兵种、派系等实体test/nullkiller2/—— 冒险 AI 的行为、目标与寻路test/mock/—— 大量手写 MockGameHandlerTestServer、TinyMapGameTest等用于隔离依赖新增测试的标准流程在对应子目录新建XxxTest.cpp参考同目录现有用例写法在test/CMakeLists.txt的test_SRCS列表中登记新文件构建后运行ctest注意vcmitest全局初始化较慢官方不建议逐条跑 ctest整包运行即可项目还内置了 Mock 服务器GameHandlerTestServer与微型 H3M 地图构建器TinyH3MBuilder让测试无需真实游戏文件即可驱动完整游戏状态——写战斗逻辑测试时直接复用这套基建即可。线程模型VCMI多线程架构详解⚡ 理解线程模型是修改客户端与网络代码的必修课。VCMI 中存在以下长生命周期线程详见docs/developers/Code_Structure.md线程名职责MainGUI主线程输入处理、屏幕更新与最终渲染runNetwork网络线程常驻 boost::asio io_service处理入站网络包、战斗 AI 反应、AI 初始响应动画播放期间会阻塞等待动画结束runServer服务器线程同样常驻独立 io_service处理所有玩家人类或 AI请求并更新游戏状态consoleHandler控制台线程处理标准输入的控制台命令TBB 并行任务短生命周期按需创建Nullkiller2 AI 用parallel_for大规模并行化任务AI 主任务NKAI::makeTurn在 AI 回合开始/结束时创建与销毁随机地图生成器RMG使用 TBB 线程池客户端在后台线程做图像超采样避免画面冻结短暂线程autofightingAI玩家按下自动战斗热键时为避免主线程冻结首步 AI 决策放到临时线程initialize游戏启动时在播放开场动画的同时于独立线程完成大部分库初始化 提交代码时牢记三条铁律客户端线程不得直接改游戏状态网络包处理逻辑可能运行在runNetwork线程上AI 重任务要派发回自己的线程游戏内聊天输入的控制台命令统一在processCommand独立线程执行以避免持锁冲突。首次贡献清单Checklist☑ 通读AGENTS.md与docs/developers/Coding_Guidelines.md☑ 用 CMake Ninja ccache 搭好本地环境成功编译☑ 小步修改优先从 bug 修复、测试补充、配置修正入手config/目录是新手友好区☑ 新逻辑必须配test/下的单元测试保证vcmitest全绿☑ 涉及存档格式时补充序列化向后兼容代码涉及实体时先查lib/constants/已有常量☑ 提交前确认无新增编译警告风格与规范一致掌握架构、规范、测试与线程模型这四块拼图后你的补丁将更有机会被社区合入。祝你在 VCMI 开源引擎的征途上一路顺风【免费下载链接】vcmiOpen-source engine for Heroes of Might and Magic III项目地址: https://gitcode.com/gh_mirrors/vc/vcmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考