简介一款基于Qt/C的2D宝可梦小游戏完整源码专为刚接触Qt游戏开发的C学习者设计可帮助理解角色扮演游戏的整体架构。项目完整实现了游戏世界、宝可梦、战斗、玩家四大系统2D俯视角地图包含角色移动与碰撞检测宝可梦系统具备属性相克、技能和进化玩法战斗系统采用回合制并带技能选择与动画玩家系统支持角色管理和背包存储。渲染基于QGraphicsView/QGraphicsScene支持TMX地图加载并预留了扩展空间可继续添加新精灵、新场景与剧情。压缩包共20个文件以9个cpp、8个h源码为主cpp实现具体游戏逻辑h定义类接口另有pro工程文件管理构建、qrc注册资源、TMX提供地图配置整体仅19KB轻量适合快速阅读。目前已有103人学习下载。代码按Battle、GameScene、BattleScene等模块划分读者可从中掌握Qt游戏项目的模块组织、回合制战斗逻辑和TMX地图加载方法也可作为课程设计或入门练手的参考。1. 用QTC做宝可梦小游戏不靠Unity也能把回合制攥在手里很多人一说到做“宝可梦”第一反应是Unity、Godot其实回合制RPG的核心在“状态流转”和“数值判定”渲染只是最外一层。用QTC做宝可梦小游戏恰好能把这两层拆干净C负责战斗内核、存档、背包逻辑QT负责窗口、绘图、信号槽和输入响应。不引入引擎不写脚本语言一个连vscode配置c/c环境都刚搞定的读者也能在两三千行内跑出一个能玩、能存档、能不闪退的桌面版本。适合拿来做Qt入门后的第一个完整小项目也适合想验证“C游戏逻辑能不能和界面解耦”的人。这篇文章讲的就是一条我实际走通的路径控制台内核先行QGraphicsScene渲染界面JSON存档收尾最后用状态机和自动化测试把流程固化下来。2. 先把战斗内核写到控制台C结构体、属性克制和回合循环很多入门项目一上来就铺界面控件结果一半时间花在对齐控件和调样式上战斗逻辑反而写得一团浆糊。做游戏最稳的路径是先把“不带界面的部分”跑通再包一层QT壳。宝可梦玩法剥去画面本质就是一个回合制状态机选择指令、计算伤害、判定胜负、切换状态。这部分用纯C写不进视口、不碰QWidget跑起来没有任何界面干扰。2.1 用结构体和枚举给宝可梦建模别急着画界面先定义最小数据集。一只宝可梦需要有名字、属性、HP、攻击、防御、速度和技能表。这里用聚合结构体就够不要一上来就套类继承体系把行为写成独立函数后面接信号槽时更顺手。struct Move { QString name; // 技能名 QString type; // 技能属性用于克制判定 int power; // 威力 double accuracy; // 命中率0.0 ~ 1.0 }; struct Pokemon { QString name; // 显示名 QString type; // 属性如火、水、草 int maxHp; // 最大HP int hp; // 当前HPqBound(0, hp, maxHp) 随时夹紧 int atk; int def; int speed; QVectorMove moves; // 最多带四个技能 };这段代码有两个细节值得说明。QString是Qt的字符串类型不是std::string因为后面无论控制台打印还是界面显示都离不开QString的隐式转换QVectorMove存放技能列表C字符串数组初始化在这里退化为QVector的初始化列表写起来比裸指针数组安全。把Move单独抽出来是给AI对手复用后面做野生宝可梦随机技能池时不需要改Pokemon本身。再用一个Roster函数生成初始数据相当于“图鉴数据源”的雏形QVectorPokemon makeRoster() { QVectorPokemon list; list.push_back({小火龙, 火, 120, 120, 60, 50, 65, {{火花, 火, 40, 1.0}, {抓, 一般, 40, 1.0}}}); list.push_back({杰尼龟, 水, 130, 130, 50, 65, 58, {{水枪, 水, 40, 1.0}, {撞击, 一般, 35, 1.0}}}); list.push_back({妙蛙种子, 草, 125, 125, 55, 60, 54, {{藤鞭, 草, 45, 1.0}, {撞击, 一般, 35, 1.0}}}); return list; }这是典型的“表驱动”写法不要把初始数据散落在各个类的构造函数里。后面换成真实平衡数值时只需改这一处。注意QVector的初始化列表要求编译器开启C11以上标准CMake里对应CMAKE_CXX_STANDARD 17Qt 5.14.2以上的默认工程模板已经带上了。2.2 克制表与伤害公式把对战规则落成可测试代码属性克制的核心数据我习惯用嵌套QMap表达这比一堆if else好维护得多const QMapQString, QMapQString, double kTypeChart { {火, {{草, 2.0}, {水, 0.5}, {火, 0.5}}}, {水, {{火, 2.0}, {草, 0.5}, {水, 0.5}}}, {草, {{水, 2.0}, {火, 0.5}, {草, 0.5}}}, {电, {{水, 2.0}, {草, 0.5}, {电, 0.5}}} }; double typeMultiplier(const QString moveType, const QString targetType) { auto it kTypeChart.find(moveType); if (it kTypeChart.end()) return 1.0; return it-value(targetType, 1.0); // 没匹配到的属性按普通伤害算 }伤害公式不用照搬原版复杂算法做小游戏重要的是“结果符合直觉”水枪打火系应该痛火花打水系应该刮痧。常见做法是基础伤害 (atk * power / def) 1再乘属性克制系数同属性技能再加1.2倍“本系加成”最后做一个2%的浮动。int calcDamage(const Pokemon attacker, const Move move, const Pokemon defender) { double base 1.0 * attacker.atk * move.power / qMax(1, defender.def) 1; double stab (attacker.type move.type) ? 1.2 : 1.0; double typeMul typeMultiplier(move.type, defender.type); double variation 0.98 QRandomGenerator::global()-bounded(5) / 100.0; int dmg qRound(base * stab * typeMul * variation); return qMax(1, dmg); // 伤害最差也是1 }qMax(1, dmg)和qMax(1, defender.def)是Qt全局函数比手写三目运算符清晰。防御力不可能为0所以对分母做钳制。随机浮动用QRandomGenerator::global()这是Qt 5.10以后的标准随机入口线程安全且一次性初始化不要再用过时的qsrand。战斗循环也控制在控制台内void runBattle(Pokemon player, Pokemon wild) { while (player.hp 0 wild.hp 0) { Pokemon first (player.speed wild.speed) ? player : wild; Pokemon second (player.speed wild.speed) ? wild : player; // 先手方随机选第一个技能释放 int dmg calcDamage(first, first.moves.first(), second); second.hp qBound(0, second.hp - dmg, second.maxHp); qDebug().noquote() first.name 造成 dmg 伤害 second.name 剩余 HP second.hp; } }顺序判定上我取速度高者先手同速时玩家先手避免随机平局破坏可预期性。qBound是把HP夹在0和maxHp之间最省事的写法。这段代码在命令行下可以反复跑不需要鼠标点击也不需要考虑窗口刷新非常适合拿单元测试去验证极端场景——比如满血一击秒杀、攻击力为1不除零。2.3 拆掉打印接上信号槽同一套内核平滑迁到QT控制台版本跑通后把“输出”和“输入”换成Qt机制战斗逻辑一行都不用改。做法是让战斗内核继承QObject把日志输出变成信号把外部操作变成槽class BattleCore : public QObject { Q_OBJECT public: explicit BattleCore(QObject* parent nullptr); void startBattle(Pokemon player, Pokemon wild); signals: void message(const QString text); // 替代 qDebug 输出 void battleEnded(bool playerWin); // 给界面切换胜负画面 void hpChanged(int playerHp, int wildHp); // 给血条更新 public slots: void useMove(int moveIndex); // 由界面按钮触发 void throwBall(); // 捕捉操作 };界面层只需要连接这些信号BattleCore* core new BattleCore(this); core-startBattle(player, wild); connect(core, BattleCore::message, this, [](const QString t){ logWidget-appendPlainText(t); }); connect(core, BattleCore::hpChanged, this, [](int a, int b){ playerBar-updateBar(a); wildBar-updateBar(b); });能这样迁移的前提是第2.2节的伤害公式和回合循环没有直接调用printf或std::cout而是把所有状态变化通过信号抛出去。界面只是战斗内核的一个“显示屏”这个思想贯穿整个项目。很多Qt游戏教程把伤害计算写在按钮的lambda里一换界面就得重写逻辑这是一开始没把边界划清的恶果。3. 用QGraphicsScene搭战斗场景qt绘图、血条和动画帧战斗逻辑就绪后界面层的任务只剩三件渲染宝可梦形象、展示血条、播放攻击动画。这里不建议用一堆QLabel叠位置而是用QGraphicsSceneQGraphicsView因为Qt绘图在场景体系里有现成的坐标变换、层级和动画回调QLabel做这些会非常别扭。3.1 场景、视图、精灵项三层结构各管什么QGraphicsView是窗口部件负责把场景画到屏幕上QGraphicsScene是逻辑坐标系管理所有图形项QGraphicsItem是单个精灵或血条。常见代码骨架如下auto* view new QGraphicsView(this); auto* scene new QGraphicsScene(view); view-setScene(scene); view-setRenderHint(QPainter::Antialiasing); view-setSceneRect(0, 0, 640, 360); // 固定战斗场景区域 auto* player new PokemonItem(:/images/player.png); player-setPos(80, 200); // 左下角 scene-addItem(player); auto* enemy new PokemonItem(:/images/enemy.png); enemy-setPos(420, 120); // 右上角 scene-addItem(enemy);PokemonItem我习惯直接继承QGraphicsObject因为它既能被场景管理又具备QObject的信号能力方便后续发hpChanged之类信号class PokemonItem : public QGraphicsObject { Q_OBJECT public: explicit PokemonItem(const QString imgPath); QRectF boundingRect() const override; void paint(QPainter* painter, const QStyleOptionGraphicsItem*, QWidget*) override; };boundingRect()返回图片的矩形范围paint()里就一行painter-drawPixmap(offset, pixmap)。注意setPos接收的是场景坐标y轴向下增长所以越往下y值越大。很多新手把左下角写成(80, 80)结果两个角色叠在左上角调半天位置这就是没弄清坐标系的问题。setSceneRect也要在addItem之前调用否则视图自动计算场景范围时可能因为空场景得到一个奇怪的默认尺寸。3.2 血条不贴QLabel用QGraphicsRectItem自绘血条这个部件最典型的错误是每帧更新QLabel的setGeometryQLabel内部有样式计算成本频繁刷新会出现肉眼可见的闪烁。更顺手的方案是两个叠加的QGraphicsRectItem底部红色满宽顶部绿色按比例变窄。class HealthBar : public QGraphicsObject { Q_OBJECT public: HealthBar(qreal width, qreal height); void updateBar(int hp, int maxHp) { qreal ratio qBound(0.0, 1.0 * hp / maxHp, 1.0); current width * ratio; update(); } protected: void paint(QPainter* p, const QStyleOptionGraphicsItem*, QWidget*) override { p-setPen(Qt::NoPen); p-setBrush(QColor(#cc3333)); p-drawRect(0, 0, width, height); p-setBrush(QColor(#33cc66)); p-drawRect(0, 0, current, height); } };paint里每次drawRect的第二个矩形宽度来自current颜色用深红当底、亮绿当上。这里有个细节current是qreal类型直接用比例乘宽度不要在外部转int否则低血量时血条会以1像素的阶梯跳变。边框用QPen但干扰视觉我选择Qt::NoPen。血条更新不重造控件只触发update()重绘这是Qt绘图性能好的原因——视图只在需要时重画脏矩形区域。3.3 QTimeLine做攻击动画帧回调与坐标插值攻击动画最常见的做法是“前冲固定距离再退回原点”。用QTimeLine按帧触发pos变化比起一个QTimer循环更简洁QTimeLine* tl new QTimeLine(400, this); // 400ms 完成一个攻击往返 tl-setUpdateInterval(16); // 约60fps tl-setEasingCurve(QEasingCurve::OutBack); // 冲出去再轻微回弹 QPointF origin playerItem-pos(); tl-setFrameRange(0, 100); connect(tl, QTimeLine::frameChanged, this, [](int frame){ qreal offset (frame 50) ? frame : 100 - frame; // 前50帧出拳后50帧回撤 playerItem-setPos(origin.x() offset * 1.2, origin.y()); }); connect(tl, QTimeLine::finished, this, []{ playerItem-setPos(origin); core-continueNextTurn(); // 动画结束后才允许下一步操作 }); tl-start();这里QTimeLine的参数直接决定了手感400ms是“干脆但不突兀”的时长短了像瞬移长了拖沓。frameChanged的信号参数是当前帧号我把它映射到0到100的进度以50帧为分界做折返移动。QEasingCurve::OutBack让冲拳过程中带轻微过冲视觉上比线性运动有弹性。还有一个关键点动画播放期间必须禁用技能按钮否则玩家连续点四次四个QTimeLine叠在一起精灵位置直接飞出屏幕。用bool isAnimating标志或者在动画开始时setEnabled(false)直到finished再恢复。3.4 输入响应让按钮和快捷键走同一个入口战斗界面的输入不止鼠标点击键盘快捷键也该支持。常见做法是给每个按钮配一个QShortcut但快捷键和点击最终都调到同一个方法QPushButton* attackBtn new QPushButton(攻击, this); attackBtn-setShortcut(QKeySequence(Qt::Key_1)); // 按1等于点攻击 connect(attackBtn, QPushButton::clicked, this, []{ core-useMove(0); }); QPushButton* ballBtn new QPushButton(捕捉, this); ballBtn-setShortcut(QKeySequence(Qt::Key_2)); connect(ballBtn, QPushButton::clicked, this, []{ core-throwBall(); });这样就不用在view里重写keyPressEvent避免了按键被其他窗口抢焦点时失效的问题。快捷键和点击汇聚到一个入口后续加逻辑只需要维护核心类不用管触发源。界面层越薄越不容易把游戏逻辑和表现层缠在一起。4. 背包、图鉴和存档JSON序列化与QTableView自定义model打完一场只是单次流程能让玩家“第二天接着玩”靠的是存档。背包道具、图鉴收集、已捕捉宝可梦列表都属于数据层我用JSON做持久化格式因为它容易读、容易改、坏了也容易定位。图鉴列表则要换成QTableView 自定义QAbstractTableModel这是qt表格大数据卡顿优化里最常被点名的一条路线。4.1 存档结构用QJsonDocument写出一份后悔药存档的最小结构包含玩家队伍、拥有的道具数量、图鉴解锁清单和当前场地进度。写档用QJsonObject组装bool saveGame(const PlayerState st, const QString path) { QJsonObject root; root[version] 1; // 版本号读档兼容用 root[scene] st.sceneId; root[gold] st.gold; QJsonArray team; for (const Pokemon p : st.team) { QJsonObject obj; obj[name] p.name; obj[type] p.type; obj[hp] p.hp; obj[maxHp] p.maxHp; obj[atk] p.atk; obj[def] p.def; obj[speed] p.speed; team.append(obj); } root[team] team; root[bag] QJsonObject{{ball, st.ballCount}, {potion, st.potionCount}}; QFile f(path); if (!f.open(QIODevice::WriteOnly)) return false; f.write(QJsonDocument(root).toJson(QJsonDocument::Indented)); return true; }toJson(QJsonDocument::Indented)是排过版的JSON调试时直接打开看到的就是树形缩进结构一眼能看出哪个字段丢了。存文件路径不要硬编码相对路径桌面应用装在哪个目录都可能正确做法是用QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)拼一个用户目录下的存档位置。读档比写档更考验容错bool loadGame(PlayerState st, const QString path) { QFile f(path); if (!f.open(QIODevice::ReadOnly)) return false; QJsonParseError err; QJsonDocument doc QJsonDocument::fromJson(f.readAll(), err); if (err.error ! QJsonParseError::NoError) return false; // 文件损坏 if (!doc.isObject()) return false; QJsonObject root doc.object(); if (!root.contains(version) || root[version].toInt() ! 1) return false; st.gold root[gold].toInt(); st.ballCount root[bag].toObject()[ball].toInt(); // 逐个字段校验缺任何一个字段都视为坏档不要用toInt的默认值硬抗 }读档时必须对每个字段做contains校验。一个只写到一半的文件toInt()会静默返回0玩家打开存档发现金币清零这种问题比闪退还可怕。版本号字段是后悔药将来数据结构变化时可以走迁移逻辑不至于把老档一刀切。4.2 图鉴从QTableWidget换到QTableView数据大时的卡顿来源如果图鉴只有几十条QTableWidget完全够用但图鉴条目一多、还要频繁和QVariant数据交互时QTableWidget的每个格子都是独立Cell控件对象卡顿会很明显。QTableView只创建可见区域的项数据从model按需取这正是表格大数据优化的核心思路。class PokedexModel : public QAbstractTableModel { Q_OBJECT public: int rowCount(const QModelIndex) const override { return entries.size(); } int columnCount(const QModelIndex) const override { return 3; } QVariant data(const QModelIndex idx, int role) const override { if (!idx.isValid()) return {}; const auto e entries[idx.row()]; if (role Qt::DisplayRole) { switch (idx.column()) { case 0: return e.name; case 1: return e.type; case 2: return e.caught ? 已捕捉 : 未捕捉; } } return {}; } };QTableView* table new QTableView(this); PokedexModel* model new PokedexModel(this); table-setModel(model); // 视图只显示可见行 table-setEditTriggers(QAbstractItemView::NoEditTriggers); table-setSelectionMode(QAbstractItemView::SingleSelection);data函数在每一行要显示时会触发一次视图滚动时按需调用几十次比一次性生成几千个QTableWidgetItem开销低一到两个数量级。这一层也是mvvm思路在Qt里的最轻量实现——model持有数据view只负责展示修改数据时发beginResetModel或dataChanged让视图局部刷新。如果未来加排序model排序后发一次layoutChanged视图和选中状态会同步重建。4.3 捕捉判定随机数、球的数量和失败兜底捕捉判定是回合制里的概率分支。简化公式bool catchPokemon(Pokemon wild, int ballCount) { if (ballCount 0) { emit message(没有精灵球了); return false; } ballCount--; double rate 0.9 - 0.4 * (1.0 * wild.hp / wild.maxHp); // 血量越低越容易 if (wild.hp wild.maxHp / 2) rate 0.2; bool ok QRandomGenerator::global()-generateDouble() rate; if (ok) { wild.hp wild.maxHp; // 捕捉后恢复满血 emit caught(wild); } else { emit message(球晃了两下还是逃出来了); } return ok; }generateDouble()返回0到1之间的double直接和概率比较比bounded(100)少一次归一化的脑内换算。捕捉失败时野生宝可梦可能会跑掉还要拖一个“回合继续”的信号出去如果捕捉成功图鉴条目里的caught要置true并发一次dataChanged让表格刷新。这里最容易踩的坑是捕捉成功时忘了把野生对象从场景里移除画面留着残影。正确的顺序是扣球数→概率判定→发消息→移除场景项→追加到队伍数据每一步依赖前一步成功不要在一个lambda里堆所有逻辑。5. 避坑排查qt崩溃、中文乱码、资源不显示和视图刷新的高频问题这部分写的是我自己踩过三遍以上的坑每一条都是“现象→原因→解决”的完整闭环。这些问题不解决项目规模再大也玩不下去尤其qt崩溃这种黑匣子问题最费时间。5.1 中文乱码MSVC编码和Qt5的UTF-8冲突现象源文件里写的“皮卡丘”运行时显示成“鐨偣涓”或者编译告警 C4819。原因是Qt 5在MSVC下默认把源文件按本地代码页GBK解析而文件实际存成了UTF-8两边对不上。解决分两步。第一步CMake里给MSVC加/utf-8编译选项if(MSVC) add_compile_options($$CXX_COMPILER_ID:MSVC:/utf-8) endif()第二步字符串常量在代码里统一用QString::fromUtf8(u8...)或者直接tr(...)包起来不要在头文件里放裸字符串字面量。Qt 6已经把默认编码换成UTF-8这个坑在Qt5时代几乎人人碰到。5.2 QObject生命周期翻车QGraphicsScene销毁后的悬空指针现象打完一场战斗切回主界面一按“继续”程序直接闪退崩溃栈指向QGraphicsScene::addItem附近。原因多半是new了一个PokemonItem后只add进场景没有设置parent而你在某个成员变量里缓存了这个指针场景被销毁时item也会被销毁但指针还留在成员变量里下一次战斗直接setPos访问已释放内存。解决方法是两件事同时做给item在创建时就挂上场景这个parent并且缓存指针时用QPointerPokemonItemauto* item new PokemonItem(:/images/enemy.png); scene-addItem(item); // item的owner归场景 m_enemy item; // 普通指针 QPointerPokemonItem m_enemy; // 安全版本场景销毁后自动变nullptr if (m_enemy) m_enemy-setPos(...);QPointer是Qt专门为QObject派生类设计的“弱引用”对象销毁后自动置空比裸指针多了一道保命符。另外connect lambda里如果捕获了this而this是场景或窗口对象要在connect第四个参数传this作为context否则对象析构后回调仍然可能被触发。5.3 资源文件不显示qrc路径前缀惹的祸现象代码编译通过运行后精灵图什么都不显示QPixmap::isNull()返回true界面是空白的。原因通常不是图片损坏而是资源路径拼写问题。qrc文件里如果注册的是/images/pika.png那代码里就必须写:/images/pika.png写成images/pika.png或者:pika.png都会静默失败。调试时先确认资源存在qDebug() QFile::exists(:/images/pika.png);如果返回false打开qrc文件检查有没有把新图片加进列表。改完qrc记得重新构建rcc只在构建时重新生成资源有时候改了图片内容但构建没重新执行上屏的还是旧图这是最容易被误判成“代码问题”的一环。除此之外setPixmap传入空QPixmap时不会报错只会画一个透明矩形所以看到空白先怀疑资源路径而不是怀疑代码逻辑。5.4 QTableView排序后选中错位行号会骗人现象图鉴点击表头按属性排序后点第二行背包里却用了第三条数据。原因是QTableView排序只会影响视图显示顺序model数据顺序并没变所以你在onClicked(index)里拿到的idx.row()是“视图行号”不是model里的实际行。解决方法是给每条数据加一个稳定id点击时通过行号拿到的数据项再去查唯一id不要直接用行号去QVector里索引。connect(table, QTableView::clicked, this, [](const QModelIndex idx){ int modelRow model-indexToEntry(idx); // 内部查id if (modelRow 0) { emit entrySelected(modelRow); } });或者不要开启排序只做固定顺序展示那行号就始终可信。小游戏图鉴通常不需要动态排序与其花时间同步排序状态不如直接禁掉表头点击排序把setSortingEnabled关掉。6. 进阶用QStateMachine拆战斗流程用QTest保住回归战斗流程从“选择技能”到“动画播放”再到“回合结算”如果用bool标志串分支一多必然乱。Qt自带的QStateMachine模块可以把这些步骤建模成状态图每个状态负责一个阶段转换条件写在transition里比手写枚举状态机直观得多。QStateMachine* sm new QStateMachine(this); QState* menu new QState(sm); // 等待玩家选择 QState* anim new QState(sm); // 播放攻击动画 QState* turnEnd new QState(sm); // 判定胜负/切换回合 menu-addTransition(attackBtn, QPushButton::clicked, anim); anim-addTransition(animTimer, QTimer::timeout, turnEnd); turnEnd-addTransition(core, BattleCore::turnFinished, menu); sm-setInitialState(menu); sm-start();状态之间的箭头就是addTransition触发源可以是按钮点击信号、计时器超时、或者核心类的自定义信号。写清楚状态图之后新增“逃跑”只需要加一个状态和两条transition不用去改for循环或switch。验证这套流程也不用手点——Qt Test里QSignalSpy可以监听任何信号配合QTest::mouseClick模拟鼠标点击事件做回归#include QTest #include QSignalSpy QSignalSpy spy(core, BattleCore::turnFinished); QTest::mouseClick(attackBtn, Qt::LeftButton); QVERIFY(spy.count() 1); // 点一下技能turnFinished恰好发一次这段测试把“界面按钮→战斗内核→回合结束信号”整条链路锁死了。我现在的习惯是每次改动核心逻辑先跑一遍这种回归再手动进游戏点两轮。以前我总在“感觉没问题”的情况下直接提交结果经常在一个改动后把捕捉判定弄坏而不自知。用QSignalSpy加上命令行里-test参数五分钟能把战斗内核的主要路径过一遍这个习惯帮我省了不少事。希望这篇路径能帮到你让你少走我当年撞过的那些暗坑。本文还有配套的精品资源点击获取
