34 KiB
34 KiB
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 · 07_FeedbackSystem
目录
- 模块职责
- IFeedbackPlayer 接口
- PlayerFeedback
- EnemyFeedback
- FeedbackConfigSO
- VFXPool — 粒子对象池
- VFXCatalogSO — VFX 映射字典
- HitFXSpawner
- HurtFlashController
- PaletteSwapSystem
- PostProcessManager
- RegionLightController
- 事件频道
- VFX 分类与生命周期策略
- VFX 性能约束
- 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 接口
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
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
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
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 — 粒子对象池
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 映射字典
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
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
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
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
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
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 |
伤害数字弹出 | 浮动文字动画 |