# 昏倒结局动画系统（Faint Ending System）技术说明

目标：当玩家三维中的某项数值降到最低（例如 0）时，触发“昏倒”演出：逐步加深黑色遮罩、相机向前向下移动并俯仰下压，中途停顿与回弹，最终彻底倒地全黑，然后弹出结算/返回主菜单 UI。

## 一、脚本
- 昏倒演出控制器：[FaintEndingSequenceController.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/EndingSystem/FaintEndingSequenceController.cs)

## 二、系统行为（对应你的步骤）
0) 禁用玩家移动/视角：脚本会禁用 `Player.PlayerController`（不切 ActionMap，不强制显示鼠标）  
1) 黑色遮罩 Alpha 上升，同时相机向前向下移动 + 俯仰向下旋转  
2) 到达“半倒”姿态后停止并保持（遮罩停在半透明）  
3) 相机回弹抬高一点并回正一点（遮罩也回透明一点）  
4) 完全倒下（面朝地 + 离地一点点高度），遮罩变全黑  
5) 解锁鼠标并激活结算 UI（Inspector 提供槽位）

## 三、场景接入步骤（Inspector，按顺序）
### 1) 创建/放置控制器物体
1. 在你的关卡场景中新建空物体：`_FaintEndingSystem`
2. Add Component：`FaintEndingSequenceController`

### 2) 准备黑屏遮罩（CanvasGroup）
1. 在你的 UI Canvas 下新建一个全屏 Image：`FaintBlackScreen`
2. Image 颜色：纯黑
3. 给该物体添加 `CanvasGroup`，并设置：
   - Alpha = 0
   - Interactable = false
   - Blocks Raycasts = false
4. 把这个 `CanvasGroup` 拖到 `FaintEndingSequenceController.blackScreenCanvasGroup`

### 3) 准备结算 UI（你自己制作）
1. 在 Canvas 下准备你的结算/返回主菜单 UI 根节点（例如 `FaintEndingUIPanel`）
2. 初始建议 SetActive=false（不设也行，脚本触发时会先隐藏一次）
3. 把它拖到 `FaintEndingSequenceController.endingUIPanel`
4. 若该结算 UI 需要“打开即预加载主菜单场景 + 点击返回主菜单 + AI 总结文案 + 结局状态提示词”，可在该 UI 根节点上额外挂载 [EndingUIScreenController.cs](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Scripts/UI/EndingUIScreenController.cs)，并在 Inspector 里把 `Outcome` 设为 `Fainted`，同时绑定 `Summaray Text / Information Text` 两个文本槽位与对应按钮。

### 4) 绑定玩家与相机引用
在 `FaintEndingSequenceController` 上拖引用：
- Player Controller：拖 Player 根节点上的 `Player.PlayerController`
- Camera Transform：拖玩家摄像机 Transform（或留空，它会尝试用 `Camera.main`）
- Camera Pivot：拖摄像机的父物体（用于上下俯仰的 pivot；或留空，它会取 `cameraTransform.parent`）

### 5) 调参数（演出姿态）
所有阶段的“位置与俯仰”都以“触发时刻的相机姿态”为基准：
- `step1CameraLocalOffset / step3CameraLocalOffset / step4CameraLocalOffset`：相机 localPosition 偏移（向前 Z 为正、向下 Y 为负）
- `step1Pitch / step3Pitch / step4Pitch`：在触发时刻的俯仰角基础上追加的角度（正数代表向下压）
- `step1Alpha / step3Alpha / step4Alpha`：遮罩透明度（0~1）
- `step2HoldDuration`：半倒停顿时间

## 四、如何从 Vitals 触发（推荐方式）
工程内的 `VitalStat` 支持阈值事件（onEnter/onExit），适合做“到 0 触发一次”的演出。

### 做法：用 Threshold Rule 绑定事件
1. 选中 Player（挂了 `PlayerVitalsSystem` 的对象）
2. 在 `health` / `hunger` / `sanity`（你要监测的那一项）展开 `thresholds`
3. 添加一条 Rule：
   - `normalizedThreshold` = 0
   - `onEnter`：绑定场景中的 `_FaintEndingSystem` 上的 `FaintEndingSequenceController.StartFaintSequence()`

参考：三维系统接入与阈值说明见 [PlayerVitalsSystem_Setup.md](file:///e:/Unity/Unity%20Program/Test_2022/Assets/_Project/Docs/PlayerVitalsSystem_Setup.md)。

## 五、常见排错
- 触发了但镜头不动：
  - 检查 `Camera Transform` 是否绑定正确（或场景里是否有 `MainCamera` Tag）
  - 检查相机是否是 `cameraPivot` 的子物体（否则俯仰不会按预期工作）
- 黑屏遮罩没效果/一闪而过：
  - 检查 `FaintBlackScreen` 是否被其它系统 `SetActive(false)`（例如开场序列复用同一个遮罩）
  - 检查 `FaintBlackScreen` 上是否挂了 `CanvasGroupAnimator` / `ImageFading` / `Animator` 这类会抢写 alpha 的组件
  - 推荐给 `FaintBlackScreen` 单独放在一个置顶的 Canvas（或确保 SortingOrder 比其它 UI 大）
- UI 没弹出来：
  - 检查 `endingUIPanel` 是否拖了正确对象
  - 检查 UI 的 Canvas SortingOrder 是否被黑屏遮罩盖住（黑屏 Image 应该在最上层）