簡介CocoKnightManager 是一套基于 Cocos Creator 引擎的開源回合制游戲系統(tǒng)設(shè)計工程面向希望掌握回合制玩法架構(gòu)的初中級游戲開發(fā)者與獨(dú)立團(tuán)隊。項目以模塊化為核心將回合管理器、行動規(guī)則引擎與角色狀態(tài)機(jī)拆分為獨(dú)立組件并通過 JSON 等數(shù)據(jù)配置驅(qū)動屬性、效果與事件便于靈活組合與二次擴(kuò)展。壓縮包共 22 個文件約 216KB包含 7 個 json 配置、7 個 meta 資源描述、3 張 png 貼圖、2 個 ts 腳本及 fire、md 等工程與說明文件完整呈現(xiàn)了場景、腳本與配置的組織方式。目前已有 836 人學(xué)習(xí)下載。讀者可從中獲取回合流程控制、行動規(guī)則抽象與狀態(tài)切換的參考實現(xiàn)理解數(shù)據(jù)驅(qū)動設(shè)計如何降低內(nèi)容調(diào)整成本并借助開源代碼快速搭建自己的回合制原型節(jié)省底層系統(tǒng)搭建時間。1. 回合制戰(zhàn)斗的骨架CocoKnightManager 到底管了什么很多回合制項目死在“戰(zhàn)斗邏輯和界面糊在一起”上按鈕點(diǎn)一下傷害計算、動畫播放、狀態(tài)刷新全塞在同一個回調(diào)里改一個技能要翻五個文件。CocoKnightManager 這個開源工程就是沖著這個痛點(diǎn)來的它把回合制游戲里最容易失控的那部分——回合調(diào)度、行動隊列、技能結(jié)算、狀態(tài)機(jī)切換——單獨(dú)抽成一套可復(fù)用的系統(tǒng)層Cocos Creator 只負(fù)責(zé)表現(xiàn)。換句話說它管的不是“一個騎士長什么樣”而是“誰先動、動了之后世界變成什么樣”。適合兩類人手里有 Cocos Creator 基礎(chǔ)、想做一個能擴(kuò)展的回合制 Demo 的開發(fā)者以及已經(jīng)寫過一版戰(zhàn)斗邏輯、被狀態(tài)同步和技能疊加折磨過、想看看別人怎么分層的人。系統(tǒng)開源代碼結(jié)構(gòu)比功能數(shù)量更值得看。2. 工程結(jié)構(gòu)與技術(shù)選型為什么把戰(zhàn)斗邏輯從節(jié)點(diǎn)樹里拽出來2.1 目錄分層表現(xiàn)層、系統(tǒng)層、數(shù)據(jù)層三刀切拿到工程先別急著點(diǎn)運(yùn)行把目錄掃一遍能省掉后面一半的迷茫。這個項目的目錄不是按“場景/預(yù)制體/腳本”這種引擎默認(rèn)習(xí)慣堆的而是按職責(zé)切assets/ scripts/ core/ # 回合調(diào)度器、行動隊列、事件總線 TurnManager.ts ActionQueue.ts EventBus.ts battle/ # 戰(zhàn)斗規(guī)則傷害公式、技能結(jié)算、buff 疊加 BattleContext.ts SkillResolver.ts BuffSystem.ts units/ # 單位數(shù)據(jù)與運(yùn)行時狀態(tài) UnitModel.ts UnitState.ts ui/ # 純表現(xiàn)血條、行動條、飄字 BattleHUD.ts TurnIndicator.ts prefabs/ units/ # 單位預(yù)制體只掛表現(xiàn)腳本 data/ skills.json # 技能配置邏輯層讀取 units.json # 單位基礎(chǔ)屬性core不 import 任何cc的 UI 組件battle只依賴core和unitsui單向依賴battle暴露的事件。這條依賴方向是整個工程能二次開發(fā)的前提——你想換一套美術(shù)表現(xiàn)只動ui和prefabs規(guī)則層一行不用碰。2.2 技術(shù)棧與版本假設(shè)TypeScript 事件驅(qū)動工程用 TypeScript 寫Cocos Creator 3.x 的組件體系。為什么強(qiáng)調(diào) TS回合制的狀態(tài)字段多當(dāng)前 HP、行動值、buff 剩余回合、技能冷卻用any滿天飛的 JS 寫兩周后自己都不記得state.t是回合數(shù)還是目標(biāo)。項目里UnitState是個明確的接口// units/UnitState.ts export interface UnitState { id: string; // 單位唯一標(biāo)識戰(zhàn)斗內(nèi)不變 hp: number; // 當(dāng)前生命 maxHp: number; actionValue: number; // 行動值越小越先動 buffs: BuffInstance[]; // 當(dāng)前掛載的 buff 列表 cooldowns: Recordstring, number; // 技能 id - 剩余冷卻回合 }字段含義直接決定調(diào)度邏輯actionValue用“越小越先動”而不是“速度越大越先動”是為了讓插入行動比如某個技能讓目標(biāo)立刻再動一次變成簡單的數(shù)值減法不用重排整個隊列。這是回合制里很常見的一個設(shè)計取舍新手容易一開始用速度排序后面加“推條/拉條”技能時就得推倒重來。2.3 事件總線UI 不輪詢邏輯不碰節(jié)點(diǎn)EventBus是個極簡的發(fā)布訂閱沒有引入第三方庫。核心就三個方法on、off、emit。戰(zhàn)斗層算完一次傷害emit(unit:damaged, payload)UI 層監(jiān)聽后播飄字、刷血條。好處是邏輯層完全不知道血條節(jié)點(diǎn)叫什么名字測試時甚至可以不起場景直接跑純邏輯。// core/EventBus.ts type Handler (payload?: any) void; export class EventBus { private static handlers: Mapstring, Handler[] new Map(); static on(event: string, fn: Handler) { const list this.handlers.get(event) ?? []; list.push(fn); this.handlers.set(event, list); } static off(event: string, fn: Handler) { const list this.handlers.get(event); if (!list) return; this.handlers.set(event, list.filter(h h ! fn)); // 防止重復(fù)注冊導(dǎo)致回調(diào)疊加 } static emit(event: string, payload?: any) { this.handlers.get(event)?.forEach(fn fn(payload)); } }參數(shù)說明event用模塊:動作的命名約定unit:damaged、turn:start、skill:cast避免不同模塊撞名payload不約束類型是刻意的簡化但實際項目里建議按事件名建一個 payload 類型映射表否則半年后沒人記得turn:start帶的是回合數(shù)還是單位 id。這里就是典型的“先跑通再收緊”的寫法。3. 回合調(diào)度核心TurnManager 與 ActionQueue 怎么配合3.1 行動隊列用最小堆還是排序數(shù)組回合制的“誰先動”本質(zhì)是個優(yōu)先隊列問題。項目里ActionQueue用的是排序數(shù)組而不是堆原因很實際一場戰(zhàn)斗通常 612 個單位每次取最小值時sort一下的開銷可以忽略而數(shù)組在調(diào)試時能直接console.log看到完整順序堆看不到。這是典型的“規(guī)模決定數(shù)據(jù)結(jié)構(gòu)”的取舍別一上來就上堆。// core/ActionQueue.ts import { UnitState } from ../units/UnitState; export class ActionQueue { private units: UnitState[] []; push(unit: UnitState) { this.units.push(unit); } // 取出行動值最小的單位行動值相同則按 id 穩(wěn)定排序 popNext(): UnitState | undefined { this.units.sort((a, b) a.actionValue ! b.actionValue ? a.actionValue - b.actionValue : a.id.localeCompare(b.id) ); return this.units.shift(); } // 行動結(jié)束后把單位放回隊列并推進(jìn)其行動值 requeue(unit: UnitState, baseActionValue: number) { unit.actionValue baseActionValue; // 累加而非重置保證速度差異體現(xiàn)在長期頻率上 this.units.push(unit); } peekAll(): UnitState[] { return [...this.units].sort((a, b) a.actionValue - b.actionValue); } }關(guān)鍵在requeue里的而不是。如果每次行動后把行動值重置成固定值那速度屬性就只影響第一次出手后面大家輪流坐莊回合制的節(jié)奏感就沒了。累加的做法讓“速度 120 的單位每 100 行動值動一次、速度 80 的每 150 動一次”這種頻率差異自然浮現(xiàn)。peekAll是給 UI 畫行動條用的返回副本防止外部改到內(nèi)部數(shù)組。3.2 TurnManager一個回合的完整生命周期TurnManager是調(diào)度的大腦它不關(guān)心傷害怎么算只負(fù)責(zé)“輪到誰、什么時候開始、什么時候結(jié)束”。一個回合的鏈路是turn:start→ 取隊首單位 → 檢查能否行動眩暈等控制→ 交給外部決策玩家輸入或 AI→ 執(zhí)行行動 →turn:end→ 單位回隊 → 下一回合。// core/TurnManager.ts import { ActionQueue } from ./ActionQueue; import { EventBus } from ./EventBus; import { UnitState } from ../units/UnitState; export class TurnManager { private queue new ActionQueue(); private round 0; private current: UnitState | null null; init(units: UnitState[]) { units.forEach(u this.queue.push(u)); } startNextTurn(): UnitState | null { const next this.queue.popNext(); if (!next) return null; this.current next; this.round; EventBus.emit(turn:start, { unit: next, round: this.round }); // 控制類狀態(tài)在這里攔截而不是散落在各技能里 if (this.isStunned(next)) { EventBus.emit(turn:skipped, { unit: next }); this.endTurn(); return this.startNextTurn(); // 遞歸推進(jìn)到下一個可行動單位 } return next; } endTurn() { if (!this.current) return; EventBus.emit(turn:end, { unit: this.current }); this.queue.requeue(this.current, this.current.baseActionValue ?? 100); this.current null; } private isStunned(u: UnitState): boolean { return u.buffs.some(b b.type stun b.remaining 0); } }這里有兩個值得抄的點(diǎn)。第一控制狀態(tài)眩暈、冰凍統(tǒng)一在startNextTurn里攔截而不是讓每個技能自己判斷“目標(biāo)能不能動”否則新增一種控制就要改 N 個技能。第二被跳過回合的單位仍然走endTurn回隊保證行動值正常推進(jìn)不會因為被控就永久掉隊。遞歸調(diào)用startNextTurn在極端情況下全隊被控會棧溢出實際項目里建議改成while循環(huán)這是我在類似結(jié)構(gòu)上翻過車的地方。3.3 和 UI 的對接行動條只讀 peekAllTurnIndicator這個 UI 組件每幀或每次turn:start時調(diào)queue.peekAll()拿排序后的單位列表按順序擺頭像。它不持有任何調(diào)度邏輯也不改隊列。這種“UI 只讀、邏輯只寫”的邊界是后面加“預(yù)覽未來三回合行動順序”功能時不用動核心代碼的原因。如果你接手后發(fā)現(xiàn)行動條和實際出手順序?qū)Σ簧习顺墒?UI 自己維護(hù)了一份順序而不是讀peekAll。4. 技能結(jié)算與 Buff 系統(tǒng)傷害公式和狀態(tài)疊加怎么不打架4.1 SkillResolver把“技能”拆成配置加解析器技能不寫成一個個類而是skills.json里的數(shù)據(jù) 一個統(tǒng)一的SkillResolver解析。這樣加新技能是改配置不是加文件。配置長這樣{ id: slash, name: 橫斬, targetType: enemy_single, effects: [ { type: damage, power: 1.2, scaling: atk }, { type: buff, buffId: bleed, chance: 0.3, duration: 2 } ], cooldown: 2 }effects是數(shù)組意味著一個技能可以同時造成傷害和掛 buff順序執(zhí)行。chance讓概率類效果不用寫進(jìn)代碼。解析器按type分發(fā)// battle/SkillResolver.ts import { BattleContext } from ./BattleContext; import { BuffSystem } from ./BuffSystem; export class SkillResolver { static resolve(ctx: BattleContext, casterId: string, targetId: string, skill: any) { const caster ctx.getUnit(casterId); const target ctx.getUnit(targetId); if (!caster || !target) return; for (const effect of skill.effects) { if (effect.chance ! undefined Math.random() effect.chance) continue; switch (effect.type) { case damage: { const base caster.atk * effect.power; // 攻擊力 × 倍率 const reduced base * (1 - target.def / (target.def 100)); // 防御減傷100 是調(diào)參常數(shù) const final Math.max(1, Math.round(reduced)); // 保底 1 點(diǎn)防止高防無敵 target.hp - final; ctx.emit(unit:damaged, { unitId: targetId, amount: final, source: casterId }); break; } case buff: BuffSystem.apply(target, effect.buffId, effect.duration ?? 1); break; } } } }防御減傷用def / (def 100)而不是直接減法是為了避免“防御堆到超過攻擊力就完全免傷”的數(shù)值崩壞這是回合制里最常見的公式選擇。Math.max(1, ...)的保底也是血淚經(jīng)驗沒有它高防單位會讓戰(zhàn)斗變成無限平局。常數(shù) 100 是調(diào)參入口想讓你游戲前期節(jié)奏快就調(diào)小后期數(shù)值膨脹就調(diào)大。4.2 BuffSystem疊加規(guī)則必須顯式定義Buff 最容易出 bug 的地方不是“加沒加上”而是“同一個 buff 加兩次會怎樣”。項目里BuffInstance帶remaining和stacks疊加策略在BuffSystem.apply里按 buff 類型查表// battle/BuffSystem.ts import { UnitState } from ../units/UnitState; interface BuffDef { id: string; type: stun | bleed | atk_up; stackMode: refresh | stack | ignore; // 疊加策略 maxStacks?: number; } export class BuffSystem { static apply(unit: UnitState, buffId: string, duration: number) { const def BuffSystem.getDef(buffId); const existing unit.buffs.find(b b.id buffId); if (!existing) { unit.buffs.push({ id: buffId, type: def.type, remaining: duration, stacks: 1 }); return; } switch (def.stackMode) { case refresh: // 只刷新持續(xù)時間不疊層 existing.remaining Math.max(existing.remaining, duration); break; case stack: // 疊層受上限約束 existing.stacks Math.min((existing.stacks ?? 1) 1, def.maxStacks ?? 99); existing.remaining Math.max(existing.remaining, duration); break; case ignore: // 已存在則不再施加 break; } } // 每回合結(jié)束時統(tǒng)一遞減避免各技能自己減導(dǎo)致漏減或雙減 static tickAll(unit: UnitState) { unit.buffs.forEach(b b.remaining--); unit.buffs unit.buffs.filter(b b.remaining 0); } private static getDef(id: string): BuffDef { // 實際項目從 buffs.json 讀這里給默認(rèn)值示意 return { id, type: bleed, stackMode: refresh }; } }tickAll統(tǒng)一在turn:end時對全場單位調(diào)用一次而不是讓每個 buff 自己記時。這樣“持續(xù) 2 回合”的語義是確定的施加當(dāng)回合不算之后兩個回合結(jié)束各減一次。很多項目 buff 時長錯亂就是因為施加時機(jī)和遞減時機(jī)分散在不同地方。4.3 BattleContext一次戰(zhàn)斗的共享狀態(tài)容器BattleContext持有所有單位、當(dāng)前回合數(shù)、隨機(jī)數(shù)種子如果要回放戰(zhàn)斗并提供getUnit、emit等便捷方法。它不寫業(yè)務(wù)邏輯只做狀態(tài)聚合。這樣SkillResolver和BuffSystem都是無狀態(tài)的靜態(tài)方法測試時構(gòu)造一個BattleContext塞幾個UnitState就能跑不用起 Cocos 場景。這是整個工程最值得學(xué)的一點(diǎn)把“能純邏輯測試”當(dāng)成架構(gòu)目標(biāo)而不是事后補(bǔ)測試。5. 避坑與排查跑起來之后最容易卡住的幾個點(diǎn)5.1 現(xiàn)象行動條順序和實際出手對不上原因通常是 UI 自己緩存了一份順序或者peekAll返回的是內(nèi)部數(shù)組引用被外部改了。解決確認(rèn)peekAll返回副本工程里用了[...this.units]UI 每次turn:start重新拉取不要onLoad時拉一次就存著。另外檢查requeue的有沒有被誤改成。5.2 現(xiàn)象某個單位被眩暈后永久不再行動原因startNextTurn里被跳過的單位沒有走endTurn沒回隊列。解決跳過分支里必須先endTurn再遞歸/循環(huán)取下一個。工程里遞歸寫法在“連續(xù)多個單位被控”時還可能棧溢出建議改成while (true)循環(huán)取到可行動單位再break。5.3 現(xiàn)象buff 持續(xù)時間比配置多一回合或少一回合原因施加 buff 的時機(jī)和tickAll的時機(jī)在同一回合內(nèi)順序不定。解決約定tickAll只在turn:end調(diào)用一次且施加 buff 的技能結(jié)算發(fā)生在turn:start之后、turn:end之前。如果技能是在turn:end里觸發(fā)的比如持續(xù)傷害要明確它是否參與當(dāng)回合遞減工程里默認(rèn)不參與。5.4 現(xiàn)象傷害飄字重復(fù)播放或播放兩次原因EventBus.on在組件onEnable里注冊但onDisable沒off場景切換后舊回調(diào)還在。解決所有on必須配對off或者用onEnable/onDisable成對管理。EventBus是靜態(tài)的生命周期比節(jié)點(diǎn)長這是靜態(tài)事件總線最常見的坑。5.5 現(xiàn)象技能配置改了但游戲里沒生效原因skills.json被 Cocos 當(dāng)資源加載后緩存或者路徑寫錯讀到了舊文件。解決確認(rèn) JSON 放在resources下用resources.load讀改完清一次構(gòu)建緩存開發(fā)期可以在BattleContext初始化時打印讀到的技能數(shù)量數(shù)量不對就是沒讀到。6. 二次開發(fā)換一套戰(zhàn)斗規(guī)則要動哪幾層想把這個工程改成自己的游戲最省力的路徑是從數(shù)據(jù)層往上改而不是從 UI 往下改。第一步改units.json和skills.json把職業(yè)、技能、數(shù)值換成你的設(shè)定這一步不動代碼就能看到完全不同的戰(zhàn)斗。第二步如果要做“多段攻擊”或“追擊”在SkillResolver的effects里加一個type: multi_hit分支按hits字段循環(huán)調(diào)用傷害計算注意每段都要單獨(dú)emit飄字事件否則 UI 只顯示一次。第三步如果要做“行動條推拉”在ActionQueue加modifyActionValue(unitId, delta)直接改actionValue后重新sort因為隊列規(guī)模小不用維護(hù)堆的索引。驗證改造是否正確的辦法很土但有效寫一個純邏輯的測試腳本不啟動 Cocos直接new TurnManager()、塞三個UnitState、循環(huán)調(diào)startNextTurn和endTurn二十次打印每次出手的單位 id 和行動值。如果順序和頻率符合預(yù)期再回引擎里接 UI。這個習(xí)慣讓我在改數(shù)值和調(diào)度規(guī)則時少走了很多“改完跑場景看半天”的彎路。改造目標(biāo)要動的文件是否碰 UI換數(shù)值/技能data/*.json否加新效果類型SkillResolver.ts否改出手頻率規(guī)則ActionQueue.ts否加新控制狀態(tài)TurnManager.ts BuffSystem.ts否換表現(xiàn)/動畫ui/ prefabs/是最后說個我自己的教訓(xùn)早期我總想先把架構(gòu)設(shè)計得很完整再寫結(jié)果TurnManager里塞了太多“以后可能用到”的鉤子反而看不清主鏈路。這個工程的好處是每個類都只干一件事你接手時先跑通默認(rèn)戰(zhàn)斗再按上表逐層替換比一上來就重構(gòu)整個調(diào)度器穩(wěn)得多。從那以后我每次改回合制邏輯都強(qiáng)制先跑一遍純邏輯腳本再進(jìn)引擎希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取