heros/assets/script/game/hero/BuffSystem_Extension.md

Buff 系统扩展指南

📌 概述

本指南说明如何在项目中添加新的 buff 和 debuff 类型。系统设计支持无限扩展，无需修改核心代码。

---

🎯 添加新的 Buff 类型

步骤 1: 确定属性影响

首先明确新 buff 要影响哪个属性：

// 示例：添加 "力量提升" buff
- 名称: PowerUp
- 属性: Attrs.AP (攻击力)
- 类型: 数值型 (BType.VALUE) 或百分比型 (BType.RATIO)
- 持续时间: 0(持久) 或 >0(临时)

步骤 2: 在技能配置中使用

在 assets/script/game/common/config/SkillSet.ts 中的技能配置里添加：

6001: {
    uuid: 6001,
    name: "攻击技能",
    // ... 其他配置 ...
    buffs: [
        {
            buff: Attrs.AP,        // 影响属性
            BType: BType.VALUE,    // 数值型
            buV: 20,               // +20 攻击力
            buC: 0,                // 永久
            buR: 100               // 100% 触发
        },
        {
            buff: Attrs.CRITICAL,  // 暴击率
            BType: BType.VALUE,    // 数值型
            buV: 25,               // +25% 暴击率
            buC: 3,                // 3 秒临时
            buR: 100
        }
    ],
    debuffs: [],
    info: "攻击技能，增加攻击力和暴击率"
}

步骤 3: 完成

✅ 系统会自动处理剩余工作：

• 自动分类存储到合适的缓存
• 自动计算属性
• 自动过期临时效果

---

⚡ 添加新的 Debuff 类型

两种 Debuff

1. 属性型 Debuff（直接修改属性）

• 例：SLOW（减速）、BURN（易伤）、DEAP（减攻击）
• 需要对应 Attrs 属性
• 会直接修改属性值

2. 状态型 Debuff（只缓存不修改属性）

• 例：STUN（眩晕）、FREEZE（冰冻）、POISON（中毒）
• 不需要对应 Attrs 属性
• 只缓存状态，用于战斗系统检查状态
• 查询使用：检查 debuff 缓存数组中是否存在该 debuff

---

添加属性型 Debuff

编辑 assets/script/game/common/config/SkillSet.ts：

步骤 1: 在 DBuff enum 中添加新类型

export enum DBuff {
    STUN = 1,           // 现有
    SLOW = 2,           // 现有
    // ... 现有 debuff ...
    NEW_DEBUFF = 15,    // 新增属性型 debuff
}

步骤 2: 在 debuffAttrMap 中添加映射

编辑 getAttrFieldFromDebuff 函数：

export const getAttrFieldFromDebuff = (debuffType: DBuff): number => {
    // ... stateDebuffSet ...
    
    const debuffAttrMap: Record<DBuff, number> = {
        // ... 现有映射 ...
        [DBuff.NEW_DEBUFF]: Attrs.DEF,  // 新增映射到防御
    };
    
    // ... 其他代码 ...
}

步骤 3: 在技能中使用

debuffs: [
    {
        debuff: DBuff.NEW_DEBUFF,
        BType: BType.VALUE,
        dev: 10,
        deC: 6,
        deR: 80
    }
]

---

添加状态型 Debuff

编辑 assets/script/game/common/config/SkillSet.ts：

步骤 1: 在 DBuff enum 中添加新类型

export enum DBuff {
    STUN = 1,
    SLOW = 2,
    // ... 现有 debuff ...
    FREEZE = 20,        // 新增状态型 debuff
}

步骤 2: 在 stateDebuffSet 中添加（不需要映射）

编辑 getAttrFieldFromDebuff 函数：

export const getAttrFieldFromDebuff = (debuffType: DBuff): number => {
    // 状态类 debuff（只需缓存，不影响属性）
    const stateDebuffSet = new Set<DBuff>([
        DBuff.FREEZE,     // 新增状态型 debuff
    ]);
    
    // 检查是否是状态类 debuff
    if (stateDebuffSet.has(debuffType)) {
        return -1;  // 表示只缓存，不影响属性
    }
    
    // ... 其他代码 ...
}

步骤 3: 在技能中使用

debuffs: [
    {
        debuff: DBuff.FREEZE,
        BType: BType.VALUE,     // 通常为数值型
        dev: 0,                 // 状态型可以为 0
        deC: 4,                 // 持续 4 秒
        deR: 100
    }
]

步骤 4: 在战斗系统中检查状态

状态型 debuff 被缓存在 stateDebuffPerm 和 stateDebuffTemp Set 中，支持最简洁的访问：

// 最推荐：一行代码检查状态
if (heroView.hasState(DBuff.STUN)) {
    // 眩晕状态下无法行动
}

// 直接 Set 访问（等价）
if (heroView.stateDebuffTemp.has(DBuff.STUN)) {
    // 眩晕状态下无法行动
}

// 同时检查持久和临时状态
if (heroView.stateDebuffPerm.has(DBuff.FREEZE) || 
    heroView.stateDebuffTemp.has(DBuff.FREEZE)) {
    // 冰冻状态，移动速度降低
    moveSpeed *= 0.5;
}

---

📝 扩展检查清单

添加属性型 Debuff 时

• 在 DBuff enum 中添加新类型
• 在 debuffAttrMap 中添加映射到对应的 Attrs
• 确保映射的 Attrs 有效
• 在技能配置中使用
• 测试属性是否正确修改

添加状态型 Debuff 时

• 在 DBuff enum 中添加新类型
• 在 stateDebuffSet 中添加
• ⚠️ 不要 在 debuffAttrMap 中添加映射
• 在技能配置中使用
• 在战斗系统中添加状态检查逻辑
• 测试状态缓存是否正确

---

🎮 完整示例

示例 1: 属性型 Debuff - 减攻击

// DBuff enum
export enum DBuff {
    WEAKEN = 15,  // 新增：减弱攻击
}

// 映射
const debuffAttrMap = {
    [DBuff.WEAKEN]: Attrs.AP,  // 直接减攻击力
};

// 技能使用
6010: {
    debuffs: [
        {
            debuff: DBuff.WEAKEN,
            BType: BType.RATIO,
            dev: 30,     // 减少 30% 攻击
            deC: 5,      // 持续 5 秒
            deR: 100
        }
    ]
}

// 自动效果：目标攻击力降低 30%

示例 2: 状态型 Debuff - 中毒

// DBuff enum
export enum DBuff {
    POISON = 16,  // 新增：中毒
}

// 状态集合
const stateDebuffSet = new Set<DBuff>([
    DBuff.POISON,  // 只缓存，不影响属性
]);

// 技能使用
6011: {
    debuffs: [
        {
            debuff: DBuff.POISON,
            BType: BType.VALUE,
            dev: 0,           // 状态型可以为 0
            deC: 8,           // 持续 8 秒
            deR: 70           // 70% 触发
        }
    ]
}

// 战斗系统检查
if (checkState(targetHero, DBuff.POISON)) {
    // 每秒损失血量
    targetHero.hp -= 5;
}

---

🔄 状态型 Debuff 的应用场景

• 控制类：眩晕、冰冻、缠绕
• 异常类：中毒、流血、灼烧
• 减益类：沉默、禁疗、虚弱
• 特殊：任何需要在战斗系统检查的状态

状态型 debuff 不直接修改属性，而是作为标记，由战斗系统根据状态采取不同的行动。

---

📞 获取帮助

遇到问题检查：

1. 是否正确区分了属性型和状态型 debuff？
2. 属性型 debuff 是否添加了映射？
3. 状态型 debuff 是否添加到了 stateDebuffSet？
4. 状态检查逻辑是否添加到战斗系统？

---

系统设计充分考虑了扩展性，添加新 buff/debuff 无需修改核心逻辑！ 🎉