938 lines
34 KiB
Markdown
938 lines
34 KiB
Markdown
# 18 · VFX 与反馈模块（VFX & Feedback Module）
|
||
|
||
> **命名空间** `BaseGames.VFX` / `BaseGames.Feedback`
|
||
> **程序集** `BaseGames.VFX`（`Assets/Scripts/VFX/`）
|
||
> **依赖** Feel v4.3 · `BaseGames.Core`（GlobalObjectPool）· `BaseGames.Combat`（HitFxType · DamageInfo）· `BaseGames.Camera`（CameraStateController）
|
||
> **Design 来源** [41_VFXArchitecture](../Design/41_VFXArchitecture.md) · [07_FeedbackSystem](../Design/07_FeedbackSystem.md)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [模块职责](#1-模块职责)
|
||
2. [IFeedbackPlayer 接口](#2-ifeedbackplayer-接口)
|
||
3. [PlayerFeedback](#3-playerfeedback)
|
||
4. [EnemyFeedback](#4-enemyfeedback)
|
||
5. [FeedbackConfigSO](#5-feedbackconfigso)
|
||
6. [VFXPool — 粒子对象池](#6-vfxpool--粒子对象池)
|
||
7. [VFXCatalogSO — VFX 映射字典](#7-vfxcatalogso--vfx-映射字典)
|
||
8. [HitFXSpawner](#8-hitfxspawner)
|
||
9. [HurtFlashController](#9-hurtflashcontroller)
|
||
10. [PaletteSwapSystem](#10-paletteswapsystem)
|
||
11. [PostProcessManager](#11-postprocessmanager)
|
||
12. [RegionLightController](#12-regionlightcontroller)
|
||
13. [事件频道](#13-事件频道)
|
||
14. [VFX 分类与生命周期策略](#14-vfx-分类与生命周期策略)
|
||
15. [VFX 性能约束](#15-vfx-性能约束)
|
||
16. [MMF_Player 命名规范](#16-mmf_player-命名规范)
|
||
|
||
---
|
||
|
||
## 1. 模块职责
|
||
|
||
```
|
||
VFX & Feedback 模块职责:
|
||
├─ IFeedbackPlayer → 反馈抽象接口（GameLogic 依赖此接口，不依赖 Feel）
|
||
├─ PlayerFeedback → 玩家侧 MMF_Player 聚合，实现 IFeedbackPlayer
|
||
├─ EnemyFeedback → 敌人侧 MMF_Player 聚合
|
||
├─ FeedbackConfigSO → 全局反馈参数（冻帧时长、震屏强度等）
|
||
├─ VFXPool → ParticleSystem 专用对象池
|
||
├─ VFXCatalogSO → HitFxType → VFX Prefab AddressKey 映射
|
||
├─ HitFXSpawner → 监听 OnHitConfirmed，路由命中特效
|
||
├─ HurtFlashController → Shader 属性块驱动的受击白闪
|
||
└─ PaletteSwapSystem → 形态切换时精灵调色板替换
|
||
```
|
||
|
||
**零耦合**：`HitFXSpawner` 通过 `EVT_HitConfirmed` 事件频道获取命中信息，不直接引用战斗系统。
|
||
|
||
---
|
||
|
||
## 2. IFeedbackPlayer 接口
|
||
|
||
```csharp
|
||
namespace BaseGames.Feedback
|
||
{
|
||
/// <summary>
|
||
/// 反馈执行器的抽象接口。
|
||
/// GameLogic（PlayerCombat / EnemyBase）依赖此接口，不依赖 Feel 资产。
|
||
/// 测试时可替换为 NullFeedbackPlayer。
|
||
/// </summary>
|
||
public interface IFeedbackPlayer
|
||
{
|
||
void PlayHit(HitWeight weight); // 命中反馈（轻/中/重）
|
||
void PlayParrySuccess(); // 弹反成功
|
||
void PlayTakeHit(); // 玩家/敌人受击
|
||
void PlayDeath(); // 死亡演出
|
||
void PlayHeal(); // 治疗
|
||
void PlayLandImpact(); // 落地冲击
|
||
void PlayAttackWhoosh(); // 攻击挥动音效
|
||
void PlayJumpLaunch(); // 起跳
|
||
void TriggerPreset(string presetId); // 通过 ID 触发任意预设（AnimEvent 用）
|
||
void PlaySFXById(string sfxId); // 通过 ID 播放音效（AnimEvent 用）
|
||
}
|
||
|
||
/// <summary>空实现，用于测试和无反馈需求场景。</summary>
|
||
public class NullFeedbackPlayer : IFeedbackPlayer
|
||
{
|
||
public void PlayHit(HitWeight w) { }
|
||
public void PlayParrySuccess() { }
|
||
public void PlayTakeHit() { }
|
||
public void PlayDeath() { }
|
||
public void PlayHeal() { }
|
||
public void PlayLandImpact() { }
|
||
public void PlayAttackWhoosh() { }
|
||
public void PlayJumpLaunch() { }
|
||
public void TriggerPreset(string id) { }
|
||
public void PlaySFXById(string id) { }
|
||
}
|
||
|
||
public enum HitWeight { Light, Medium, Heavy }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. PlayerFeedback
|
||
|
||
```csharp
|
||
namespace BaseGames.Feedback
|
||
{
|
||
/// <summary>
|
||
/// 挂在 Player Prefab 根节点下的 [Feedback] 子 GameObject 上。
|
||
/// 实现 IFeedbackPlayer，聚合所有玩家相关 MMF_Player。
|
||
/// </summary>
|
||
public class PlayerFeedback : MonoBehaviour, IFeedbackPlayer
|
||
{
|
||
// ── MMF_Player 引用（Inspector 配置）────────────────
|
||
[Header("命中反馈")]
|
||
[SerializeField] MMF_Player _onHitLight;
|
||
[SerializeField] MMF_Player _onHitMedium;
|
||
[SerializeField] MMF_Player _onHitHeavy;
|
||
|
||
[Header("战斗反馈")]
|
||
[SerializeField] MMF_Player _onParrySuccess;
|
||
[SerializeField] MMF_Player _onTakeHit;
|
||
[SerializeField] MMF_Player _onDeath;
|
||
|
||
[Header("移动反馈")]
|
||
[SerializeField] MMF_Player _onHeal;
|
||
[SerializeField] MMF_Player _onLandImpact;
|
||
[SerializeField] MMF_Player _onAttackWhoosh;
|
||
[SerializeField] MMF_Player _onJumpLaunch;
|
||
|
||
[Header("配置")]
|
||
[SerializeField] FeedbackConfigSO _config;
|
||
|
||
// ── Dictionary 预设（runtime，用于 TriggerPreset）───
|
||
Dictionary<string, MMF_Player> _presetMap;
|
||
|
||
void Awake()
|
||
{
|
||
_presetMap = new Dictionary<string, MMF_Player>
|
||
{
|
||
{ "HitLight", _onHitLight },
|
||
{ "HitMedium", _onHitMedium },
|
||
{ "HitHeavy", _onHitHeavy },
|
||
{ "ParrySuccess", _onParrySuccess },
|
||
{ "TakeHit", _onTakeHit },
|
||
{ "Death", _onDeath },
|
||
{ "LandImpact", _onLandImpact },
|
||
};
|
||
}
|
||
|
||
// ── IFeedbackPlayer 实现 ─────────────────────────────
|
||
public void PlayHit(HitWeight weight)
|
||
{
|
||
switch (weight)
|
||
{
|
||
case HitWeight.Light: _onHitLight?.PlayFeedbacks(); break;
|
||
case HitWeight.Medium: _onHitMedium?.PlayFeedbacks(); break;
|
||
case HitWeight.Heavy: _onHitHeavy?.PlayFeedbacks(); break;
|
||
}
|
||
}
|
||
public void PlayParrySuccess() => _onParrySuccess?.PlayFeedbacks();
|
||
public void PlayTakeHit() => _onTakeHit?.PlayFeedbacks();
|
||
public void PlayDeath() => _onDeath?.PlayFeedbacks();
|
||
public void PlayHeal() => _onHeal?.PlayFeedbacks();
|
||
public void PlayLandImpact() => _onLandImpact?.PlayFeedbacks();
|
||
public void PlayAttackWhoosh() => _onAttackWhoosh?.PlayFeedbacks();
|
||
public void PlayJumpLaunch() => _onJumpLaunch?.PlayFeedbacks();
|
||
|
||
public void TriggerPreset(string presetId)
|
||
{
|
||
if (_presetMap.TryGetValue(presetId, out var player))
|
||
player?.PlayFeedbacks();
|
||
}
|
||
|
||
public void PlaySFXById(string sfxId)
|
||
{
|
||
// ⚠️ AudioManager.PlaySFX 接受 AudioClip（非 string）（架构 11_AudioModule §2）
|
||
// sfxId → AudioClip 解析需通过 SFX 目录；此处留空实现待扩展
|
||
// 具体用法：持有 SFXCatalogSO 引用，查表后调用 AudioManager.Instance.PlaySFX(clip)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Player Prefab 层级**：
|
||
|
||
```
|
||
[Player]
|
||
└── [Feedback]
|
||
├── PlayerFeedback.cs
|
||
├── MMF_Player_OnHitLight
|
||
├── MMF_Player_OnHitMedium
|
||
├── MMF_Player_OnHitHeavy
|
||
├── MMF_Player_OnParrySuccess
|
||
├── MMF_Player_OnTakeHit
|
||
├── MMF_Player_OnDeath
|
||
├── MMF_Player_OnHeal
|
||
├── MMF_Player_OnLandImpact
|
||
├── MMF_Player_OnAttackWhoosh
|
||
└── MMF_Player_OnJumpLaunch
|
||
```
|
||
|
||
---
|
||
|
||
## 4. EnemyFeedback
|
||
|
||
```csharp
|
||
namespace BaseGames.Feedback
|
||
{
|
||
/// <summary>
|
||
/// 挂在 EnemyBase Prefab 下的 [Feedback] 子 GameObject 上。
|
||
/// EnemyBase 通过 [SerializeField] EnemyFeedback _feedback 引用。
|
||
/// </summary>
|
||
public class EnemyFeedback : MonoBehaviour, IFeedbackPlayer
|
||
{
|
||
[SerializeField] MMF_Player _onTakeHit;
|
||
[SerializeField] MMF_Player _onDeath;
|
||
[SerializeField] MMF_Player _onHitLight;
|
||
[SerializeField] MMF_Player _onHitMedium;
|
||
[SerializeField] MMF_Player _onHitHeavy;
|
||
|
||
// IFeedbackPlayer 实现（敌人侧只需命中/受击/死亡）
|
||
public void PlayHit(HitWeight weight)
|
||
{
|
||
switch (weight)
|
||
{
|
||
case HitWeight.Light: _onHitLight?.PlayFeedbacks(); break;
|
||
case HitWeight.Medium: _onHitMedium?.PlayFeedbacks(); break;
|
||
case HitWeight.Heavy: _onHitHeavy?.PlayFeedbacks(); break;
|
||
}
|
||
}
|
||
public void PlayTakeHit() => _onTakeHit?.PlayFeedbacks();
|
||
public void PlayDeath() => _onDeath?.PlayFeedbacks();
|
||
|
||
// 未使用的接口方法（空实现）
|
||
public void PlayParrySuccess() { }
|
||
public void PlayHeal() { }
|
||
public void PlayLandImpact() { }
|
||
public void PlayAttackWhoosh() { }
|
||
public void PlayJumpLaunch() { }
|
||
public void TriggerPreset(string id) { }
|
||
public void PlaySFXById(string id) { }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. FeedbackConfigSO
|
||
|
||
```csharp
|
||
namespace BaseGames.Feedback
|
||
{
|
||
[CreateAssetMenu(menuName = "Feedback/FeedbackConfig")]
|
||
public class FeedbackConfigSO : ScriptableObject
|
||
{
|
||
[Header("冻帧")]
|
||
[Range(0f, 0.2f)]
|
||
public float FreezeFrameDuration = 0.033f; // 默认 2 帧（60fps）
|
||
[Range(0f, 0.2f)]
|
||
public float ParryFreezeFrameDuration = 0.067f; // 弹反冻帧更长
|
||
|
||
[Header("子弹时间")]
|
||
[Range(0.01f, 1f)]
|
||
public float BulletTimeScale = 0.15f;
|
||
[Range(0f, 1f)]
|
||
public float BulletTimeDuration = 0.3f;
|
||
|
||
[Header("镜头震动强度")]
|
||
public float ShakeLightForce = 0.2f;
|
||
public float ShakeMediumForce = 0.5f;
|
||
public float ShakeHeavyForce = 1.0f;
|
||
public float ShakeParryForce = 0.8f;
|
||
|
||
[Header("受击白闪")]
|
||
public Color HurtFlashColor = Color.white;
|
||
[Range(0f, 0.5f)]
|
||
public float HurtFlashDuration = 0.15f;
|
||
}
|
||
}
|
||
```
|
||
|
||
**资产路径**：`Assets/ScriptableObjects/Feedback/Feedback_Config.asset`
|
||
|
||
---
|
||
|
||
## 6. VFXPool — 粒子对象池
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// ParticleSystem 专用对象池，挂在 Persistent 场景 [VFXPool] GameObject 上。
|
||
/// 粒子播放完成（或超过 MaxLifetime）后自动回池，调用方无需手动归还。
|
||
/// 不依赖 UniTask，使用 Coroutine 驱动回收。
|
||
/// </summary>
|
||
public class VFXPool : MonoBehaviour
|
||
{
|
||
public static VFXPool Instance { get; private set; }
|
||
|
||
[SerializeField, Min(1f)] private float _globalMaxLifetime = 10f;
|
||
|
||
private readonly Dictionary<AssetReferenceGameObject, Queue<ParticleSystem>> _pools
|
||
= new Dictionary<AssetReferenceGameObject, Queue<ParticleSystem>>();
|
||
|
||
private void Awake() => Instance = this;
|
||
|
||
/// <summary>
|
||
/// 在世界坐标播放一次特效（Fire-and-forget，Coroutine 自动回池）。
|
||
/// </summary>
|
||
public void Play(AssetReferenceGameObject vfxRef,
|
||
Vector3 position,
|
||
Quaternion rotation = default,
|
||
float maxLifetime = 0f)
|
||
{
|
||
StartCoroutine(PlayCoroutine(vfxRef, position, rotation, maxLifetime));
|
||
}
|
||
|
||
/// <summary>预热：预先创建若干实例避免首次播放卡顿。</summary>
|
||
public void Warmup(AssetReferenceGameObject vfxRef, int count)
|
||
{
|
||
StartCoroutine(WarmupCoroutine(vfxRef, count));
|
||
}
|
||
|
||
private IEnumerator PlayCoroutine(AssetReferenceGameObject vfxRef,
|
||
Vector3 position, Quaternion rotation, float maxLifetime)
|
||
{
|
||
ParticleSystem ps = null;
|
||
if (!TryDequeue(vfxRef, out ps))
|
||
{
|
||
var op = Addressables.InstantiateAsync(vfxRef, transform);
|
||
yield return op;
|
||
if (op.Result == null) { Debug.LogError($"[VFXPool] Failed: {vfxRef.RuntimeKey}"); yield break; }
|
||
ps = op.Result.GetComponent<ParticleSystem>();
|
||
if (ps == null) { Addressables.ReleaseInstance(op.Result); yield break; }
|
||
ps.gameObject.SetActive(false);
|
||
}
|
||
|
||
ps.transform.SetPositionAndRotation(position, rotation);
|
||
ps.gameObject.SetActive(true);
|
||
ps.Play();
|
||
|
||
float limit = maxLifetime > 0f ? maxLifetime : _globalMaxLifetime;
|
||
float elapsed = 0f;
|
||
while (elapsed < limit && ps.IsAlive(true))
|
||
{
|
||
elapsed += Time.deltaTime;
|
||
yield return null;
|
||
}
|
||
|
||
if (ps.IsAlive(true))
|
||
{
|
||
ps.Stop(true, ParticleSystemStopBehavior.StopEmittingAndClear);
|
||
Debug.LogWarning($"[VFXPool] '{vfxRef.RuntimeKey}' 超过 {limit:F1}s 强制回收。");
|
||
}
|
||
|
||
ps.gameObject.SetActive(false);
|
||
Enqueue(vfxRef, ps);
|
||
}
|
||
|
||
private IEnumerator WarmupCoroutine(AssetReferenceGameObject vfxRef, int count)
|
||
{
|
||
for (int i = 0; i < count; i++)
|
||
{
|
||
var op = Addressables.InstantiateAsync(vfxRef, transform);
|
||
yield return op;
|
||
if (op.Result == null) continue;
|
||
var ps = op.Result.GetComponent<ParticleSystem>();
|
||
if (ps == null) { Addressables.ReleaseInstance(op.Result); continue; }
|
||
ps.gameObject.SetActive(false);
|
||
Enqueue(vfxRef, ps);
|
||
}
|
||
}
|
||
|
||
private bool TryDequeue(AssetReferenceGameObject key, out ParticleSystem ps)
|
||
{
|
||
ps = null;
|
||
return _pools.TryGetValue(key, out var q) && q.Count > 0 && (ps = q.Dequeue()) != null;
|
||
}
|
||
|
||
private void Enqueue(AssetReferenceGameObject key, ParticleSystem ps)
|
||
{
|
||
if (!_pools.ContainsKey(key)) _pools[key] = new Queue<ParticleSystem>();
|
||
_pools[key].Enqueue(ps);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. VFXCatalogSO — VFX 映射字典
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
[CreateAssetMenu(menuName = "VFX/VFXCatalog")]
|
||
public class VFXCatalogSO : ScriptableObject
|
||
{
|
||
[Header("命中特效映射")]
|
||
public VFXEntry[] hitEffects; // HitFxType → VFX Prefab
|
||
|
||
[Header("预热配置")]
|
||
public VFXWarmupEntry[] warmups;
|
||
|
||
private Dictionary<HitFxType, AssetReferenceGameObject> _map;
|
||
|
||
/// <summary>在 GameManager.OnGameplayStarted 中调用，建立快速查表字典。</summary>
|
||
public void Initialize()
|
||
{
|
||
_map = new Dictionary<HitFxType, AssetReferenceGameObject>();
|
||
foreach (var e in hitEffects) _map[e.type] = e.vfxRef;
|
||
}
|
||
|
||
/// <summary>根据 HitFxType 查找对应的 VFX Prefab 引用。</summary>
|
||
public bool TryGetHitFX(HitFxType type, out AssetReferenceGameObject vfxRef)
|
||
{
|
||
if (_map != null) return _map.TryGetValue(type, out vfxRef);
|
||
// 未初始化时回退至线性查找
|
||
foreach (var e in hitEffects)
|
||
{
|
||
if (e.type == type) { vfxRef = e.vfxRef; return true; }
|
||
}
|
||
vfxRef = default;
|
||
return false;
|
||
}
|
||
}
|
||
|
||
[Serializable]
|
||
public struct VFXEntry
|
||
{
|
||
public HitFxType type;
|
||
public AssetReferenceGameObject vfxRef;
|
||
}
|
||
|
||
[Serializable]
|
||
public struct VFXWarmupEntry
|
||
{
|
||
public AssetReferenceGameObject vfxRef;
|
||
[Min(1)] public int warmupCount; // 建议 3~5
|
||
}
|
||
}
|
||
```
|
||
|
||
**资产路径**：`Assets/ScriptableObjects/VFX/VFX_Catalog.asset`
|
||
|
||
---
|
||
|
||
## 8. HitFXSpawner
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// 监听 EVT_HitConfirmed 事件频道，从 VFXPool 取粒子播放命中特效。
|
||
/// 挂在 Persistent 场景 [VFXSystem] GameObject 上。
|
||
/// </summary>
|
||
public class HitFXSpawner : MonoBehaviour
|
||
{
|
||
[SerializeField] private HitConfirmedEventChannelSO _onHitConfirmed;
|
||
[SerializeField] private VFXCatalogSO _catalog;
|
||
|
||
private void Awake()
|
||
{
|
||
if (_catalog != null)
|
||
_catalog.Initialize();
|
||
}
|
||
|
||
private void OnEnable()
|
||
{
|
||
if (_onHitConfirmed != null)
|
||
_onHitConfirmed.OnEventRaised += HandleHit;
|
||
}
|
||
|
||
private void OnDisable()
|
||
{
|
||
if (_onHitConfirmed != null)
|
||
_onHitConfirmed.OnEventRaised -= HandleHit;
|
||
}
|
||
|
||
private void HandleHit(HitInfo info)
|
||
{
|
||
if (_catalog == null || VFXPool.Instance == null) return;
|
||
if (_catalog.TryGetHitFX(info.DamageInfo.FxType, out var vfxRef))
|
||
VFXPool.Instance.Play(vfxRef, info.HitPoint);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. HurtFlashController
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// 受击白闪效果，通过 Material Property Block 修改 Shader 参数。
|
||
/// 挂在玩家/敌人的 SpriteRenderer 所在 GameObject 上。
|
||
/// 不复制 Material（避免 GC），通过 MaterialPropertyBlock 实现。
|
||
/// 若上一次闪白未结束则重置计时器（支持连击打断重置）。
|
||
/// </summary>
|
||
public class HurtFlashController : MonoBehaviour
|
||
{
|
||
[SerializeField] private SpriteRenderer _renderer;
|
||
[SerializeField] private FeedbackConfigSO _config;
|
||
|
||
private static readonly int FlashColorID = Shader.PropertyToID("_FlashColor");
|
||
private static readonly int FlashAmountID = Shader.PropertyToID("_FlashAmount");
|
||
|
||
private MaterialPropertyBlock _block;
|
||
private Coroutine _flashCoroutine;
|
||
|
||
private void Awake()
|
||
{
|
||
if (_renderer == null)
|
||
_renderer = GetComponent<SpriteRenderer>();
|
||
_block = new MaterialPropertyBlock();
|
||
}
|
||
|
||
/// <summary>触发一次受击白闪。若上一次未结束则重置计时器。</summary>
|
||
public void Flash()
|
||
{
|
||
if (_flashCoroutine != null)
|
||
StopCoroutine(_flashCoroutine);
|
||
_flashCoroutine = StartCoroutine(FlashCoroutine());
|
||
}
|
||
|
||
private IEnumerator FlashCoroutine()
|
||
{
|
||
SetFlash(1f);
|
||
yield return new WaitForSeconds(_config != null ? _config.HurtFlashDuration : 0.12f);
|
||
SetFlash(0f);
|
||
_flashCoroutine = null;
|
||
}
|
||
|
||
private void SetFlash(float amount)
|
||
{
|
||
_renderer.GetPropertyBlock(_block);
|
||
if (_config != null)
|
||
_block.SetColor(FlashColorID, _config.HurtFlashColor);
|
||
_block.SetFloat(FlashAmountID, amount);
|
||
_renderer.SetPropertyBlock(_block);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Shader 要求**：`SpriteRenderer` 所用 Shader 需支持 `_FlashColor`（Color）和 `_FlashAmount`（float 0~1）属性（URP Sprite-Lit-Flash 变体）。
|
||
|
||
---
|
||
|
||
## 10. PaletteSwapSystem
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// 形态切换时替换玩家精灵调色板。
|
||
/// 通过 Texture2D 查找表（LUT）Shader 实现，不换 Sprite 资产。
|
||
/// 挂在玩家 SpriteRenderer 所在 GameObject 上。
|
||
/// 由 FormController 在切换形态时调用 ApplyPalette(FormType)。
|
||
/// </summary>
|
||
public class PaletteSwapSystem : MonoBehaviour
|
||
{
|
||
[SerializeField] private SpriteRenderer _renderer;
|
||
[SerializeField] private PaletteCatalogSO _catalog;
|
||
|
||
private static readonly int PaletteTexID = Shader.PropertyToID("_PaletteTex");
|
||
|
||
private MaterialPropertyBlock _block;
|
||
|
||
private void Awake()
|
||
{
|
||
if (_renderer == null)
|
||
_renderer = GetComponent<SpriteRenderer>();
|
||
_block = new MaterialPropertyBlock();
|
||
}
|
||
|
||
/// <summary>切换到指定形态的调色板。由 FormController.SwitchForm() 调用。</summary>
|
||
public void ApplyPalette(FormType form)
|
||
{
|
||
if (_catalog == null || _renderer == null) return;
|
||
if (!_catalog.TryGetPalette(form, out var tex)) return;
|
||
_renderer.GetPropertyBlock(_block);
|
||
_block.SetTexture(PaletteTexID, tex);
|
||
_renderer.SetPropertyBlock(_block);
|
||
}
|
||
}
|
||
|
||
[CreateAssetMenu(menuName = "VFX/PaletteCatalog")]
|
||
public class PaletteCatalogSO : ScriptableObject
|
||
{
|
||
[SerializeField] private PaletteEntry[] _entries;
|
||
|
||
public bool TryGetPalette(FormType form, out Texture2D tex)
|
||
{
|
||
if (_entries != null)
|
||
{
|
||
foreach (var e in _entries)
|
||
{
|
||
if (e.form == form) { tex = e.paletteLUT; return true; }
|
||
}
|
||
}
|
||
tex = null;
|
||
return false;
|
||
}
|
||
}
|
||
|
||
[Serializable]
|
||
public struct PaletteEntry
|
||
{
|
||
public FormType form;
|
||
public Texture2D paletteLUT; // 1D 查找表纹理（256×1 px）
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. PostProcessManager
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// 后处理 Volume 分区管理器，挂在 Persistent 场景 [PostProcess] GameObject 上。
|
||
/// 通过 Coroutine 平滑 blend Weight，监听游戏状态/Boss/死亡/胜利事件。
|
||
/// 注意：水下后处理由 UnderwaterPostProcessingController（World.Liquid）独立负责，此组件不处理。
|
||
/// </summary>
|
||
public class PostProcessManager : MonoBehaviour
|
||
{
|
||
[Header("Volume 引用（Persistent 场景内）")]
|
||
[SerializeField] private Volume _bossArenaVolume; // Priority=10
|
||
[SerializeField] private Volume _deathVolume; // Priority=20
|
||
[SerializeField] private Volume _victoryVolume; // Priority=10
|
||
|
||
[Header("事件频道")]
|
||
[SerializeField] private VoidEventChannelSO _onBossFightStarted;
|
||
[SerializeField] private VoidEventChannelSO _onBossFightEnded;
|
||
[SerializeField] private VoidEventChannelSO _onPlayerDied;
|
||
[SerializeField] private VoidEventChannelSO _onPlayerRespawned;
|
||
[SerializeField] private VoidEventChannelSO _onBossDefeated;
|
||
|
||
[SerializeField] private float _blendDuration = 0.4f;
|
||
|
||
private Volume[] _managedVolumes;
|
||
private Coroutine _blendCoroutine;
|
||
|
||
private void Awake()
|
||
{
|
||
_managedVolumes = new[] { _bossArenaVolume, _deathVolume, _victoryVolume };
|
||
}
|
||
|
||
private void OnEnable()
|
||
{
|
||
if (_onBossFightStarted != null) _onBossFightStarted.OnEventRaised += HandleBossFightStarted;
|
||
if (_onBossFightEnded != null) _onBossFightEnded.OnEventRaised += HandleBossFightEnded;
|
||
if (_onPlayerDied != null) _onPlayerDied.OnEventRaised += HandlePlayerDied;
|
||
if (_onPlayerRespawned != null) _onPlayerRespawned.OnEventRaised += HandlePlayerRespawned;
|
||
if (_onBossDefeated != null) _onBossDefeated.OnEventRaised += HandleBossDefeated;
|
||
}
|
||
|
||
private void OnDisable()
|
||
{
|
||
if (_onBossFightStarted != null) _onBossFightStarted.OnEventRaised -= HandleBossFightStarted;
|
||
if (_onBossFightEnded != null) _onBossFightEnded.OnEventRaised -= HandleBossFightEnded;
|
||
if (_onPlayerDied != null) _onPlayerDied.OnEventRaised -= HandlePlayerDied;
|
||
if (_onPlayerRespawned != null) _onPlayerRespawned.OnEventRaised -= HandlePlayerRespawned;
|
||
if (_onBossDefeated != null) _onBossDefeated.OnEventRaised -= HandleBossDefeated;
|
||
}
|
||
|
||
private void HandleBossFightStarted() => BlendTo(_bossArenaVolume);
|
||
private void HandleBossFightEnded() => ResetAll();
|
||
private void HandlePlayerDied() => BlendTo(_deathVolume);
|
||
private void HandlePlayerRespawned() => ResetAll();
|
||
private void HandleBossDefeated() => BlendTo(_victoryVolume);
|
||
|
||
private void BlendTo(Volume target)
|
||
{
|
||
if (_blendCoroutine != null) StopCoroutine(_blendCoroutine);
|
||
_blendCoroutine = StartCoroutine(BlendCoroutine(target, 1f));
|
||
}
|
||
|
||
private void ResetAll()
|
||
{
|
||
if (_blendCoroutine != null) StopCoroutine(_blendCoroutine);
|
||
_blendCoroutine = StartCoroutine(ResetAllCoroutine());
|
||
}
|
||
|
||
private IEnumerator BlendCoroutine(Volume target, float targetWeight)
|
||
{
|
||
float elapsed = 0f;
|
||
float[] startWeights = new float[_managedVolumes.Length];
|
||
for (int i = 0; i < _managedVolumes.Length; i++)
|
||
startWeights[i] = _managedVolumes[i] != null ? _managedVolumes[i].weight : 0f;
|
||
|
||
while (elapsed < _blendDuration)
|
||
{
|
||
elapsed += Time.unscaledDeltaTime;
|
||
float t = Mathf.Clamp01(elapsed / _blendDuration);
|
||
for (int i = 0; i < _managedVolumes.Length; i++)
|
||
{
|
||
if (_managedVolumes[i] == null) continue;
|
||
float dest = _managedVolumes[i] == target ? targetWeight : 0f;
|
||
_managedVolumes[i].weight = Mathf.Lerp(startWeights[i], dest, t);
|
||
}
|
||
yield return null;
|
||
}
|
||
}
|
||
|
||
private IEnumerator ResetAllCoroutine()
|
||
{
|
||
float elapsed = 0f;
|
||
float[] startWeights = new float[_managedVolumes.Length];
|
||
for (int i = 0; i < _managedVolumes.Length; i++)
|
||
startWeights[i] = _managedVolumes[i] != null ? _managedVolumes[i].weight : 0f;
|
||
|
||
while (elapsed < _blendDuration)
|
||
{
|
||
elapsed += Time.unscaledDeltaTime;
|
||
float t = Mathf.Clamp01(elapsed / _blendDuration);
|
||
for (int i = 0; i < _managedVolumes.Length; i++)
|
||
{
|
||
if (_managedVolumes[i] == null) continue;
|
||
_managedVolumes[i].weight = Mathf.Lerp(startWeights[i], 0f, t);
|
||
}
|
||
yield return null;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **⚠️ 实现说明**：
|
||
> - 使用 `Time.unscaledDeltaTime`，暂停期间 blend 不受 `Time.timeScale` 影响
|
||
> - 水下 Volume（`_underwaterVolume`）由 `World.Liquid` 模块中的 `UnderwaterPostProcessingController` 独立管理，不在此组件中
|
||
> - 不使用 DOTween；不使用 Lambda 订阅（Lambda 无法从事件中移除）
|
||
|
||
### Volume 结构与 Profile 参数
|
||
|
||
```
|
||
Persistent 场景 [PostProcess]:
|
||
├── Volume_Default Priority=0 Weight=1.0（始终生效基础 Profile）
|
||
├── Volume_Underwater Priority=10 Weight=0（由 UnderwaterPostProcessingController 管理）
|
||
├── Volume_BossArena Priority=10 Weight=0（Boss 战开始时 blend 到 1.0）
|
||
├── Volume_Death Priority=20 Weight=0（玩家死亡时 blend 到 1.0）
|
||
└── Volume_Victory Priority=10 Weight=0（Boss 击败时 blend 到 1.0）
|
||
```
|
||
|
||
---
|
||
|
||
## 12. RegionLightController
|
||
|
||
```csharp
|
||
namespace BaseGames.VFX
|
||
{
|
||
/// <summary>
|
||
/// 区域进出时平滑切换 Global Light 2D 颜色和强度。
|
||
/// 挂在 Persistent 场景 [Lighting] GameObject 上，监听 OnRegionEntered 事件频道。
|
||
/// 使用 Coroutine 实现平滑过渡，不依赖 DOTween。
|
||
/// </summary>
|
||
public class RegionLightController : MonoBehaviour
|
||
{
|
||
[SerializeField] private Light2D _globalLight;
|
||
[SerializeField] private RegionLightCatalogSO _catalog;
|
||
[SerializeField] private StringEventChannelSO _onRegionEntered;
|
||
[SerializeField] private float _transitionDuration = 1.5f;
|
||
|
||
private Coroutine _colorCoroutine;
|
||
private Coroutine _intensityCoroutine;
|
||
|
||
private void OnEnable()
|
||
{
|
||
if (_onRegionEntered != null)
|
||
_onRegionEntered.OnEventRaised += OnRegionEntered;
|
||
}
|
||
|
||
private void OnDisable()
|
||
{
|
||
if (_onRegionEntered != null)
|
||
_onRegionEntered.OnEventRaised -= OnRegionEntered;
|
||
}
|
||
|
||
private void OnRegionEntered(string regionId)
|
||
{
|
||
if (_catalog == null || _globalLight == null) return;
|
||
if (!_catalog.TryGet(regionId, out var config)) return;
|
||
|
||
if (_colorCoroutine != null) StopCoroutine(_colorCoroutine);
|
||
if (_intensityCoroutine != null) StopCoroutine(_intensityCoroutine);
|
||
|
||
_colorCoroutine = StartCoroutine(TweenColor(_globalLight.color, config.Color, _transitionDuration));
|
||
_intensityCoroutine = StartCoroutine(TweenIntensity(_globalLight.intensity, config.Intensity, _transitionDuration));
|
||
}
|
||
|
||
private IEnumerator TweenColor(Color from, Color to, float duration)
|
||
{
|
||
float elapsed = 0f;
|
||
while (elapsed < duration)
|
||
{
|
||
elapsed += Time.deltaTime;
|
||
_globalLight.color = Color.Lerp(from, to, Mathf.Clamp01(elapsed / duration));
|
||
yield return null;
|
||
}
|
||
_globalLight.color = to;
|
||
}
|
||
|
||
private IEnumerator TweenIntensity(float from, float to, float duration)
|
||
{
|
||
float elapsed = 0f;
|
||
while (elapsed < duration)
|
||
{
|
||
elapsed += Time.deltaTime;
|
||
_globalLight.intensity = Mathf.Lerp(from, to, Mathf.Clamp01(elapsed / duration));
|
||
yield return null;
|
||
}
|
||
_globalLight.intensity = to;
|
||
}
|
||
}
|
||
|
||
[CreateAssetMenu(menuName = "VFX/RegionLightCatalog")]
|
||
public class RegionLightCatalogSO : ScriptableObject
|
||
{
|
||
[Serializable]
|
||
public struct RegionLightConfig
|
||
{
|
||
public string regionId;
|
||
public Color Color;
|
||
[Range(0f, 1f)] public float Intensity;
|
||
}
|
||
|
||
[SerializeField] private RegionLightConfig[] _entries;
|
||
|
||
public bool TryGet(string regionId, out RegionLightConfig cfg)
|
||
{
|
||
if (_entries != null)
|
||
{
|
||
foreach (var e in _entries)
|
||
{
|
||
if (e.regionId == regionId) { cfg = e; return true; }
|
||
}
|
||
}
|
||
cfg = default;
|
||
return false;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### URP 2D 光照层（Light Layer）规范
|
||
|
||
| Light Layer | 名称 | 用途 |
|
||
|------------|------|------|
|
||
| 0 | `Default` | 全局环境光（所有对象默认受光）|
|
||
| 1 | `Environment` | 蜡烛、火把、发光水晶等环境光源 |
|
||
| 2 | `PlayerLight` | 玩家携带光源（如灵力发光）|
|
||
| 3 | `EnemyLight` | Boss 爆炸闪光、特殊敌人发光体 |
|
||
| 4 | `FXOnly` | 仅特效 ParticleSystem 受此层光照 |
|
||
| 5–7 | _预留_ | 未来扩展 |
|
||
|
||
**规则**：地形 Tilemap 仅勾选 Layer 0；粒子特效勾选 Layer 0 + 4；敌人勾选 Layer 0 + 3。
|
||
|
||
### 区域 Global Light 2D 参数速查
|
||
|
||
| 区域 | 颜色 | 强度 |
|
||
|------|------|------|
|
||
| Forest（扎根森林）| `#C8E8D0`（淡绿）| 0.8 |
|
||
| Cave（腐蚀洞穴）| `#1A0A2E`（深紫）| 0.2 |
|
||
| Ruins（坍塌废墟）| `#3D3028`（暖褐）| 0.5 |
|
||
| Abyss（深渊裂隙）| `#000820`（极暗蓝）| 0.1 |
|
||
| Core（核心熔炉）| `#4A1800`（暗红橙）| 0.6 |
|
||
|
||
---
|
||
|
||
## 13. 事件频道
|
||
|
||
| 频道 SO | Payload | 发布者 | 订阅者 |
|
||
|--------|---------|--------|--------|
|
||
| `EVT_HitConfirmed` | `HitInfo` | `HurtBox.ReceiveDamage` | `HitFXSpawner`、`AudioManager`、`PlayerFeedback`（受击方） |
|
||
| `EVT_RegionEntered` | `string regionId` | `RegionTrigger` | `RegionLightController`、`AudioManager` |
|
||
|
||
> 注：`HurtFlashController.Flash()` 和 `CameraStateController.TriggerImpulse()` 均由 `IFeedbackPlayer`（`PlayerFeedback`）通过直接调用触发，不使用独立事件频道。
|
||
|
||
---
|
||
|
||
## 14. VFX 分类与生命周期策略
|
||
|
||
| 分类 | 示例 | 生命周期策略 | 说明 |
|
||
|------|------|------------|------|
|
||
| **命中特效** | 刀击火花、魔法爆炸 | 对象池（VFXPool）| 频繁触发，必须池化 |
|
||
| **状态特效** | 持续燃烧、中毒气泡 | Prefab 跟随目标 Transform | 随目标销毁，不需要池 |
|
||
| **环境特效** | 灰尘、落叶、水泡 | 场景内预放置，常驻播放 | 不产生运行时 Instantiate |
|
||
| **能力特效** | 冲刺残影、双跳光圈 | 对象池（VFXPool）| 中等频率，建议池化 |
|
||
| **死亡特效** | 敌人爆裂、Boss 死亡烟花 | Addressables.InstantiateAsync | 低频但复杂，不值得池化 |
|
||
| **UI 特效** | 升级闪光、货币飞入 | Timeline Signal / MMF_Player | 在 UI Canvas 子层用 UI Particle |
|
||
|
||
**原则**：帧内可能多次触发（命中、脚步等）→ 池化；每关卡最多触发数次 → Addressables 按需加载。
|
||
|
||
### HitFxType 枚举值速查
|
||
|
||
| 枚举值 | 特效 | 建议粒子数 |
|
||
|-------|------|----------|
|
||
| `Spark` | 金属碰撞火花 | ≤ 8 |
|
||
| `Blood` | 敌人受击血迹 | ≤ 12 |
|
||
| `Magic` | 法术命中光环 | ≤ 15 |
|
||
| `Crit` | 暴击大爆炸 | ≤ 20 |
|
||
| `Void` | 深渊伤害涟漪 | ≤ 10 |
|
||
| `Heal` | 治疗绿光粒子 | ≤ 8 |
|
||
| `Parry` | 弹反白光爆散 | ≤ 20 |
|
||
|
||
---
|
||
|
||
## 15. VFX 性能约束
|
||
|
||
| 约束项 | 限制 | 备注 |
|
||
|--------|------|------|
|
||
| 同屏活跃粒子总数 | ≤ 500 | 超过时 GPU 帧时上升 |
|
||
| 单次命中特效粒子数 | ≤ 20 | HitFxType 表格已约束 |
|
||
| 同屏 Light 2D 数量 | ≤ 16 | 超过时触发 URP 2D 光照降级 |
|
||
| Shadow Caster 2D 数量 | ≤ 32 | Composite 模式下 1 Tilemap = 1 |
|
||
| 新增 VFX Prefab | 必须通过 VFXPool 统一管理 | PR Review 清单检查项 |
|
||
| `Material.SetXxx()` 直接调用 | 禁止 | 一律用 MaterialPropertyBlock |
|
||
| `Instantiate(ParticleSystem)` 运行时调用 | 禁止 | 一律从 VFXPool.Play() 取 |
|
||
|
||
---
|
||
|
||
## 16. MMF_Player 命名规范
|
||
|
||
| 格式 | 示例 |
|
||
|------|------|
|
||
| `MMF_{Owner}_{EventName}` | `MMF_Player_OnTakeHit`、`MMF_Enemy_OnDeath`、`MMF_Boss_OnPhaseChange` |
|
||
|
||
**常用 Feedback 类型速查**：
|
||
|
||
| Feel Feedback | 用途 | 关键参数 |
|
||
|--------------|------|---------|
|
||
| `MMF_Flash` | Sprite 受击白闪 | `FlashColor`, `Duration` |
|
||
| `MMF_FreezeFrame` | 命中冻帧 | `FreezeDuration`（来自 FeedbackConfigSO） |
|
||
| `MMF_TimeScale` | 子弹时间 | `TimeScale`, `Duration` |
|
||
| `MMF_CinemachineImpulse` | 镜头震动 | `ImpulseSource`, `Velocity` |
|
||
| `MMF_Particles` | 命中粒子 | `ParticleSystem` 引用 |
|
||
| `MMF_AudioSource` | 音效 | `AudioClip`, `PitchVariance` |
|
||
| `MMF_TextMeshPro` | 伤害数字弹出 | 浮动文字动画 |
|