# 07 · 敌人系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：敌人实体模型、AI 行为规范、Boss 系统设计与掉落体系。

---

## 目录

1. [设计原则](#1-设计原则)
2. [敌人实体模型](#2-敌人实体模型)
3. [AI 行为规范](#3-ai-行为规范)
4. [寻路与感知](#4-寻路与感知)
5. [Boss 系统](#5-boss-系统)
6. [电报系统（攻击预警）](#6-电报系统攻击预警)
7. [敌人分级体系](#7-敌人分级体系)
8. [掉落系统](#8-掉落系统)

---

## 1. 设计原则

| 原则 | 说明 |
|------|------|
| **可读性优先** | 每个攻击都有明确的预警（电报），让玩家有机会反应 |
| **弹反友好** | 大多数攻击标记为可弹反，鼓励玩家使用核心机制 |
| **行为数据化** | AI 行为通过数据配置组合，不硬编码 |
| **职责分离** | 移动、攻击、感知各为独立模块，互不依赖 |

---

## 2. 敌人实体模型

### 2.1 实体构成

```
EnemyEntity（协调器）
├── EnemyStats         ← 属性（HP、防御、速度等）
├── AIController       ← 行为决策（BehaviorTree 或 FSM）
├── MovementAgent      ← 路径跟随与物理移动
├── CombatModule       ← 攻击执行、HitArea 管理
├── HurtBox            ← 受击响应
├── PerceptionModule   ← 感知（视野、听觉、自定义触发器）
├── LootModule         ← 死亡掉落处理
└── TelegraphSystem    ← 攻击电报（预警视觉效果）
```

### 2.2 敌人属性模型

```
DataModel EnemyStatsData {
    enemyId         : ID
    displayName     : String
    ──────────────────────────────────
    maxHP           : Integer
    defense         : Number              // 伤害减免（0.0~1.0）
    poiseLevel      : PoiseLevel          // 霸体等级
    ──────────────────────────────────
    moveSpeed       : Number              // 基础移动速度
    detectionRange  : Number              // 视野/感知范围
    attackRange     : Number              // 近战攻击范围
    ──────────────────────────────────
    lootTableId     : Ref<LootTableData>  // 掉落表
    geoReward       : {min: Integer, max: Integer}  // Geo 掉落范围
    killCreditType  : KillCreditType      // 击杀积分类型（普通/精英/Boss）
}
```

---

## 3. AI 行为规范

### 3.1 行为树节点类型

AI 行为通过**行为树（Behavior Tree）**组织，行为节点类型：

| 节点类型 | 符号 | 说明 |
|---------|------|------|
| 选择节点（Selector）| `?` | 依次尝试子节点，第一个成功即返回成功 |
| 序列节点（Sequence）| `→` | 依次执行子节点，所有成功才返回成功 |
| 条件节点（Condition）| `[C]` | 判断某个条件，返回成功/失败 |
| 动作节点（Action）| `[A]` | 执行一个具体行为 |
| 装饰节点（Decorator）| `{D}` | 修改子节点行为（如重复、反转、冷却）|

### 3.2 通用敌人行为树模板

```
Root（Selector）
├─ ? 死亡检测
│   └─ [C] HP <= 0  →  [A] 播放死亡动画 → [A] 触发掉落 → [A] 销毁
│
├─ ? 受击响应
│   └─ [C] 正在受击  →  [A] 受击动画（若霸体被打断）
│
├─ ? 攻击决策（Selector）
│   ├─ ? 近战攻击
│   │   └─ [C] 玩家在攻击范围内
│   │       → [C] 攻击冷却结束
│   │       → [A] 播放电报
│   │       → [A] 执行攻击
│   │
│   └─ ? 远程攻击
│       └─ [C] 玩家在视野内但超出近战范围
│           → [C] 远程攻击冷却结束
│           → [A] 播放电报
│           → [A] 发射弹射物
│
├─ ? 追击（Sequence）
│   ├─ [C] 已感知到玩家
│   └─ [A] 向玩家移动（路径跟随）
│
└─ ? 巡逻/待机（Sequence）
    └─ [A] 执行巡逻路径（或原地待机）
```

### 3.3 AI 感知状态

| 状态 | 条件 | 行为 |
|------|------|------|
| `Idle`（待机）| 未感知到玩家 | 巡逻或原地等待 |
| `Alert`（警戒）| 听到声音或余光检测 | 转向检查，不主动追击 |
| `Chase`（追击）| 视野内确认玩家 | 向玩家移动 |
| `Combat`（战斗）| 玩家在攻击范围内 | 执行攻击序列 |
| `Stunned`（硬直）| 受到重击/被弹反 | 暂停所有行为 |

---

## 4. 寻路与感知

### 4.1 寻路规范

| 规范项 | 说明 |
|--------|------|
| 寻路类型 | 2D 导航网格（NavMesh）或路径点系统 |
| 更新频率 | 目标位置变化超过阈值时重新规划路径（不每帧更新）|
| 跳跃/下落 | 可配置是否允许跳跃/从平台下落追击 |
| 障碍物 | 动态障碍物（其他敌人）不重新规划路径，简单规避 |

### 4.2 感知规范

```
DataModel PerceptionConfig {
    visionRange     : Number    // 视野半径
    visionAngle     : Number    // 视野角度（正前方±角度）
    hearingRange    : Number    // 听觉半径（玩家移动/攻击触发）
    alertDuration   : Duration  // Alert 状态持续时长
    lostTargetDelay : Duration  // 失去视野到放弃追击的延迟
}
```

---

## 5. Boss 系统

### 5.1 Boss 实体模型

Boss 继承普通敌人的所有能力，附加以下扩展：

```
DataModel BossData extends EnemyStatsData {
    bossName        : String
    arenaId         : ID                    // 专属战斗场景
    ──────────────────────────────────────
    phases          : List<BossPhaseData>   // 阶段列表（按顺序触发）
    introSequenceId : ID                    // 入场演出序列
    defeatSequenceId: ID                    // 失败演出序列
    ──────────────────────────────────────
    bgmPhase1       : AudioID
    bgmPhase2       : Optional<AudioID>     // 阶段变更时切换音乐
}

DataModel BossPhaseData {
    phaseIndex      : Integer
    hpThreshold     : Number                // 触发阶段变更的 HP 百分比（0~1.0）
    availableAttacks: List<Ref<AttackPatternData>>  // 该阶段可用攻击
    attackWeights   : Map<ID, Number>       // 各攻击的选取权重
    aggressionScale : Number                // 攻击频率倍率
}
```

### 5.2 Boss 攻击模式模型

```
DataModel AttackPatternData {
    patternId       : ID
    patternName     : String
    ──────────────────────────────
    telegraphType   : TelegraphType         // 电报类型
    telegraphDuration: Duration             // 电报持续时间
    ──────────────────────────────
    attackType      : BossAttackType        // 攻击类型
    executionParams : Map<String, Number>   // 执行参数
    cooldown        : Duration              // 攻击后冷却
    ──────────────────────────────
    isParryable     : Boolean               // 是否可被玩家弹反
    counterWindowId : Optional<ID>          // 弹反后的脆弱窗口
}
```

### 5.3 Boss 阶段转换流程

```
Boss HP 降至 PhaseData.hpThreshold 以下
  → AIController 暂停（短暂无敌帧 0.5s）
  → 播放相变动画/特效
  → 发出 OnBossPhaseChanged 事件（bossId, newPhase）
  → 更新可用攻击列表和攻击权重
  → 音频系统切换音乐（若配置了 bgmPhase2）
  → 恢复 AIController
```

---

## 6. 电报系统（攻击预警）

所有攻击**必须**有电报，给玩家反应时间：

| 电报类型 | 视觉表现 | 适用场景 |
|---------|---------|---------|
| `PoseHold` | 攻击前摇姿势定格 | 近战重击 |
| `GroundIndicator` | 地面出现警告范围标记 | 落地冲击、AoE |
| `TrajectoryLine` | 显示弹射物飞行路径 | 精准弹射物 |
| `BodyGlow` | 敌人身体特定颜色发光 | 不可弹反：红色；可弹反：黄色 |
| `SoundCue` | 特定音效（与视觉结合）| 所有攻击必备 |

### 电报颜色规范

| 颜色 | 含义 |
|------|------|
| 黄色/金色 | 可弹反攻击 |
| 红色/橙色 | 不可弹反攻击 |
| 紫色 | 特殊/Boss 专属机制 |
| 白色 | 环境危险（非敌人攻击）|

---

## 7. 敌人分级体系

| 等级 | 名称 | AI 复杂度 | 霸体 | 典型特征 |
|------|------|----------|------|---------|
| T1 | 杂兵 | 简单（2-3种行为）| Fragile | 单一攻击，跑向玩家 |
| T2 | 普通敌人 | 中等（3-5种行为）| Standard | 有攻击组合，有简单规避 |
| T3 | 精英怪 | 较高（5-7种行为）| Armored | 有阶段变化，有独特机制 |
| T4 | Boss | 高（多阶段完整AI）| Boss | 多阶段、多攻击、电报复杂 |

---

## 8. 掉落系统

### 8.1 掉落表模型

```
DataModel LootTableData {
    tableId         : ID
    entries         : List<LootEntry>
    guaranteedDrops : List<Ref<ItemData>>  // 必掉物品（如 Boss 必掉能力道具）
}

DataModel LootEntry {
    itemId          : Ref<ItemData>
    baseWeight      : Number               // 基础权重（相对概率）
    minCount        : Integer
    maxCount        : Integer
    difficultyScale : Number               // 难度缩放系数（Easy 减少，Hard 增加）
}
```

### 8.2 掉落概率计算

```
各 Entry 的实际权重 = baseWeight × 难度系数
总权重 = 所有 Entry 实际权重之和
某 Entry 概率 = 该 Entry 实际权重 / 总权重

保底机制:
  若稀有物品连续 20 次未掉落 → 下次强制掉落
  保底计数存入 SaveData，跨死亡保留
```

### 8.3 掉落触发流程

```
OnEnemyDied 事件触发
  → 掉落系统读取死亡敌人的 LootTableData
  → 计算本次掉落结果（权重随机 + 保底检查）
  → 在死亡位置生成掉落物实体
  → Geo 直接加入玩家账户（不生成实体，减少拾取摩擦）
  → 特殊道具生成拾取实体，玩家走近自动拾取
```