简介：CocoKnightManager 是一套基于 Cocos Creator 的开源回合制游戏系统设计工程，面向希望掌握回合制玩法架构的初中级游戏开发者与独立团队，帮助其解决战斗流程抽象、角色状态管理与规则扩展等核心问题。压缩包共 22 个文件，约 216KB，以 json 配置、meta 资源描述、ts 脚本与 png 贴图为主，另含 fire 场景文件与 README 说明，整体结构轻量，便于快速导入引擎并对照阅读。项目围绕回合管理器、行动规则引擎与状态机三大组件展开，采用模块化拆分与数据驱动配置，属性、效果和事件均可通过 JSON 调整，降低编程耦合。已有 838 人学习，读者可从中获取一套可直接运行的回合制系统骨架、模块划分思路与脚本组织范例，适合作为二次开发起点或架构学习参考。
1. 回合制战斗的“骨架”长什么样：从一份 Cocos Creator 系统设计源码说起
回合制游戏最容易被低估的地方，不是战斗表现，而是“回合”本身怎么被管理。谁先手、技能结算顺序、状态机切换、战斗中断线重连后状态怎么恢复——这些逻辑一旦散落在各个脚本里，后期加一个 Buff 就能让整个战斗流程翻车。CocoKnightManager 这份开源系统设计源码，核心解决的就是这件事：把回合制战斗的流程控制、角色数据、技能结算拆成可复用的模块，跑在 Cocos Creator 上。它适合正在做回合制 Demo、想参考一套能落地的战斗系统分层写法的开发者，也适合已经写过一版战斗逻辑、但被状态管理折磨过的熟手。下面按“这套系统怎么组织 → 关键模块怎么接 → 哪里容易踩坑”的顺序拆。
2. 战斗系统的分层设计：为什么把回合控制和角色数据拆开
2.1 回合制游戏里最容易失控的三类状态
回合制战斗的状态可以粗分成三层：战斗全局状态（当前回合数、行动队列、胜负判定）、单位状态（血量、蓝量、Buff/Debuff、是否已行动）、技能结算状态（技能释放中、等待动画回调、结算完成）。新手常见的写法是把这三层塞进一个BattleManager里，用一堆布尔标志位控制流程，比如isPlayerTurn、isAnimating、isSkillCasting。刚开始能跑，一旦加入“反击”“追击”“持续伤害在回合开始时结算”这类机制，标志位之间就会互相打架，出现“动画播完了但回合没推进”或者“Buff 结算了两次”的玄学问题。
CocoKnightManager 的思路是把这三层拆成独立的职责：回合控制器只管“轮到谁、什么时候推进”，单位数据只管“我现在的属性是什么”，技能结算走一套独立的执行队列。这样做的直接好处是，加新机制时你只需要改对应那一层，不用去动其他两层的判断逻辑。常见做法是给每个单位挂一个状态组件，回合控制器通过接口读取“这个单位本回合能不能行动”，而不是直接读它的内部字段。
2.2 目录结构与模块职责对照
拿到源码包后，先别急着跑，花十分钟把目录结构过一遍，后面改代码会省很多时间。典型的 Cocos Creator 项目结构大致如下（不同版本目录名可能略有差异，以实际包内为准）：
| 目录/文件 | 职责 | 改动频率 |
|---|---|---|
assets/scripts/battle/ | 回合控制器、行动队列、胜负判定 | 低，机制稳定后基本不动 |
assets/scripts/unit/ | 单位数据、属性计算、状态组件 | 中，加新属性时改 |
assets/scripts/skill/ | 技能配置、结算执行器 | 高，新技能都在这加 |
assets/scripts/ui/ | 血条、行动条、伤害飘字 | 中 |
assets/resources/ | 技能表、单位配置等数据文件 | 高，策划改 |
assets/scenes/ | 战斗场景、预制体 | 低 |
这个划分的关键在于：battle层不直接操作 UI，ui层不直接改单位数据，两边都通过事件或回调通信。很多项目后期难维护，就是因为 UI 脚本里直接unit.hp -= damage，导致数据流变成一张网。
2.3 回合推进的核心循环怎么读
回合控制器的核心逻辑通常是一个“行动队列 + 状态机”的组合。下面是一段简化后的伪代码，用来理解它的推进节奏（实际源码里会有更多边界判断）：
// 回合控制器核心循环（简化示意） class TurnController { constructor(units) { this.units = units; this.turnIndex = 0; this.actionQueue = []; // 本回合待行动单位 } // 开始新回合：按速度排序生成行动队列 startNewTurn() { this.turnIndex++; this.actionQueue = this.units .filter(u => u.isAlive()) .sort((a, b) => b.speed - a.speed); // 速度降序 this.processNextAction(); } // 处理队列中的下一个单位 processNextAction() { if (this.actionQueue.length === 0) { this.startNewTurn(); // 队列空，进入下一回合 return; } const current = this.actionQueue.shift(); if (!current.isAlive()) { this.processNextAction(); // 跳过死亡单位 return; } this.emit('unitTurnStart', current); // 通知 UI 和技能系统 } // 单位行动结束后由外部调用 onUnitActionEnd(unit) { this.emit('unitTurnEnd', unit); this.processNextAction(); } }这段代码里有两个参数值得注意：speed决定行动顺序，isAlive()决定是否跳过。实际项目中，速度相同的单位还需要一个稳定的次级排序（比如按单位 ID），否则每回合顺序可能抖动，玩家会觉得“玄学”。另外onUnitActionEnd由外部调用这一点很关键——它意味着回合推进不依赖动画时长，动画只是表现层，逻辑层该推进就推进。这是避免“动画卡住导致回合不结束”的根本办法。
3. 单位与技能模块的落地：数据驱动和结算顺序
3.1 单位数据用配置表还是脚本硬编码
CocoKnightManager 采用的是配置表驱动的方式：单位的基础属性（血量、攻击、速度）和技能列表放在resources下的数据文件里，脚本只负责读取和计算。这个选择的理由很实际——回合制游戏的数值调整频率极高，如果属性写死在脚本里，每次调平衡都要改代码、重新编译，效率太低。
配置表的结构通常长这样（JSON 示意）：
{ "id": "knight_001", "name": "重装骑士", "baseHp": 1200, "baseAtk": 85, "baseDef": 60, "speed": 42, "skills": ["skill_shield_bash", "skill_taunt"] }读取时用一个UnitFactory把配置转成运行时对象，运行时对象上再挂 Buff 列表和当前血量。这里有个容易忽略的点：配置表里的baseHp是基础值，实际血量要经过装备、Buff、关卡加成等多层计算，所以运行时对象必须保留“基础值”和“最终值”两套字段，否则 Buff 到期后回滚会算错。我一般会在单位类里明确区分baseStats和finalStats，每次属性变化都从baseStats重新算一遍finalStats，而不是在finalStats上做加减——后者在多层 Buff 叠加时几乎必然出错。
3.2 技能结算的执行队列与顺序问题
技能结算是回合制里最容易出 Bug 的地方。一个技能可能包含：前置条件检查 → 消耗资源 → 播放动画 → 计算伤害 → 应用 Buff → 触发被动 → 检查死亡 → 推进回合。这些步骤如果写成同步顺序调用，动画一异步就乱套；如果全用回调嵌套，代码会变成回调地狱。
源码里的做法是引入一个轻量的执行队列：每个技能被拆成若干“步骤对象”，队列按顺序执行，每个步骤执行完调用next()。下面是一个简化的执行器示意：
// 技能步骤执行器（简化示意） class SkillExecutor { constructor(steps) { this.steps = steps; this.index = 0; } run(context) { if (this.index >= this.steps.length) { context.onComplete && context.onComplete(); return; } const step = this.steps[this.index++]; step.execute(context, () => this.run(context)); // 每步执行完回调继续 } } // 一个伤害技能的步骤定义 const damageSkillSteps = [ { execute: (ctx, next) => { ctx.checkCost(); next(); } }, { execute: (ctx, next) => { ctx.playAnimation('attack', next); } }, { execute: (ctx, next) => { ctx.calcDamage(); next(); } }, { execute: (ctx, next) => { ctx.applyDamage(); next(); } }, { execute: (ctx, next) => { ctx.checkDeath(); next(); } } ];这个模式的好处是每个步骤职责单一，加新步骤（比如“触发反击检查”）只需要往数组里插一项，不用改执行器本身。参数上要注意context对象要贯穿整个技能生命周期，里面存着施法者、目标、伤害值等中间结果，步骤之间靠它传递数据。常见翻车点是：某个步骤忘了调next()，整个队列就停在那里，表现就是“技能放一半卡住”。排查时优先看每个execute是否都有回调出口。
3.3 把战斗事件接到 UI 层
逻辑层和表现层的解耦靠事件。回合控制器和技能执行器在关键节点发出事件（unitTurnStart、damageDealt、unitDied），UI 层订阅这些事件更新血条和飘字。这样做的实际收益是：你可以在不启动 UI 的情况下跑逻辑测试，也可以换一套 UI 而不动战斗逻辑。
订阅时要注意解绑。Cocos Creator 里节点销毁后如果事件监听没移除，回调里访问已销毁节点会报错。常见做法是在onDestroy里统一off掉本组件注册的所有监听，或者用一个事件中心统一管理订阅关系。这个坑几乎每个项目都会踩一次，表现是切场景后控制台刷一堆“target is null”。
4. 避坑与排查：这套系统落地时最容易翻车的几处
4.1 现象：回合推进了但动画还在播，下一回合的技能打到了上一回合的目标
原因：逻辑层推进不等表现层，而技能结算里又依赖了“当前目标”这种会被下一回合覆盖的引用。解决：技能执行时把目标引用快照到context里，后续步骤只读快照，不读全局的“当前选中目标”。同时给表现层加一个“忙碌”标记，逻辑层推进前检查该标记，但不阻塞逻辑本身。
4.2 现象：Buff 到期后属性没有回滚，角色血量越打越多
原因：属性计算在finalStats上做增量加减，Buff 叠加和移除的顺序不一致导致误差累积。解决：改成每次属性变化都从baseStats全量重算，Buff 只作为计算输入，不作为修改目标。这个改动初期会觉得“每次重算好麻烦”，但它是唯一能保证多层 Buff 正确的做法。
4.3 现象：速度相同的单位每回合行动顺序不一样
原因：排序算法不稳定，相同speed的元素相对顺序不确定。解决：排序时加次级键，比如sort((a,b) => b.speed - a.speed || a.id.localeCompare(b.id))，保证同速单位顺序固定。这个细节玩家感知很强，属于血泪经验。
4.4 现象：技能执行到一半卡住，没有任何报错
原因：某个步骤的异步回调没有触发next()，队列停摆。解决：给执行器加超时保护，每个步骤超过设定时长（比如 3 秒）强制推进并打日志，日志里带上步骤名和技能 ID。排查时先看日志停在哪一步，再去看那一步的回调出口。
4.5 现象：切场景后控制台报节点已销毁
原因：事件监听没解绑，回调访问了已销毁的 UI 节点。解决：组件onDestroy里统一移除监听，或者用事件中心按订阅者批量清理。养成“注册即记录、销毁即清理”的习惯，能省掉大量排查时间。
5. 进阶用法：用这套结构快速验证一个新机制
这套系统设计真正的价值不在“能跑一个战斗”，而在于它给了你一个可以快速试错的骨架。举个具体例子：想加一个“行动条”机制（类似速度累积到阈值才行动），你不需要重写回合控制器，只需要替换行动队列的生成逻辑。
// 行动条模式：每个单位累积行动值，达到阈值者行动 class ActionGaugeController { constructor(units, threshold = 100) { this.units = units; this.threshold = threshold; // 行动阈值，可调 } tick() { // 每帧或每逻辑步给所有存活单位累积行动值 this.units.forEach(u => { if (u.isAlive()) u.gauge += u.speed * 0.1; // 0.1 是时间系数 }); // 找出达到阈值的单位，按超出量排序 const ready = this.units .filter(u => u.isAlive() && u.gauge >= this.threshold) .sort((a, b) => b.gauge - a.gauge); if (ready.length > 0) { const actor = ready[0]; actor.gauge -= this.threshold; // 扣除阈值，保留溢出 return actor; } return null; } }这段代码里threshold和0.1这两个参数决定了战斗节奏：阈值越低、系数越大，行动越频繁。调这两个值就能在不改任何技能逻辑的情况下改变整体手感，这正是分层设计带来的便利。验证时我一般会先关掉动画，用纯逻辑跑 100 回合，打印每回合的行动序列，确认没有死循环和顺序抖动，再接 UI。从那以后我每次改战斗核心逻辑，都强制先跑一遍无 UI 的逻辑回归，再开画面看表现——这个习惯帮我挡掉了至少一半的“看起来是动画问题、实际是逻辑问题”的排查时间。希望这套拆法能帮到你。
本文还有配套的精品资源，点击获取
