# 天赋系统快速参考

## 📋 文件导览

| 文件 | 用途 |
|------|------|
| `TalSet.ts` | 核心配置文件 - 定义所有天赋类型、接口和配置表 |
| `TalSet_USAGE.md` | 详细使用文档 - 包含各天赋类型的详解和最佳实践 |
| `TalSet_Example.ts` | 集成示例 - 完整的天赋系统实现代码 |
| `TalSet_QuickRef.md` | 快速参考（本文件） - 常用代码片段速查 |

---

## 🚀 快速开始

### 1. 初始化英雄天赋

```typescript
import { initHeroTalents } from "./TalSet_Example";

// 为英雄 ID=5001 初始化天赋 [7001, 7202]
initHeroTalents(5001, [7001, 7202]);
```

### 2. 监听英雄事件

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

// 英雄升级到新等级
onHeroLevelUp(5001, 10);

// 英雄发动攻击
onHeroAttack(5001, 50);

// 英雄受到伤害
onHeroDamaged(5001, 30);
```

### 3. 查询天赋信息

```typescript
import { getTalConf, getTalConfByType, TalType } from "./TalSet";

// 获取单个天赋配置
const talConfig = getTalConf(7001);

// 获取某类型的所有天赋
const levelTals = getTalConfByType(TalType.LEVEL_ATTR);
```

---

## 📊 天赋类型速查

### 等级类天赋 (LEVEL_ATTR)

**ID范围**: 7001-7099

| ID | 名称 | 描述 | 触发条件 |
|---|------|------|--------|
| 7001 | 剑意提升 | 攻击力 +10% | 每5级 |
| 7002 | 法力修炼 | 魔力 +15 | 每3级 |

**配置模板**:
```typescript
{
    talId: 7001,
    name: "天赋名",
    desc: "效果描述",
    talType: TalType.LEVEL_ATTR,
    trigger: { type: "level", level: 5 } as ILevelTrigger,
    effect: {
        type: "attrModify",
        attr: TalAttrType.AP,
        value: 10,
        percent: true,
    } as IAttrModifyEffect,
    stackable: true,
    maxStack: 20,
}
```

---

### 行为计数类天赋 (ACTION_COUNT_ATTR)

**ID范围**: 7101-7199

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

**配置模板**:
```typescript
{
    talId: 7101,
    name: "天赋名",
    desc: "效果描述",
    talType: TalType.ACTION_COUNT_ATTR,
    trigger: {
        type: "actionCount",
        actionType: TalActionType.ATTACK,
        count: 10,
        resetPerLevel: false,
    } as IActionCountTrigger,
    effect: {
        type: "attrModify",
        attr: TalAttrType.DODGE,
        value: 1,
        percent: true,
    } as IAttrModifyEffect,
    stackable: true,
    maxStack: 20,
}
```

**行为类型**:
- `TalActionType.ATTACK` - 攻击
- `TalActionType.SKILL` - 技能
- `TalActionType.DAMAGED` - 受伤

---

### 受伤计数类天赋 (DAMAGE_COUNT_ATTR)

**ID范围**: 7201-7299

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

**配置模板**:
```typescript
{
    talId: 7201,
    name: "天赋名",
    desc: "效果描述",
    talType: TalType.DAMAGE_COUNT_ATTR,
    trigger: {
        type: "damageCount",
        count: 10,
        resetPerLevel: false,
    } as IDamageCountTrigger,
    effect: {
        type: "attrModify",
        attr: TalAttrType.HP,
        value: 100,
        percent: false,
    } as IAttrModifyEffect,
    stackable: true,
    maxStack: 15,
}
```

---

### 技能触发类天赋 (ACTION_TRIGGER_SKILL)

**ID范围**: 7301-7399

| ID | 名称 | 描述 | 触发条件 |
|---|------|------|--------|
| 7301 | 连击反击 | 释放技能6010 | 每15次攻击 |
| 7302 | 受伤反制 | 释放技能6011 | 每8次受伤 |
| 7303 | 技能链接 | 释放技能6012 | 每5次技能 |

**配置模板**:
```typescript
{
    talId: 7301,
    name: "天赋名",
    desc: "效果描述",
    talType: TalType.ACTION_TRIGGER_SKILL,
    trigger: {
        type: "actionCount",
        actionType: TalActionType.ATTACK,
        count: 15,
        resetPerLevel: true,
    } as IActionCountTrigger,
    effect: {
        type: "skillTrigger",
        skillId: 6010,
    } as ISkillTriggerEffect,
    stackable: false,
}
```

---

## 🎯 属性类型速查

```typescript
TalAttrType.HP       // 最大生命值
TalAttrType.MP       // 最大魔力值
TalAttrType.AP       // 攻击力
TalAttrType.MAP      // 魔法攻击力
TalAttrType.DEF      // 防御力
TalAttrType.MDEF     // 魔法防御力
TalAttrType.SPEED    // 移动速度
TalAttrType.DODGE    // 闪避率
TalAttrType.CRIT     // 暴击率
```

---

## 💡 常见代码片段

### 获取所有某类型天赋

```typescript
import { getTalConfByType, TalType } from "./TalSet";

const levelTals = getTalConfByType(TalType.LEVEL_ATTR);
const actionTals = getTalConfByType(TalType.ACTION_COUNT_ATTR);
const damageTals = getTalConfByType(TalType.DAMAGE_COUNT_ATTR);
const skillTals = getTalConfByType(TalType.ACTION_TRIGGER_SKILL);
```

### 获取某属性相关的所有天赋

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

const hpTals = TalentQueryHelper.getTalentsByAttribute(TalAttrType.HP);
const apTals = TalentQueryHelper.getTalentsByAttribute(TalAttrType.AP);
```

### 获取某行为相关的所有天赋

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

const attackTals = TalentQueryHelper.getTalentsByAction(TalActionType.ATTACK);
const skillTals = TalentQueryHelper.getTalentsByAction(TalActionType.SKILL);
```

### 获取英雄的天赋状态

```typescript
import { globalTalentManager } from "./TalSet_Example";

const talentInfo = globalTalentManager.getHeroTalentInfo(5001);
if (talentInfo) {
    talentInfo.talents.forEach((instance, talId) => {
        console.log(`天赋${talId}: 堆叠${instance.stackCount}`);
    });
}
```

### 获取英雄的特定天赋实例

```typescript
import { globalTalentManager } from "./TalSet_Example";

const talInstance = globalTalentManager.getHeroTalentInstance(5001, 7001);
if (talInstance) {
    console.log(`堆叠层数: ${talInstance.stackCount}`);
    console.log(`行为计数: ${talInstance.actionCounter}`);
    console.log(`受伤计数: ${talInstance.damageCounter}`);
}
```

---

## 📝 添加新天赋步骤

### 步骤 1: 确定天赋类型

选择以下之一:
- `LEVEL_ATTR` - 等级触发
- `ACTION_COUNT_ATTR` - 行为计数触发
- `DAMAGE_COUNT_ATTR` - 受伤次数触发
- `ACTION_TRIGGER_SKILL` - 技能自动释放

### 步骤 2: 分配 ID

遵循命名规范:
- `70xx` - 等级类
- `71xx` - 行为计数类
- `72xx` - 受伤计数类
- `73xx` - 技能触发类

### 步骤 3: 配置天赋

在 `TalSet.ts` 的 `talConf` 中添加配置：

```typescript
// 示例：新增"生命吸取"天赋
7104: {
    talId: 7104,
    name: "生命吸取",
    desc: "每使用技能10次，最大生命值增加50点",
    talType: TalType.ACTION_COUNT_ATTR,
    trigger: {
        type: "actionCount",
        actionType: TalActionType.SKILL,
        count: 10,
        resetPerLevel: false,
    } as IActionCountTrigger,
    effect: {
        type: "attrModify",
        attr: TalAttrType.HP,
        value: 50,
        percent: false,
    } as IAttrModifyEffect,
    stackable: true,
    maxStack: 10,
},
```

---

## 🔍 调试技巧

### 打印所有天赋信息

```typescript
import { TalentQueryHelper } from "./TalSet_Example";

TalentQueryHelper.printAllTalents();
```

### 获取所有天赋ID

```typescript
import { getAllTalIds } from "./TalSet";

const allIds = getAllTalIds();
console.log(allIds); // [7001, 7002, 7101, ...]
```

### 获取所有可堆叠天赋

```typescript
import { TalentQueryHelper } from "./TalSet_Example";

const stackableTals = TalentQueryHelper.getStackableTalents();
```

### 获取所有技能触发类天赋

```typescript
import { TalentQueryHelper } from "./TalSet_Example";

const skillTriggerTals = TalentQueryHelper.getSkillTriggerTalents();
```

---

## ⚙️ 配置最佳实践

### 等级间隔建议

| 间隔 | 用途 | 示例 |
|------|------|------|
| 1 级 | 极高频触发（谨慎使用） | 特殊被动 |
| 2-3 级 | 高频触发 | 关键属性增长 |
| 4-5 级 | 常规触发 | 通用属性增长 |
| 6-10 级 | 低频触发 | 强力效果 |

### 堆叠层数建议

| 效果类型 | 建议上限 | 原因 |
|---------|---------|------|
| 固定值 (+100 HP) | 10-20 | 总收益 1000-2000 |
| 小百分比 (+1%) | 15-30 | 防止过度膨胀 |
| 大百分比 (+5%) | 5-10 | 数值平衡 |
| 技能触发 | 1 (false) | 防止无限触发 |

### 数值平衡公式

```
最终增益 = 基础值 × 最大堆叠 × 触发频率

例: 攻击力 +10% × 20 堆叠 = 200% 增加
    调整建议: 减少堆叠 maxStack 或增加触发频率
```

---

## 📦 导入速览

### 基础导入

```typescript
import { 
    TalType,           // 天赋类型枚举
    TalAttrType,       // 属性类型枚举
    TalActionType,     // 行为类型枚举
    getTalConf,        // 获取单个天赋
    getTalConfByType,  // 按类型获取天赋
    getAllTalIds,      // 获取所有天赋ID
} from "./TalSet";
```

### 高级导入

```typescript
import {
    TalentTriggerManager,      // 天赋触发管理器
    TalentQueryHelper,         // 天赋查询助手
    globalTalentManager,       // 全局管理器实例
    initHeroTalents,           // 初始化天赋
    onHeroLevelUp,             // 升级事件
    onHeroAttack,              // 攻击事件
    onHeroSkillCast,           // 技能事件
    onHeroDamaged,             // 受伤事件
} from "./TalSet_Example";
```

---

## 🐛 常见问题速答

| 问题 | 答案 |
|------|------|
| 如何禁用某个天赋？ | 在初始化时不添加该天赋ID |
| 天赋可以堆叠多少次？ | 看 `maxStack` 配置，不设则无限 |
| 如何重置计数器？ | 设置 `resetPerLevel: true` 按等级重置 |
| 如何添加新的属性类型？ | 在 `TalAttrType` 枚举中添加 |
| 如何添加新的行为类型？ | 在 `TalActionType` 枚举中添加 |
| 技能触发如何防止无限循环？ | 设置 `stackable: false` |

---

## 📚 相关文件链接

- [详细使用文档](./TalSet_USAGE.md) - 完整的天赋系统说明
- [集成示例代码](./TalSet_Example.ts) - 天赋系统实现示例
- [核心配置文件](./TalSet.ts) - 所有类型定义和配置表

---

**版本**: 1.0  
**最后更新**: 2025-10-27  
**维护者**: 开发团队