Echo/Assets/_Project/Docs/PlayerVitalsSystem_Setup.md

玩家三维数值条（Thirst / Hunger / Sanity）接入说明

目标：在不修改 ThirdParty（Reach UI）脚本的前提下，实现三项数值随时间衰减、可被事件/物品即时增减，并通过 Reach 的 HUD Health Bar 显示。

一、脚本清单

新增：

• PlayerVitalsSystem.cs
• VitalStat.cs
• VitalsHUD.cs

修改：

• ItemData.cs
• ItemUsageSystem.cs

二、场景/Hierarchy 操作步骤（你现在的 Statebars 结构继续用）

1) 在 Player 上挂载数值系统

1. 选中 Player（挂了 PlayerController / ItemUsageSystem 的那个对象）
2. Add Component：PlayerVitalsSystem
3. 在 Inspector 中配置三项（Thirst/Hunger/Sanity）：
   • maxValue：例如 100
   • currentValue：例如 100
   • decayPerMinute：按你的设计填（比如 Hunger 12，Sanity 3，Thirst 6）
4. 阈值效果（可选，先留空也行）：
   • 展开 thresholds
   • 添加一条或多条阈值（0~1）
   • 在 onEnter/onExit 里后续可绑定相机抖动、眩晕、GameOver 等事件

2) 在 UI 上绑定三条 Reach Bar

你已经在 Canvas 下创建了 Statebars，并从 Reach UI > HUD > Health Bar 创建了 3 条。

1. 在 Statebars 或 Canvas 下新增一个组件载体（推荐直接用 Statebars）
2. Add Component：VitalsHUD
3. 把引用拖进去：
   • Target：拖入 Player 上的 PlayerVitalsSystem
   • Thirst Bar / Hunger Bar / Sanity Bar：分别拖入三条 Reach Health Bar（组件类型是 Michsky.UI.Reach.ProgressBar）

运行时 VitalsHUD 会把三项数值的 min/max/current 同步到三条 Reach Bar，并在数值变化时自动刷新 UI。

3) 让 ItemUsageSystem 驱动消耗品对三维的影响

ItemUsageSystem 已接入：

1. 选中 Player 上的 ItemUsageSystem
2. 看到 Inspector 里新增了 Vitals System 字段：
   • 推荐手动拖入 Player 上的 PlayerVitalsSystem（最稳）
   • 不拖也可以，它会在运行时自动尝试找到实例

4) 配置消耗品的数值改变量

在每个消耗品 ItemData（ScriptableObject）里新增了三项：

• thirstDelta
• hungerDelta
• sanityDelta

示例：

• 食物：hungerDelta = +20，sanityDelta = +2
• 药物：thirstDelta = +25，sanityDelta = -5
• 毒药：thirstDelta = -30

三、运行验证（最小闭环）

1. 进入 Play Mode
2. 不做任何操作，观察 Hunger/Sanity 是否按 decayPerMinute 下降，UI 是否同步下降
3. 在背包里放入一个配置了 delta 的 Consumable，按 Use 使用
4. 观察三条数值是否按配置立刻变化，且 UI 同步

四、常见问题

1) UI 不动

• 检查 VitalsHUD 是否引用到了正确的三条 Reach Bar（ProgressBar 组件）
• 检查 VitalsHUD.target 是否指向 Player 上的 PlayerVitalsSystem
• 检查 Player 是否真的在场景里只有一个 PlayerVitalsSystem（若多个可能被单例销毁其一）

2) 数值变化但条显示不对

• 确认 maxValue 在 PlayerVitalsSystem 里配置正确（Reach 的 fillAmount 依赖 current/max）
• 确认条的 minValue/maxValue 没被别的 UI 脚本覆盖