pan/pixelheros
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(cardSkill): 完成卡牌技能触发机制类型化改造

Browse Source 
本次提交为全量的卡牌技能触发系统重构，主要变更包括：
1.  新增CardTriggerType枚举，统一卡牌触发类型定义
2.  补全依赖事件派发：每波战斗结束FightEnd、英雄死亡HeroDead（带阵营过滤）、复活成功ReviveSuccess
3.  重构SkillBoxComp，按触发类型动态注册事件监听，拆分即时/定时/驻场/事件型逻辑
4.  批量迁移所有卡牌配置，为旧技能补充显式触发类型
5.  新增全局触发次数上限机制，区分每波/全局触发计数规则
6.  新增配套设计文档，记录改造背景与方案细节

本次重构彻底解决了原有隐式配置难以维护、无法支持事件型触发的痛点，实现了技能触发逻辑的标准化与可扩展性。
This commit is contained in:
panFD
2026-06-19 23:01:24 +08:00
parent a866cba8d1
commit dc8391847b
14 changed files with 4924 additions and 2125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
assets/script/game/map/SkillBoxComp.ts
View File

@@ -4,23 +4,27 @@
*
* 职责：
* 1. 表示一张已使用的技能卡在战场上的 **可视化实体**。
* 2. 管理技能的 **触发逻辑**：即时触发 vs 定时触发（战斗中按间隔触发）。
* 2. 按 trigger_type 类型化分发触发逻辑（即时 / 定时 / 驻场 / 事件型）。
* 3. 显示技能图标和剩余触发次数。
* 4. 触发结束后自动销毁。
*
* 关键设计：
* - is_instant=true（即时技能）：init 时立即触发一次，播放后延迟销毁。
* - is_instant=false（持续技能）：战斗中每隔 trigger_interval 秒触发一次，
* 共触发 trigger_times 次后销毁。
* - 新一波（NewWave）时如果持续技能的次数已用完则销毁。
* - 销毁时通过 GameEvent.RemoveSkillBox 通知 MissSkillsComp 回收槽位。
* 触发类型（CardTriggerType）：
* - Instant (1)：init 时立即触发一次（按 t_times 控制次数，跨波次 NewWave 时再次触发）
* - Interval (2)：监听 FightStart → update 帧驱动按 t_inv 间隔重复触发（按 t_times 控制每波次数）
* - Field (3)：被动生效，不主动施法（实际由 FieldSkillSet 处理）
* - FightStart (4)：监听 FightStart 事件，按 trigger_limit 全局累计上限
* - FightEnd (5)：监听 FightEnd 事件（每波结束派发），按 trigger_limit 全局累计上限
* - HeroDead (6)：监听 HeroDead 事件（仅英雄阵营派发，怪物死亡不触发）
* - HeroCall (7)：监听 MasterCalled（主角/技能召唤）+ ReviveSuccess（复活）
*
* 触发技能的方式：
* - 通过 GameEvent.TriggerSkill 事件，将技能 UUID、卡牌等级、
* 触发位置等信息分发给技能系统。
* 关键设计：
* - 事件型（4-7）统一走 onEventTrigger 入口，仅作触发信号，不读取 payload
* - 触发上限：Instant/Interval 按 t_times（每波内），事件型按 trigger_limit（全局）
* - 跨波次：keep_waves 控制存活；事件型 trigger_count 不随波次重置
* - 销毁时通过 GameEvent.RemoveSkillBox 通知 MissSkillsComp 回收槽位
*
* 依赖：
* - CardPoolList（CardSet）—— 查询技能卡的触发配置（t_times / t_inv / is_inst）
* - CardPoolList / CardTriggerType（CardSet）—— 查询技能卡的触发配置
* - SkillSet —— 技能静态配置（icon 字段）
* - GameEvent —— 各类游戏事件
* - smc.mission —— 游戏运行状态
@@ -29,7 +33,7 @@ import { mLogger } from "../common/Logger";
import { _decorator, Node, Prefab, Sprite, Label, Vec3, resources, SpriteAtlas, tween, v3, Tween, NodeEventType } from "cc";
import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
import { CCComp } from "../../../../extensions/oops-plugin-framework/assets/module/common/CCComp";
import { CardPoolList } from "../common/config/CardSet";
import { CardPoolList, CardTriggerType } from "../common/config/CardSet";
import { SkillSet, SkillOverrides } from "../common/config/SkillSet";
import { oops } from "db://oops-framework/core/Oops";
import { GameEvent } from "../common/config/GameEvent";
@@ -79,6 +83,15 @@ export class SkillBoxComp extends CCComp {
/** 驻场技能 UUID 列表 */
public field: number[] = [];
// ======================== 触发类型化扩展 ========================
/** 触发类型（默认即时，保持向后兼容） */
private trigger_type: CardTriggerType = CardTriggerType.Instant;
/** 事件型触发的全局次数上限（Infinity 表示无上限） */
private trigger_limit: number = Infinity;
/** 事件型已触发次数 */
private trigger_count: number = 0;
// ======================== 运行时状态 ========================
/** 已触发次数 */
@@ -92,9 +105,13 @@ export class SkillBoxComp extends CCComp {
// ======================== 生命周期 ========================
/** 注册战斗开始、任务结束、新一波等事件 */
/**
* 注册全局事件：
* - MissionEnd：所有类型都需要监听，任务结束时强制销毁
* - NewWave：处理 keep_waves 跨波次逻辑（所有类型统一）
* - 其它触发事件由 registerTrigger 按 trigger_type 动态注册
*/
onLoad() {
oops.message.on(GameEvent.FightStart, this.onFightStart, this);
oops.message.on(GameEvent.MissionEnd, this.onMissionEnd, this);
this.node.on(GameEvent.NewWave, this.onNewWave, this);
oops.message.on(GameEvent.NewWave, this.onNewWaveGlobal, this);
@@ -104,8 +121,15 @@ export class SkillBoxComp extends CCComp {
/** 销毁时移除所有事件监听并通知槽位管理器回收 */
onDestroy() {
super.onDestroy();
oops.message.off(GameEvent.FightStart, this.onFightStart, this);
// 统一 off 所有可能订阅的事件（即使未订阅也无副作用）
// 注意：FightStart 可能由两种回调订阅（Interval→onFightStart / FightStart触发型→onEventTrigger），都需要 off
oops.message.off(GameEvent.MissionEnd, this.onMissionEnd, this);
oops.message.off(GameEvent.FightStart, this.onFightStart, this);
oops.message.off(GameEvent.FightStart, this.onEventTrigger, this);
oops.message.off(GameEvent.FightEnd, this.onEventTrigger, this);
oops.message.off(GameEvent.HeroDead, this.onEventTrigger, this);
oops.message.off(GameEvent.MasterCalled, this.onEventTrigger, this);
oops.message.off(GameEvent.ReviveSuccess, this.onEventTrigger, this);
if (this.node && this.node.isValid) {
this.node.off(GameEvent.NewWave, this.onNewWave, this);
this.node.off(NodeEventType.TOUCH_END, this.onNodeClicked, this);
@@ -128,9 +152,9 @@ export class SkillBoxComp extends CCComp {
/**
* 初始化技能卡效果：
* 1. 从 CardPoolList 查询技能卡的触发配置。
* 1. 从 CardPoolList 查询技能卡的触发配置（含 trigger_type）。
* 2. 更新 UI 显示（图标 + 次数）。
* 3. 即时技能立即触发一次；若次数已满则延迟销毁。
* 3. 按 trigger_type 注册对应事件监听并执行首次触发。
*
* @param uuid 卡牌 UUID
* @param card_lv 技能卡等级
@@ -148,37 +172,135 @@ export class SkillBoxComp extends CCComp {
this.keep_waves = config.keep_waves ?? 0;
this.overrides = config.overrides;
this.field = config.field || [];
// 读取触发类型与上限（兜底默认值，避免 undefined）
this.trigger_type = config.trigger_type ?? CardTriggerType.Instant;
this.trigger_limit = config.trigger_limit ?? Infinity;
} else {
this.s_uuid = uuid;
}
this.current_trigger_times = 0;
this.trigger_count = 0;
this.timer = 0;
this.initialized = true;
this.updateUI();
if (this.is_instant) {
// 即时技能：立即触发
// 按 trigger_type 注册事件监听 + 执行首次触发
this.registerTrigger();
}
/**
* 按 trigger_type 注册对应事件监听：
* - Instant: init 时立即触发一次（保持旧行为）
* - Interval: 监听 FightStart，进入战斗后由 update 帧驱动计时
* - Field: 不主动施法（实际生效由 FieldSkillSet 处理）
* - FightStart: 监听 FightStart 事件
* - FightEnd: 监听 FightEnd 事件
* - HeroDead: 监听 HeroDead 事件（已在派发处做阵营过滤）
* - HeroCall: 监听 MasterCalled（主角/技能召唤）+ ReviveSuccess（复活）
*
* 注意：MasterCalled 各派发点 payload 不一致，onEventTrigger 仅作触发信号使用。
*/
private registerTrigger(): void {
switch (this.trigger_type) {
case CardTriggerType.Instant:
// 即时技能：立即触发一次
this.onEventTrigger();
break;
case CardTriggerType.Interval:
// 定时循环：监听 FightStart 进入战斗后启动计时
oops.message.on(GameEvent.FightStart, this.onFightStart, this);
break;
case CardTriggerType.Field:
// 驻场光环：不主动施法，由 FieldSkillSet 处理
break;
case CardTriggerType.FightStart:
oops.message.on(GameEvent.FightStart, this.onEventTrigger, this);
break;
case CardTriggerType.FightEnd:
oops.message.on(GameEvent.FightEnd, this.onEventTrigger, this);
break;
case CardTriggerType.HeroDead:
oops.message.on(GameEvent.HeroDead, this.onEventTrigger, this);
break;
case CardTriggerType.HeroCall:
// 同时监听召唤和复活两类英雄上场事件
oops.message.on(GameEvent.MasterCalled, this.onEventTrigger, this);
oops.message.on(GameEvent.ReviveSuccess, this.onEventTrigger, this);
break;
default:
mLogger.warn(true, 'SkillBoxComp', `[registerTrigger] unknown trigger_type: ${this.trigger_type}, fallback to Instant`);
this.onEventTrigger();
break;
}
}
/**
* 事件型触发的统一入口：
* - Instant 类型：按 trigger_times 上限判定，复用 current_trigger_times 跟踪
* （保持与原 is_instant 行为一致，且 NewWave 中也用 current_trigger_times）
* - 事件型（FightStart/FightEnd/HeroDead/HeroCall）：按 trigger_limit 上限判定，使用 trigger_count 跟踪
*
* 注意：本方法不读取事件 payload，仅作触发信号使用（避免 MasterCalled 不同 payload 字段引发的兼容问题）。
*/
private onEventTrigger(): void {
if (!this.initialized) return;
if (this.trigger_type === CardTriggerType.Instant) {
// 即时触发：上限由 trigger_times 控制（保持旧行为）
if (this.current_trigger_times >= this.trigger_times) {
this.destroySelf();
return;
}
this.triggerSkill();
this.current_trigger_times++;
this.updateUI();
// 单次触发 + 不跨波次维持 → 延迟销毁（保留短暂视觉反馈）
if (this.keep_waves === 0 && this.current_trigger_times >= this.trigger_times) {
// 次数已满且不跨波次维持 → 延迟 1 秒后销毁（保留短暂视觉反馈）
this.scheduleOnce(() => {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
}, 1.0);
this.scheduleOnce(() => this.destroySelf(), 1.0);
}
return;
}
// 事件型：上限由 trigger_limit 控制（全局累计，跨波次不重置）
if (this.trigger_count >= this.trigger_limit) {
this.destroySelf();
return;
}
this.triggerSkill();
this.trigger_count++;
this.updateUI();
}
/**
* 统一的节点销毁封装：
* 优先通过 ECS 实体销毁；否则直接销毁节点。
*/
private destroySelf(): void {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
}
/**
* 更新 UI：
* - 图标：从 uicons 图集获取。
* - 剩余次数：持续技能显示剩余数字，即时技能不显示。
* - 图标：从 uicons 图集获取
* - 剩余次数标签：
* * Interval / 事件型：显示剩余次数（按各自上限计算）
* * Instant / Field：不显示
* - CD 遮罩：仅 Interval 类型展示冷却进度
*/
updateUI() {
// 加载技能图标
@@ -193,13 +315,29 @@ export class SkillBoxComp extends CCComp {
}
}
// 更新剩余次数标签
// 是否需要展示剩余次数
const showRemainCount =
this.trigger_type === CardTriggerType.Interval ||
this.trigger_type === CardTriggerType.FightStart ||
this.trigger_type === CardTriggerType.FightEnd ||
this.trigger_type === CardTriggerType.HeroDead ||
this.trigger_type === CardTriggerType.HeroCall;
if (this.info_label) {
if (!this.is_instant) {
if (this.trigger_interval <= 0 && this.field && this.field.length > 0) {
this.info_label.string = ""; // 纯驻场技能不显示剩余次数
if (showRemainCount) {
// 事件型按 trigger_limit；Interval 按 t_times
const isEvent =
this.trigger_type === CardTriggerType.FightStart ||
this.trigger_type === CardTriggerType.FightEnd ||
this.trigger_type === CardTriggerType.HeroDead ||
this.trigger_type === CardTriggerType.HeroCall;
const used = isEvent ? this.trigger_count : this.current_trigger_times;
const total = isEvent ? this.trigger_limit : this.trigger_times;
if (isEvent && !isFinite(total)) {
// 无上限：显示已触发次数
this.info_label.string = `${used}`;
} else {
const remain = Math.max(0, this.trigger_times - this.current_trigger_times);
const remain = Math.max(0, Math.floor(total) - used);
this.info_label.string = `${remain}`;
}
} else {
@@ -207,14 +345,14 @@ export class SkillBoxComp extends CCComp {
}
}
// 初始化或重置 CD 遮罩表现
// 初始化或重置 CD 遮罩表现（仅 Interval 类型有冷却进度）
if (this.cd_mask && this.cd_mask.isValid) {
let sprite = this.cd_mask.getComponent(Sprite);
if (sprite) {
if (this.is_instant || this.trigger_interval <= 0) {
sprite.fillRange = 0; // 无需冷却（包括驻场光环卡），直接归 0
} else {
if (this.trigger_type === CardTriggerType.Interval && this.trigger_interval > 0) {
sprite.fillRange = Math.max(0, 1 - (this.timer / this.trigger_interval));
} else {
sprite.fillRange = 0; // 非冷却类型直接归 0
}
}
}
@@ -222,14 +360,17 @@ export class SkillBoxComp extends CCComp {
// ======================== 战斗状态事件 ========================
/** 战斗开始：标记进入战斗状态，持续技能开始计时 */
/**
* 战斗开始回调：
* - 仅 Interval 类型在 registerTrigger 中订阅此事件
* - 标记进入战斗状态，启动计时器（实际触发由 update 帧驱动）
*
* 注意：FightStart 触发型（CardTriggerType.FightStart）的事件回调是 onEventTrigger，不是本方法。
*/
private onFightStart() {
if (!this.initialized) return;
this.in_combat = true;
if (!this.is_instant) {
this.timer = 0; // 重置计时器
}
this.timer = 0; // 重置计时器
}
/** 节点级新一波事件处理 */
@@ -245,76 +386,79 @@ export class SkillBoxComp extends CCComp {
/**
* 新一波：退出战斗状态。
* 处理维持波次逻辑：递减剩余波次，或者重置触发次数。
*
* 各类型在新一波的行为：
* - Instant/Interval/FightStart/FightEnd：按 keep_waves 决定维持/销毁，并在新一波开始时重置本地计数
* - Field：被动生效，跟随 keep_waves 决定存活
* - HeroDead/HeroCall：跨波次触发的事件型，trigger_count（全局）不重置，仅 keep_waves 控制存活
*/
private handleNewWave() {
if (!this.initialized) return;
this.in_combat = false;
// 事件型触发（HeroDead / HeroCall）：trigger_count 全局累计，不随波次重置
const isGlobalEventType =
this.trigger_type === CardTriggerType.HeroDead ||
this.trigger_type === CardTriggerType.HeroCall;
if (this.keep_waves !== 0) {
if (this.keep_waves > 0) {
this.keep_waves--;
if (this.keep_waves <= 0) {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
this.destroySelf();
return;
}
}
// 能够跨波次维持，重置触发次数和计时器，以便新一波继续触发
this.current_trigger_times = 0;
// 跨波次维持：重置本地计数与计时器（事件型 trigger_count 不重置）
if (!isGlobalEventType) {
this.current_trigger_times = 0;
this.trigger_count = 0;
}
this.timer = 0;
// 即时技能在新一波开始时立即触发一次
if (this.is_instant) {
// 即时/事件型触发一次（保持旧行为：Instant 在新一波开始立即触发一次）
if (this.trigger_type === CardTriggerType.Instant) {
this.triggerSkill();
this.current_trigger_times++;
}
this.updateUI();
} else {
// 默认逻辑：不跨波次维持
if (!this.is_instant) {
if (this.current_trigger_times >= this.trigger_times) {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
}
// 不跨波次维持：达到上限即销毁
// - Interval / Instant：按 t_times 判定
// - 事件型：按 trigger_limit 判定
const reachedLimit = isGlobalEventType
? this.trigger_count >= this.trigger_limit
: this.current_trigger_times >= this.trigger_times;
if (reachedLimit) {
this.destroySelf();
}
}
}
/** 任务结束：强制销毁 */
private onMissionEnd() {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
this.destroySelf();
}
// ======================== 帧更新 ========================
/**
* 每帧更新（仅对持续技能生效）：
* - 累加计时器，达到 trigger_interval 时触发一次技能。
* - 触发后重置计时器并更新 UI。
* - 总次数用完后延迟销毁。
* 每帧更新：
* - 仅 Interval 类型走帧驱动计时逻辑（其它类型提前 return）
* - 累加计时器，达到 trigger_interval 时触发一次技能
* - 触发后重置计时器并更新 UI
* - 总次数用完后延迟销毁
*/
update(dt: number) {
if (!this.initialized || !this.in_combat || this.is_instant) return;
// 收窄：仅 Interval 类型走帧驱动
if (this.trigger_type !== CardTriggerType.Interval) return;
if (!this.initialized || !this.in_combat) return;
if (!smc.mission.play || smc.mission.pause) return;
// 如果是纯驻场光环技能且无触发间隔，则不执行定期触发逻辑
if (this.trigger_interval <= 0 && this.field && this.field.length > 0) {
return;
}
if (this.current_trigger_times < this.trigger_times) {
this.timer += dt;
// 更新 CD 遮罩 (fillRange 从 1 降到 0)
if (this.cd_mask && this.cd_mask.isValid && this.trigger_interval > 0) {
let sprite = this.cd_mask.getComponent(Sprite);
@@ -331,13 +475,7 @@ export class SkillBoxComp extends CCComp {
// 次数用完且不跨波次维持 → 延迟销毁
if (this.keep_waves === 0 && this.current_trigger_times >= this.trigger_times) {
this.scheduleOnce(() => {
if (this.ent) {
(this.ent as ecs.Entity).destroy();
} else if (this.node && this.node.isValid) {
this.node.destroy();
}
}, 0.5);
this.scheduleOnce(() => this.destroySelf(), 0.5);
}
}
}