# 06 · 形态系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：三形态（天魂/地魂/命魂）的数据模型、切换契约、武器适配与技能体系。

---

## 目录

1. [形态设计目标](#1-形态设计目标)
2. [形态数据模型](#2-形态数据模型)
3. [形态切换契约](#3-形态切换契约)
4. [三形态规格表](#4-三形态规格表)
5. [技能体系](#5-技能体系)
6. [武器与形态联动](#6-武器与形态联动)
7. [形态配置参数](#7-形态配置参数)

---

## 1. 形态设计目标

| 目标 | 说明 |
|------|------|
| **风格差异化** | 三形态提供截然不同的战斗体验，不仅仅是皮肤替换 |
| **情境适应** | 不同区域/敌人类型鼓励不同形态，但不强制 |
| **无缝切换** | 切换不中断当前动作，下次输入时生效 |
| **可扩展** | 新增形态只需新增数据，不需要修改现有逻辑 |

---

## 2. 形态数据模型

```
DataModel FormData {
    formId          : ID                // 形态唯一标识（如 "SkyForm"）
    displayName     : String            // 显示名称（"天魂"）
    description     : String            // 一句话描述
    accentColor     : Color             // HUD/特效色调
    ──────────────────────────────────
    defaultWeapon   : Ref<WeaponData>   // 默认武器（连击动画+伤害来源+判定尺寸）
    soulSkill       : Ref<SkillData>    // 魂技能（消耗灵力）
    spiritSkill1    : Ref<SkillData>    // 魄技能 1（消耗魄元）
    spiritSkill2    : Ref<SkillData>    // 魄技能 2（消耗魄元）
    ──────────────────────────────────
    switchAnimation : Optional<AnimationID>  // 切换前摇动画（无则立即切换）
    unlockCondition : Optional<Ref<AbilityData>> // 解锁条件（null=初始可用）
}
```

```
DataModel WeaponData {
    weaponId        : ID
    formId          : ID                // 归属形态
    ──────────────────────────────────
    attack1Anim     : AnimationID       // 第一击动画
    attack2Anim     : AnimationID       // 第二击动画
    attack3Anim     : AnimationID       // 第三击动画
    airAttackAnim   : AnimationID
    upAttackAnim    : AnimationID
    downAttackAnim  : AnimationID
    ──────────────────────────────────
    hitBoxConfig    : List<HitBoxSpec>  // 各攻击段的判定区域规格
    damageMultipliers: Map<AttackType, Number>  // 各攻击段伤害倍率
}
```

---

## 3. 形态切换契约

### 3.1 切换输入映射

| 输入槽 | 默认形态 | 说明 |
|--------|---------|------|
| 槽位 0 | 天魂（SkyForm）| 键位 1 / 手柄方向键左 |
| 槽位 1 | 地魂（EarthForm）| 键位 2 / 手柄方向键下 |
| 槽位 2 | 命魂（DeathForm）| 键位 3 / 手柄方向键右 |

> **设计决策**：使用有序槽位而非形态枚举  
> **原因**：未来新增第四形态时，只需增加新输入槽和新 FormData，不改变现有逻辑

### 3.2 切换时机

```
玩家按下形态切换键
  → 目标形态 = 对应槽位的 FormData

  目标形态 == 当前形态？
  ├─ 是 → 忽略输入
  └─ 否 → 

    目标形态有切换前摇动画？
    ├─ 是 → 播放前摇，前摇完成后切换
    └─ 否 → **立即** 更新 CurrentForm（不中断当前动作）

    → 发出 OnFormChanged 事件（传入新 FormData）
    → WeaponSlot 接收事件，自动切换为新形态的默认武器
    → 下次攻击/技能输入时，使用新形态的动画和参数
```

### 3.3 切换的"无缝"原则

- 切换**本身无前摇**（默认配置下）
- 当前动作（如攻击、冲刺）**不被打断**
- 下一次攻击输入才体现新形态效果
- 技能（魂技能/魄技能）绑定于形态，切换后技能槽内容随之改变

---

## 4. 三形态规格表

### 4.1 天魂形态（SkyForm）

| 属性 | 规格 |
|------|------|
| 战斗风格 | 轻快连击，空中机动性强 |
| 攻击判定 | 较小范围，近身贴脸 |
| 连击特点 | 第三击向上抛起敌人 |
| 魂技能 | **天光斩**：前冲斩击，穿透多个敌人，灵力消耗 100 |
| 魄技能 1 | **天翔步**：瞬间向上跳跃（额外跳），魄元消耗 40 |
| 魄技能 2 | **灵鸟护体**：短暂无敌 + 反伤护盾，魄元消耗 70 |
| 定位 | 灵活流，擅长空中平台战斗 |

### 4.2 地魂形态（EarthForm）

| 属性 | 规格 |
|------|------|
| 战斗风格 | 重击范围大，霸体强 |
| 攻击判定 | 较大范围，有前置停顿 |
| 连击特点 | 第三击震地，范围伤害 |
| 魂技能 | **大地震怒**：跳起落下产生冲击波，灵力消耗 100 |
| 魄技能 1 | **岩甲护卫**：护盾层（吸收 X 点伤害），魄元消耗 50 |
| 魄技能 2 | **地裂踏**：踏地减速附近敌人，魄元消耗 60 |
| 定位 | 坦克流，擅长对峙 Boss 和密集敌人 |

### 4.3 命魂形态（DeathForm）

| 属性 | 规格 |
|------|------|
| 战斗风格 | 中等速度，弹反增益显著 |
| 攻击判定 | 适中范围，攻击后有追加效果 |
| 连击特点 | 每击命中后留下诅咒标记，第三击引爆全部标记 |
| 魂技能 | **命魂索链**：召唤锁链束缚最近敌人，灵力消耗 100 |
| 魄技能 1 | **命魂反噬**：下次弹反触发额外爆炸伤害，魄元消耗 45 |
| 魄技能 2 | **命域领域**：短暂降低附近敌人攻击力，魄元消耗 65 |
| 定位 | 弹反流，弹反策略强化，适合精通玩家 |

---

## 5. 技能体系

### 5.1 技能数据模型

```
DataModel SkillData {
    skillId         : ID
    skillName       : String
    description     : String
    resourceType    : ResourceType          // SoulPower 或 SpiritPower
    resourceCost    : Integer               // 消耗量
    ──────────────────────────────────
    castAnimation   : AnimationID           // 前摇动画
    castDuration    : Duration              // 前摇时长
    effectDelay     : Duration              // 前摇结束后效果开始的延迟
    ──────────────────────────────────
    effectType      : SkillEffectType
    effectParams    : Map<String, Number>   // 效果参数（因技能类型而异）
    ──────────────────────────────────
    canCastAirborne : Boolean               // 是否可在空中施放
    interruptible   : Boolean               // 前摇是否可被打断（冲刺/受伤仍可打断）
}
```

### 5.2 技能效果类型

| 类型 | 说明 | 典型参数 |
|------|------|---------|
| `Projectile` | 发射弹射物 | `speed`, `damage`, `piercing` |
| `Melee` | 近战范围攻击 | `radius`, `damage`, `knockback` |
| `Shield` | 护盾效果 | `absorbAmount`, `duration` |
| `Buff` | 正面增益 | `buffType`, `duration`, `magnitude` |
| `Debuff` | 负面施加 | `debuffType`, `duration`, `radius` |
| `Summon` | 召唤实体 | `entityId`, `duration`, `count` |
| `Mobility` | 移动型技能 | `distance`, `direction`, `invincible` |

### 5.3 资源消耗规则

| 资源类型 | 消耗时机 | 失败处理 |
|---------|---------|---------|
| 灵力 | 技能执行前检查，通过则立即扣除 | 不足时技能键无响应 |
| 魄元 | 技能执行前检查，通过则立即扣除 | 不足时技能键无响应 |

---

## 6. 武器与形态联动

### 6.1 武器切换流程

```
OnFormChanged 事件触发
  → WeaponSlot 更新为新形态的 defaultWeapon
  → CombatHandler 刷新以下内容:
       ├─ 当前连击段的动画片段
       ├─ HitArea 尺寸与偏移
       ├─ DamagePacket 中的伤害倍率来源
       └─ 重置连击计数器（ComboState → None）
```

### 6.2 护符武器覆盖

特定护符可覆盖某形态的默认武器（只改变该形态）：
- 护符持有 `WeaponData` 引用
- 装备时：对应槽位的 `FormData.defaultWeapon` 临时被护符武器替代
- 卸装时：恢复原 `FormData.defaultWeapon`

---

## 7. 形态配置参数

| 参数 | 说明 |
|------|------|
| 三形态 FormData | 见第 4 节规格表 |
| 各形态武器 HitBox 尺寸 | 在各 WeaponData 中配置 |
| 技能消耗量 | 在各 SkillData 中配置 |
| 技能前摇时长 | 在各 SkillData 中配置 |

> **扩展原则**：新增形态时，只需：
> 1. 创建新的 `FormData`（含武器和技能引用）
> 2. 将其加入形态配置列表的新槽位
> 3. 为新槽位绑定输入键位
> 
> 无需修改任何现有系统逻辑。