Echo/Assets/_Project/Docs/FaintEndingSystem_Technical_Reference.md

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

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

一、脚本

• 昏倒演出控制器：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，并在 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。

五、常见排错

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