# 03 · 玩家系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：玩家实体的构成、资源模型、状态机规范与对外行为契约。  
> **关联**：[04_CombatSystem](./04_CombatSystem.md) · [05_MovementSystem](./05_MovementSystem.md) · [06_FormSystem](./06_FormSystem.md)

---

## 目录

1. [玩家实体构成](#1-玩家实体构成)
2. [资源模型](#2-资源模型)
3. [玩家状态机](#3-玩家状态机)
4. [行为契约](#4-行为契约)
5. [能力解锁体系](#5-能力解锁体系)
6. [玩家配置参数](#6-玩家配置参数)
7. [发出的事件](#7-发出的事件)

---

## 1. 玩家实体构成

玩家实体是多个**职责分离的子系统**的协调器，自身不含具体业务逻辑：

```
PlayerEntity（协调器）
├── MovementController    ← 物理移动（速度、跳跃、冲刺）
├── StatContainer         ← 资源数值（HP、灵力、魄元、灵泉、Geo）
├── CombatHandler         ← 攻击判定（HitBox 开关、连击链）
├── FormController        ← 形态管理（天魂/地魂/命魂切换）
├── WeaponSlot            ← 当前武器（形态联动自动切换）
├── SkillExecutor         ← 技能执行（魂技能/魄技能）
├── ParryHandler          ← 弹反逻辑
├── HurtBox               ← 受击判定（路由 DamagePacket）
└── StateMachine          ← 行为状态机（协调上述子系统）
```

**协调器原则**：PlayerEntity 只负责：
1. 初始化子系统并维护引用
2. 维护状态机（决定当前行为）
3. 在受击时强制转换到受击状态
4. 在死亡时触发 `OnPlayerDied` 事件

---

## 2. 资源模型

### 2.1 资源总览

| 资源 | 类型 | 范围 | 特性 | 用途 |
|------|------|------|------|------|
| **HP** | Integer | 0 ~ MaxHP | 受击减少，存档点/灵泉恢复 | 生存指标 |
| **灵力（SoulPower）** | Integer | 0 ~ 100 | 近战命中积累，死亡清零 | 魂技能燃料 |
| **魄元（SpiritPower）** | Integer | 0 ~ 100 | 时间自动恢复，死亡恢复至上限 | 魄技能燃料 |
| **灵泉次数（SpringCharges）** | Integer | 0 ~ MaxCharges | 击杀积分驱动，存档点恢复 | 治疗次数 |
| **Geo（灵晶）** | Integer | 0 ~ ∞ | 击败敌人获得，死亡遗留遗骸 | 货币 |

### 2.2 灵力积累规则

> **设计目标**：鼓励玩家主动攻击，弹反作为高回报行为

| 来源 | 灵力增量 |
|------|---------|
| 近战命中普通敌人 | +10 |
| 近战命中 Boss | +5 |
| 弹反成功 | +33 |

- 死亡时归零
- 无自动恢复

### 2.3 魄元恢复规则

> **设计目标**：魄元是始终可用的"持续消耗"资源，不依赖风险操作

| 来源 | 魄元增量 |
|------|---------|
| 每秒自动恢复 | +`spiritRegenRate`（见配置参数）|
| 死亡复活 | 恢复至上限 |
| 存档点交互 | 恢复至上限 |

- 受伤不影响魄元
- 使用魄技能后扣除固定量

### 2.4 灵泉次数规则

> **设计目标**：治疗是"击杀驱动"而非"时间驱动"，鼓励激进战斗风格

| 来源 | 变化 |
|------|------|
| 击杀普通敌人 | +1 积分 |
| 击杀精英怪 | +3 积分 |
| 击杀 Boss | +5 积分 |
| 积分达到阈值 | +1 次灵泉（积分清零）|
| 使用灵泉（治疗）| -1 次 |
| 与存档点交互 | 恢复至上限 |
| 死亡复活 | **不恢复**（死亡惩罚）|

> **设计决策**：死亡不恢复灵泉  
> **原因**：保留一定死亡惩罚，让玩家珍惜治疗机会，但由于复活在存档点旁，玩家仍可快速通过激活存档点补满

### 2.5 Geo（货币）规则

| 来源 | 变化 |
|------|------|
| 击败敌人 | 掉落固定 + 随机范围 |
| 破坏场景容器 | 少量固定 |
| 任务奖励 | 固定量 |
| 死亡 | Geo 留在遗骸，不直接丢失 |
| 取回遗骸 | 遗骸的 Geo 归还玩家 |
| 再次死亡（未取回遗骸）| 遗骸 Geo **永久丢失** |

---

## 3. 玩家状态机

### 3.1 状态优先级

| 优先级 | 状态 | 说明 |
|--------|------|------|
| 100 | `DeathState` | 死亡，不可被任何状态打断 |
| 90 | `HurtState` | 受击硬直，仅死亡可打断 |
| 80 | `DashState` | 冲刺（含空中冲刺），受伤/死亡可打断 |
| 75 | `SoulSkillState` | 魂技能前摇，冲刺/受伤可打断 |
| 72 | `SpiritSkillState` | 魄技能前摇，冲刺/受伤可打断 |
| 70 | `ParryState` | 弹反等待，受伤可打断 |
| 60 | `AttackState` | 攻击，弹反/受伤可打断 |
| 55 | `SpringState` | 使用灵泉，前摇可被打断 |
| 40 | `InteractState` | 与 NPC/物件交互 |
| 35 | `WallGrabState` | 抓墙悬挂，冲刺/技能可打断 |
| 30 | `AirState` | 空中（含跳跃/下落）|
| 20 | `RunState` | 地面奔跑 |
| 10 | `SwimState` | 游泳（解锁后）|
| 0 | `IdleState` | 待机（最低优先级）|

### 3.2 状态转换规则

```
任意状态
  ══受击(HP>0)══►  HurtState      [强制，忽略优先级]
  ══受击(HP=0)══►  DeathState     [强制，不可被打断]

IdleState
  ──移动输入──────────►  RunState
  ──跳跃输入──────────►  AirState
  ──攻击输入──────────►  AttackState
  ──弹反输入──────────►  ParryState
  ──冲刺输入──────────►  DashState
  ──魂技能+灵力充足───►  SoulSkillState
  ──魄技能+魄元充足───►  SpiritSkillState
  ──使用灵泉+次数≥1──►  SpringState
  ──交互输入+目标存在─►  InteractState

RunState
  ──无移动输入─────────►  IdleState
  ──跳跃输入───────────►  AirState
  ──攻击输入───────────►  AttackState（保持RunState，上半身叠加）
  ──弹反/冲刺/技能─────►  对应状态

AirState（统一处理 跳跃/双跳/下落）
  ──落地───────────────►  IdleState 或 RunState
  ──跳跃输入+双跳可用──►  AirState内重置（双跳，不切状态）
  ──贴墙+朝墙方向输入──►  WallGrabState
  ──攻击/弹反/冲刺─────►  对应状态

WallGrabState
  ──跳跃输入───────────►  AirState（蹬墙跳）
  ──反向输入或落地─────►  AirState / IdleState
  ──冲刺/技能──────────►  对应状态

AttackState（上半身叠加，下半身保持原状态）
  ~~动画结束~~──────────►  恢复原状态（Idle/Run/Air）
  ──连击窗口内攻击输入─►  AttackState（切换连击段）
  ──弹反输入───────────►  ParryState

ParryState
  ──弹反成功───────────►  ParrySuccessState（反击窗口）
    ──攻击输入（窗口内）─►  AttackState（ParryCounter）
    ~~反击窗口超时~~─────►  IdleState/RunState
  ~~弹反超时~~──────────►  IdleState/RunState

DashState
  ~~冲刺时长结束~~────── ►  AirState 或 IdleState/RunState

SpringState
  ~~前摇完成~~──────────►  后摇 → IdleState
  ──被打断─────────────►  IdleState（灵泉次数已扣，不返还）

HurtState
  ~~硬直时长结束~~──────►  IdleState

DeathState
  （等待游戏管理器触发复活流程）
```

### 3.3 攻击连击链

| 连击段 | 触发方式 | 攻击方向 | 伤害倍率 | 备注 |
|--------|---------|---------|---------|------|
| `Attack1` | 第一次攻击输入 | 水平 | ×1.0 | 各形态动画不同 |
| `Attack2` | 连击窗口内再攻击 | 水平 | ×1.0 | |
| `Attack3` | 连击窗口内再攻击 | 水平 | ×2.0 | 重击，连击链结尾 |
| `AirAttack` | 空中攻击 | 水平 | ×1.0 | |
| `UpAttack` | 移动方向向上时攻击 | 向上 | ×1.0 | 角色轻微下移（反作用力）|
| `DownAttack` | 空中+移动方向向下时攻击 | 向下 | ×1.0 | 命中时产生弹起（Pogo）|
| `ParryCounter` | 弹反成功后攻击 | 水平 | ×3.0 | 不可被弹反，忽略无敌帧 |

> **设计决策**：第三击伤害 ×2，弹反反击 ×3  
> **原因**：鼓励打满连击，奖励弹反技巧。高倍率使玩家有显著的策略目标。

---

## 4. 行为契约

### 4.1 玩家实体对外接口

```
Interface IPlayerEntity {
    // 只读属性
    [readonly] position        : Vector2
    [readonly] facingDirection : Integer    // +1 右 / -1 左
    [readonly] currentState    : StateID
    [readonly] isInvincible    : Boolean

    // 强制状态切换（外部系统使用，如受击）
    forceState(stateId: StateID, context: Optional<StateContext>) → void

    // 查询
    hasAbility(abilityId: ID) → Boolean

    // 事件
    [event] onDied         : Event<void>
    [event] onHit          : Event<HitPayload>
    [event] onStateChanged : Event<StateChangedPayload>
}
```

### 4.2 StatContainer 对外接口

```
Interface IStatContainer {
    [readonly] currentHP           : Integer
    [readonly] maxHP               : Integer
    [readonly] currentSoulPower    : Integer
    [readonly] currentSpiritPower  : Integer
    [readonly] currentSpringCharges: Integer
    [readonly] maxSpringCharges    : Integer
    [readonly] currentGeo          : Integer
    [readonly] isAlive             : Boolean

    takeDamage(amount: Integer)           → void
    heal(amount: Integer)                 → void
    addSoulPower(amount: Integer)         → void
    consumeSoulPower(amount: Integer)     → Result<Boolean>
    consumeSpiritPower(amount: Integer)   → Result<Boolean>
    addKillCredit(creditType: KillType)   → void    // 驱动灵泉积分
    useSpring()                           → Result<Boolean>
    restoreSpringCharges()                → void
    addGeo(amount: Integer)               → void
    spendGeo(amount: Integer)             → Result<Boolean>
    beginInvincibility(duration: Duration)→ void

    [event] onHPChanged            : Event<{current, max}>
    [event] onSoulPowerChanged     : Event<{current, max}>
    [event] onSpiritPowerChanged   : Event<{current, max}>
    [event] onSpringChargesChanged : Event<{current, max}>
    [event] onGeoChanged           : Event<{current, delta}>
    [event] onDied                 : Event<void>
}
```

---

## 5. 能力解锁体系

### 5.1 能力定义

| 能力 ID | 默认状态 | 影响的状态/行为 | 解锁位置 |
|---------|---------|--------------|---------|
| `DoubleJump` | 锁定 | AirState 允许第二次跳跃 | 探索奖励 |
| `WallGrab` | **已解锁** | AirState → WallGrabState 允许 | 初始能力 |
| `AerialDash` | 锁定 | AirState → DashState 允许（消耗充能）| 探索奖励 |
| `Parry` | **已解锁** | ParryState 可进入 | 初始能力 |
| `Swim` | 锁定 | 液体区域不死亡，SwimState 可进入 | 主线解锁 |
| `PlungeAttack` | 锁定 | 空中向下冲刺触发下冲 | 探索奖励 |

### 5.2 解锁流程

```
玩家触碰解锁物件（AbilityUnlockItem）
  → 世界系统发出 OnCollectiblePickedUp（type=Ability, abilityId）
  → 进程系统处理：将 abilityId 加入已解锁集合
  → 进程系统发出 OnAbilityUnlocked（abilityId）
  → 玩家系统接收：更新运行时能力标记
  → UI 系统显示能力获得动画
  → 存档系统：在下次存档时持久化
```

---

## 6. 玩家配置参数

以下参数在配置数据中定义，运行时只读：

| 参数 | 类型 | 推荐值 | 说明 |
|------|------|--------|------|
| `maxHP` | Integer | 5 | 初始最大生命值 |
| `maxSoulPower` | Integer | 100 | 灵力上限 |
| `maxSpiritPower` | Integer | 100 | 魄元上限 |
| `spiritRegenRate` | Number | 8.0/s | 魄元每秒自动回复量 |
| `maxSpringCharges` | Integer | 3 | 初始最大灵泉次数 |
| `springKillThreshold` | Integer | 5 | 增加 1 次灵泉所需积分 |
| `iFrameAfterHit` | Duration | 1.2s | 受击后无敌时长 |
| `comboWindowDuration` | Duration | 0.5s | 连击窗口时长 |
| `comboResetDelay` | Duration | 0.3s | 第三击后连击重置延迟 |
| `parryCounterDuration` | Duration | 0.6s | 弹反后反击窗口时长 |

---

## 7. 发出的事件

| 事件 | 触发时机 | 载荷 |
|------|---------|------|
| `OnPlayerDied` | HP 归零 | `void` |
| `OnHPChanged` | HP 任意变化 | `{current, max}` |
| `OnSoulPowerChanged` | 灵力变化 | `{current, max}` |
| `OnSpiritPowerChanged` | 魄元变化 | `{current, max}` |
| `OnSpringChargesChanged` | 灵泉次数变化 | `{current, max}` |
| `OnGeoChanged` | Geo 增减 | `{current, delta}` |
| `OnFormChanged` | 形态切换 | `{newFormId}` |
| `OnParrySuccess` | 弹反成功 | `{counterWindowDuration}` |
| `OnHitConfirmed` | 攻击命中有效目标 | `HitPayload` |
| `OnAbilityUnlocked` | 新能力获得 | `{abilityId}` |