heros/assets/script/game/common/config/TalSet_README.md

🎮 英雄天赋系统 (Talent System)

📌 项目概述

这是一个为游戏英雄系统设计的功能完整、高度可扩展的天赋配置系统。系统支持四种不同类型的天赋效果定义，每种类型都有清晰的触发条件和效果机制，可以轻松创建复杂而有趣的英雄特性。

---

📦 项目结构

assets/script/game/common/config/
├── TalSet.ts                    # ⭐ 核心配置文件 (435行)
├── TalSet_Example.ts            # 💡 集成示例 (424行)
├── TalSet_USAGE.md              # 📖 详细文档 (400+行)
├── TalSet_QuickRef.md           # ⚡ 快速参考 (350+行)
└── TalSet_README.md             # 📋 本文件 - 总体说明

---

✨ 核心功能

1️⃣ 等级类天赋 (LEVEL_ATTR)

当英雄升到指定等级时触发效果

• 示例: 每升5级，攻击力增加10%
• ID范围: 7001-7099
• 特点: 里程碑式的属性增长

2️⃣ 行为计数类天赋 (ACTION_COUNT_ATTR)

当特定行为累计达到次数时触发

• 示例: 每攻击10次，闪避率增加1%
• ID范围: 7101-7199
• 支持行为: 攻击、技能释放、受到伤害
• 特点: 可选择按等级重置或持续累积

3️⃣ 受伤计数类天赋 (DAMAGE_COUNT_ATTR)

当英雄累计受伤达到次数时触发

• 示例: 每受伤10次，最大生命值增加100
• ID范围: 7201-7299
• 特点: 坦克英雄的成长机制

4️⃣ 技能触发类天赋 (ACTION_TRIGGER_SKILL)

满足条件时自动释放指定技能

• 示例: 每攻击15次，自动释放反击技能
• ID范围: 7301-7399
• 特点: 创建链式反应和特殊战斗机制

---

🚀 快速开始 (5分钟)

第一步：初始化英雄天赋

import { initHeroTalents } from "./TalSet_Example";

// 为英雄 ID=5001 (刘邦) 初始化天赋
initHeroTalents(5001, [7001, 7202]);
// 7001: 剑意提升 (等级类)
// 7202: 防御强化 (受伤类)

第二步：监听游戏事件

import { 
    onHeroLevelUp, 
    onHeroAttack, 
    onHeroDamaged,
    onHeroSkillCast
} from "./TalSet_Example";

// 在英雄升级系统中调用
onHeroLevelUp(5001, 10);  // 英雄升到10级

// 在战斗系统中调用
onHeroAttack(5001, 50);        // 英雄发动攻击
onHeroSkillCast(5001, 6001);   // 英雄释放技能
onHeroDamaged(5001, 30);       // 英雄受到伤害

第三步：查询天赋信息

import { getTalConf } from "./TalSet";

// 获取单个天赋配置
const talConfig = getTalConf(7001);
console.log(talConfig.name);  // "剑意提升"

// 获取英雄的天赋状态
const talentInfo = globalTalentManager.getHeroTalentInfo(5001);
talentInfo?.talents.forEach((instance, talId) => {
    console.log(`天赋${talId}: 堆叠${instance.stackCount}层`);
});

---

📚 文档导航

文档	内容	何时阅读
TalSet.ts	核心代码，类型定义和配置表	需要了解数据结构
TalSet_USAGE.md	详细说明，四种天赋类型详解	深入学习天赋系统
TalSet_QuickRef.md	速查表，代码片段和模板	快速查阅和参考
TalSet_Example.ts	完整实现，天赋触发器和查询工具	了解系统实现细节
TalSet_README.md	本文件，项目总体说明	第一次使用

推荐阅读顺序

1. 📋 本文件 (10分钟) - 了解项目整体
2. ⚡ TalSet_QuickRef.md (10分钟) - 快速上手
3. 📖 TalSet_USAGE.md (20分钟) - 深入理解
4. 💡 TalSet_Example.ts (查需) - 参考实现

---

🎯 预置天赋示例

等级类天赋

ID	名称	效果	触发
7001	剑意提升	攻击力 +10%	每5级
7002	法力修炼	魔力 +15	每3级

行为计数类天赋

ID	名称	效果	触发
7101	强化闪避	闪避率 +1%	每10次攻击
7102	暴击强化	暴击率 +2%	每15次攻击
7103	连击精通	攻击力 +5%	每8次技能

受伤计数类天赋

ID	名称	效果	触发
7201	坚甲护体	生命 +100	每10次受伤
7202	防御强化	防御 +3%	每12次受伤
7203	魔抗修炼	魔防 +5	每15次受伤

技能触发类天赋

ID	名称	效果	触发
7301	连击反击	释放技能6010	每15次攻击
7302	受伤反制	释放技能6011	每8次受伤
7303	技能链接	释放技能6012	每5次技能

---

🔧 如何添加新天赋

方案：添加 "越战越强" 战士天赋

步骤 1：确定天赋类型

• 受伤时变强 → 使用 DAMAGE_COUNT_ATTR

步骤 2：分配天赋ID

• 下一个受伤类 ID → 7204

步骤 3：在 TalSet.ts 中添加配置

// 在 talConf 对象中添加：
7204: {
    talId: 7204,
    name: "越战越强",
    desc: "每受伤8次，攻击力增加4%",
    talType: TalType.DAMAGE_COUNT_ATTR,
    trigger: {
        type: "damageCount",
        count: 8,
        resetPerLevel: false,
    } as IDamageCountTrigger,
    effect: {
        type: "attrModify",
        attr: TalAttrType.AP,
        value: 4,
        percent: true,
    } as IAttrModifyEffect,
    stackable: true,
    maxStack: 18,
},

步骤 4：使用新天赋

initHeroTalents(5001, [7204]);  // 为英雄添加新天赋

---

🎮 与英雄系统集成

在 heroSet.ts 中添加天赋字段

// 修改 heroInfo 接口
export interface heroInfo {
    uuid: number;
    name: string;
    // ... 其他属性 ...
    talents?: number[];  // 新增：天赋ID数组
}

// 为具体英雄添加天赋
5001: {
    uuid: 5001,
    name: "刘邦",
    // ... 其他属性 ...
    talents: [7001, 7202],  // 刘邦的天赋
}

在战斗系统中触发天赋

// 在战斗逻辑中适当位置调用：

// 1. 英雄升级时
hero.onLevelUp((newLevel) => {
    onHeroLevelUp(hero.id, newLevel);
});

// 2. 英雄攻击时
hero.onAttack((damage) => {
    onHeroAttack(hero.id, damage);
});

// 3. 英雄受伤时
hero.onDamaged((damage) => {
    onHeroDamaged(hero.id, damage);
});

// 4. 英雄释放技能时
hero.onSkillCast((skillId) => {
    onHeroSkillCast(hero.id, skillId);
});

---

💡 设计原则

1. 触发条件与效果分离

• 触发条件负责"何时激发"
• 效果负责"产生什么影响"
• 两者独立定义，灵活组合

2. 高度扩展性

• 新增属性类型？直接加入 TalAttrType 枚举
• 新增行为类型？直接加入 TalActionType 枚举
• 新增触发条件？创建新的 ITriggerCondition 接口

3. 类型安全

• 使用 TypeScript 接口确保配置正确
• 使用类型强制进行编译时检查
• 避免运行时类型错误

4. 清晰的ID命名规范

XYZZ
├─ X: 类别 (7 = 天赋)
├─ Y: 子类型 (0=等级, 1=行为, 2=受伤, 3=技能)
└─ ZZ: 序列号 (01-99)

示例：
7001 → 7(天赋) 0(等级) 01(第1个)
7102 → 7(天赋) 1(行为) 02(第2个)

---

📊 关键数据结构

天赋配置接口

interface ItalConf {
    talId: number;           // 天赋ID
    name: string;            // 天赋名称
    desc: string;            // 天赋描述
    talType: TalType;        // 天赋类型
    trigger: ITriggerCondition;  // 触发条件
    effect: ITalEffect;      // 效果
    stackable?: boolean;     // 是否可堆叠
    maxStack?: number;       // 最大堆叠次数
}

天赋实例数据

interface HeroTalentInstance {
    talId: number;           // 天赋ID
    stackCount: number;      // 当前堆叠层数
    actionCounter: number;   // 行为计数
    damageCounter: number;   // 受伤计数
    lastTriggerLevel: number;// 最后触发等级
    isActive: boolean;       // 是否激活
}

---

⚡ 性能建议

1. 初始化一次，复用多次

// ✅ 推荐
const manager = globalTalentManager;
for (let i = 0; i < 1000; i++) {
    manager.onHeroAttack(heroId, 50);
}

// ❌ 不推荐 (频繁查询)
for (let i = 0; i < 1000; i++) {
    getTalConf(7001);
}

2. 缓存配置对象

// ✅ 推荐
const configs = getTalConfByType(TalType.LEVEL_ATTR);
configs.forEach(config => { /* 使用 */ });

// ❌ 不推荐 (重复查询)
for (let i = 0; i < 100; i++) {
    const config = getTalConf(7001);
}

3. 合理设置堆叠上限

// 防止无限堆叠导致性能问题
maxStack: 20,  // 而不是无限

---

🐛 调试与测试

打印所有天赋信息

import { TalentQueryHelper } from "./TalSet_Example";

TalentQueryHelper.printAllTalents();

获取特定条件的天赋

import { TalentQueryHelper, TalAttrType, TalActionType } from "./TalSet_Example";

// 获取所有影响生命值的天赋
const hpTals = TalentQueryHelper.getTalentsByAttribute(TalAttrType.HP);

// 获取所有与攻击相关的天赋
const attackTals = TalentQueryHelper.getTalentsByAction(TalActionType.ATTACK);

查看英雄天赋状态

import { globalTalentManager } from "./TalSet_Example";

const talentInfo = globalTalentManager.getHeroTalentInfo(5001);
console.table(Array.from(talentInfo?.talents.values() || []));

---

📋 完整集成示例

// main.ts 或 game.ts
import { 
    initHeroTalents,
    onHeroLevelUp,
    onHeroAttack,
    onHeroDamaged,
    TalentSystemExample
} from "./TalSet_Example";

class GameSystem {
    initGame() {
        // 1. 为英雄初始化天赋
        initHeroTalents(5001, [7001, 7202, 7101]);
        
        // 2. 在战斗系统中监听事件
        this.setupEventListeners();
    }
    
    setupEventListeners() {
        // 英雄升级时
        on('heroLevelUp', (heroId, newLevel) => {
            onHeroLevelUp(heroId, newLevel);
        });
        
        // 英雄发动攻击时
        on('heroAttack', (heroId, damage) => {
            onHeroAttack(heroId, damage);
        });
        
        // 英雄受伤时
        on('heroDamaged', (heroId, damage) => {
            onHeroDamaged(heroId, damage);
        });
    }
    
    // 用于调试
    debugTalents() {
        const example = new TalentSystemExample();
        example.initLiuBangTalents();
        example.simulateLevelUp();
        example.simulateCombat();
        example.queryTalentInfo();
    }
}

---

🎓 学习路径

初级 (理解基础)

1. 阅读本文件
2. 查看 TalSet_QuickRef.md
3. 运行预置示例

中级 (自定义开发)

1. 阅读 TalSet_USAGE.md
2. 参考 TalSet_Example.ts
3. 添加新的天赋配置

高级 (系统扩展)

1. 研究 TalSet.ts 源代码
2. 创建新的触发条件类型
3. 实现自定义效果逻辑

---

🤝 贡献指南

添加新的预置天赋

1. 确定天赋类型和ID
2. 在 TalSet.ts 中添加配置
3. 在本文档中更新示例表格
4. 在 TalSet_USAGE.md 中记录详情

报告问题

• 配置错误？检查接口是否实现
• 触发不工作？检查事件是否正确调用
• 性能问题？检查 maxStack 是否过大

---

📞 快速帮助

Q: 天赋何时触发？

A: 取决于配置的触发条件：

• 等级类：升到指定等级
• 行为类：行为累计达到指定次数
• 受伤类：受伤累计达到指定次数
• 技能类：满足前三种条件之一

Q: 如何禁用某个天赋？

A: 初始化时不添加该天赋ID即可

initHeroTalents(heroId, [7001, 7002]);  // 不包括 7101

Q: 天赋堆叠有上限吗？

A: 有，由 maxStack 属性控制

maxStack: 20,  // 最多堆叠20次
// 不设置则无限堆叠（不推荐）

Q: 百分比效果如何计算？

A: 在实现层面应用

// 如果 percent: true，value: 10
// 则增益 = 基础属性 × 110% (基础+10%)
// 多堆叠层 = 基础属性 × (1 + 0.1 * stackCount)

---

📄 许可证

这个天赋系统是项目的内部组件，遵循项目许可。

---

✅ 检查清单

在投入使用前，请确认：

• 已阅读本文档
• 了解四种天赋类型的区别
• 能够添加新天赋配置
• 已在游戏系统中集成事件监听
• 已进行性能测试
• 已验证天赋触发正常

---

📞 支持

遇到问题？

1. 查看 TalSet_QuickRef.md 的常见问题
2. 参考 TalSet_USAGE.md 的详细说明
3. 查看 TalSet_Example.ts 的实现代码
4. 检查浏览器控制台的调试输出

---

天赋系统已就绪！🚀 祝游戏开发愉快！

---

📊 系统统计

指标	数值
总代码行数	~1,200
预置天赋	12个
支持属性	9种
支持行为	3种
触发条件类型	3种
效果类型	2种
最大天赋ID	7399
扩展性评分	⭐⭐⭐⭐⭐