开发者教程

路线档案

适合：准备修改 C++、构建系统或项目基础设施的贡献者　·　前置：Git 与命令行基础　·　最终成果：提交一份经过本地验证的 PR

CCB 是一个以 C++ 和 JSON 为核心、面向多个桌面平台及 Android 的大型项目。不要从“读懂全部源码”开始；先让构建和测试跑起来，再沿具体功能追踪数据流。

学习路线

课程	完成标志
准备开发环境	有独立分支，并能找到当前平台的权威构建文档
编译游戏	产出可启动的图形版程序
测试与调试	能运行相关测试并定位日志或断点
提交贡献	PR 描述、格式和验证记录完整

仓库地图

目录	主要内容
src/	游戏逻辑、界面和平台后端的 C++ 源码
data/json/	核心物品、怪物、配方、地图等数据
data/mods/	随仓库维护的 MOD
tests/	Catch2 测试与测试数据
doc/	当前版本的开发、JSON、设计与平台文档
tools/	格式化、校验、贴图和维护脚本
.github/workflows/	CI 构建矩阵、格式与发布流程

上游关系

CCB 基于 CDDA 演进，并选择性同步上游改动。实现功能时既要检查上游当前设计，也要保留 CCB 明确存在的差异；不能把“与上游不同”自动当作错误。

最有效的阅读方式

从一个可观察行为出发：找到它对应的 JSON ID、界面动作或测试名称，再使用 rg 沿引用追踪。大型源码树不适合从入口文件顺序阅读。