# 08 · 世界模块

> **命名空间** `BaseGames.World`  
> **程序集** `BaseGames.World`  
> **路径** `Assets/Scripts/World/`  
> **依赖** `BaseGames.Core`、`BaseGames.Core.Events`、`BaseGames.Core.Save`  
> （通过 `IRestoreOnSave`（定义于 Core）与玩家层解耦，无需直接引用 `BaseGames.Player`）

---

## 目录

1. [场景结构规范（总览）](#1-场景结构规范)
2. [RoomTransition](#2-roomtransition)
3. [SavePoint](#3-savepoint)
4. [HazardZone](#4-hazardzone)
5. [Collectible](#5-collectible)
6. [AbilityUnlock](#6-abilityunlock)
7. [IInteractable 接口](#7-iinteractable-接口)
8. [InteractableDetector](#8-interactabledetector)
9. [WorldStateRegistry](#9-worldstateregistry)
10. [DestructibleTile](#10-destructibletile)
11. [MovingPlatform](#11-movingplatform)
12. [DirectionalDestructible — 单向可破坏墙](#12-directionaldestructible--单向可破坏墙)
13. [DirectionalInteractable — 单向触发机关](#13-directionalinteractable--单向触发机关)
14. [CrumblePlatform — 碎裂平台](#14-crumbleplatform--碎裂平台)
15. [SkillInteractable — 技能专属交互物](#15-skillinteractable--技能专属交互物)
16. [世界事件频道清单](#16-世界事件频道清单)

---

## 1. 场景结构规范

**场景命名**（见 [01_ProjectStructure.md](./01_ProjectStructure.md) §8）。

**房间场景标准层级**（详见 Architecture README）。  
重要约束：

- 每个房间场景必须包含 `RoomController` 组件（挂在 `[RoomRoot]` GameObject 上）
- 必须有至少一个 `RoomTransition`（出入口）
- 玩家出生点：`PlayerSpawnPoint` 组件，由 `SceneLoadRequest.EntryTransitionId` 匹配

---

## 2. RoomTransition

```csharp
// 路径: Assets/Scripts/World/RoomTransition.cs
// 挂在出入口 Trigger Collider2D 上
[RequireComponent(typeof(Collider2D))]
public class RoomTransition : MonoBehaviour
{
    [Header("Config")]
    [SerializeField] private string  _transitionId;         // 唯一 ID（目标出口用于匹配出生点）
    [SerializeField] private string  _targetSceneAddress;   // 目标场景 Addressable key（AddressKeys 常量）
    [SerializeField] private string  _targetTransitionId;   // 目标场景中对应出口的 ID
    [SerializeField] private bool    _autoTrigger = true;   // true = 进入触发器自动触发；false = 需交互
    [SerializeField] private bool    _requiresKeyItem;      // 是否需要持有鑰匙物品
    [SerializeField] private string  _requiredItemId;       // 鑰匙物品 ID

    [Header("Event Channel")]
    [SerializeField] private SceneLoadRequestEventChannelSO _onSceneLoadRequest;

    [Header("世界状态")]
    [SerializeField] private WorldStateRegistry _worldState;  // 持有物品检查

    // 玩家进入触发器
    private void OnTriggerEnter2D(Collider2D other)
    {
        if (!other.CompareTag("Player")) return;
        if (_requiresKeyItem && !HasItem(_requiredItemId)) return;

        _onSceneLoadRequest.Raise(new SceneLoadRequest
        {
            SceneName        = _targetSceneName,
            EntryTransitionId = _targetTransitionId,
            ShowLoadingScreen = false,
            IsRespawn        = false
        });
    }

    private bool HasItem(string itemId)
    {
        if (string.IsNullOrEmpty(itemId)) return true;
        if (_worldState == null) return false;         // 未配置则拦截（警告日志）
        return _worldState.IsCollected(itemId);
    }

    // Editor：在 Scene View 显示箭头 Gizmo
    private void OnDrawGizmos();
}

// 玩家出生点，与 RoomTransition.transitionId 对应
public class PlayerSpawnPoint : MonoBehaviour
{
    public string TransitionId;
    public Vector2 SpawnPosition => transform.position;
    public int FacingDirection = 1;  // +1 右, -1 左

    private void OnDrawGizmos() { /* 绿色标记 */ }
}
```

---

## 3. SavePoint

```csharp
// 路径: Assets/Scripts/World/SavePoint.cs
// 实现 IInteractable + ISaveable，玩家交互时触发存档
// 架构决策：通过 IRestoreOnSave（定义于 BaseGames.Core）调用玩家回血/灵泉，
//           避免 World 层反向依赖 BaseGames.Player，World.asmdef 无需引用 Player 程序集。
public class SavePoint : MonoBehaviour, IInteractable, ISaveable
{
    [Header("Config")]
    [SerializeField] private string  _savePointId;
    [SerializeField] private bool    _restoreSpring = true;

    [Header("Event Channels")]
    [SerializeField] private StringEventChannelSO _onSavePointActivated;
    [SerializeField] private VoidEventChannelSO   _onFastTravelOpen;

    private bool _isActivated;

    // IInteractable（⚠️ 参数为 Transform，与 14_NarrativeModule §1 / 07 §7 对齐）
    public bool   CanInteract    => true;
    public string InteractPrompt => _isActivated ? "休息" : "激活";
    public void Interact(Transform player)
    {
        _isActivated = true;
        // 1. 通过 IRestoreOnSave 恢复玩家（World 不感知具体 Player 类型）
        var restorer = player.GetComponentInChildren<IRestoreOnSave>();
        if (restorer != null)
        {
            restorer.FullRestore();
            if (_restoreSpring) restorer.RestoreSpring();
        }
        // 2. 广播存档点激活（GameManager 响应并调用 SaveManager.SaveAsync）
        _onSavePointActivated?.Raise(_savePointId);
        // 3. 若该场景已有多个存档点激活，打开快速旅行 UI
        // 4. 播放激活动画 / 特效
    }

    // ISaveable 存档集成
    public bool IsActivated => _isActivated;
    public void SetActivated(bool val) => _isActivated = val;
}
```

> **IRestoreOnSave 接口**（`Assets/Scripts/Core/IRestoreOnSave.cs`，命名空间 `BaseGames.Core`）  
> `PlayerStats` 显式实现：`FullRestore()` → `FullHeal()`，`RestoreSpring()` → `RestoreSpringCharges()`。  
> 同一接口可扩展至其他可被存档点恢复的对象（伙伴、坐骑等），无需修改 SavePoint 本身。

---

## 4. HazardZone

```csharp
// 路径: Assets/Scripts/World/HazardZone.cs
// 即死区域（深坑、岩浆等）
[RequireComponent(typeof(Collider2D))]
public class HazardZone : MonoBehaviour
{
    public enum RespawnType { AtLastSavePoint, AtRoomEntry }

    [SerializeField] private bool         _isInstantKill  = true;
    [SerializeField] private int          _damage         = 9999;
    [SerializeField] private RespawnType  _respawnType    = RespawnType.AtLastSavePoint;

    private void OnTriggerEnter2D(Collider2D other)
    {
        if (!other.CompareTag("Player")) return;

        var stats = other.GetComponentInParent<PlayerStats>();
        if (stats == null) return;

        if (_isInstantKill)
            stats.TakeDamage(stats.MaxHP * 2);  // 确保即死
        else
            stats.TakeDamage(_damage);
    }
}
```

---

## 5. Collectible

```csharp
// 路径: Assets/Scripts/World/Collectible.cs
// Geo 货币 / 物品掉落
public class Collectible : MonoBehaviour
{
    [Header("Config")]
    [SerializeField] private CollectibleType _type;
    [SerializeField] private int    _geoAmount;       // type = Geo 时
    [SerializeField] private string _itemId;           // type = Item 时
    [SerializeField] private bool   _isPersistent;    // false = 敌人掉落（不存档）; true = 固定位置（存档）

    [Header("Physics")]
    [SerializeField] private float _bounceForce = 5f;

    [Header("Event Channel")]
    [SerializeField] private StringEventChannelSO _onCollectiblePickup;

    private string _collectibleId;  // 用于存档（持久化 Collectible 专用）

    private void OnTriggerEnter2D(Collider2D other)
    {
        if (!other.CompareTag("Player")) return;

        var player = other.GetComponentInParent<PlayerController>();
        if (player == null) return;

        switch (_type)
        {
            case CollectibleType.Geo:
                player.Stats.AddGeo(_geoAmount);
                break;
            case CollectibleType.Item:
                // 通知 Inventory / QuestManager
                _onCollectiblePickup.Raise(_itemId);
                break;
        }

        if (_isPersistent)
            _onCollectiblePickup.Raise(_collectibleId);  // 存档标记

        Despawn();
    }

    private void Despawn();   // 归还对象池

    // ―― 运行时配置（由 CollectibleSpawner 在实例化后调用）――――――――――――――――
    /// <summary>将此 Collectible 配置为 Geo 掉落。</summary>
    public void SetGeo(int amount);

    /// <summary>将此 Collectible 配置为道具掉落。</summary>
    public void SetItem(string itemId);
}

public enum CollectibleType { Geo, Item, HPOrb }
```

---

## 5b. CollectibleSpawner

```csharp
// 路径: Assets/Scripts/World/CollectibleSpawner.cs + CollectibleSpawnerConfig.cs
// 封装 Collectible Prefab 实例化逻辑，供 LootResolver 等静态调用。
// CollectibleSpawnerConfig 挂在 Persistent 场景 [World] GameObject 上持有 Prefab 引用，
// Awake 调用 CollectibleSpawner.Register(this) 注入静态配置。
public static class CollectibleSpawner
{
    internal static void Register(CollectibleSpawnerConfig config);
    public static void SpawnGeo(Vector2 position, int amount);   // 实例化 GeoPrefab 并调用 SetGeo(amount)
    public static void SpawnItem(Vector2 position, string itemId); // 实例化 ItemPrefab 并调用 SetItem(itemId)
}

public class CollectibleSpawnerConfig : MonoBehaviour
{
    [SerializeField] internal GameObject GeoPrefab;
    [SerializeField] internal GameObject ItemPrefab;
    private void Awake() => CollectibleSpawner.Register(this);
}
```

---

## 6. AbilityUnlock

```csharp
// 路径: Assets/Scripts/World/AbilityUnlock.cs
// 世界中固定位置的能力解锁物（获取新技能）
public class AbilityUnlock : MonoBehaviour, IInteractable
{
    [SerializeField] private AbilityType    _abilityToUnlock;
    [SerializeField] private string         _unlockId;          // 存档用

    [Header("Event Channels")]
    [SerializeField] private StringEventChannelSO _onCollectiblePickup;  // 通知存档已拾取

    private bool _isCollected = false;

    public bool   CanInteract    => !_isCollected;
    public string InteractPrompt => "获得能力";

    public void Interact(Transform player)
    {
        if (_isCollected) return;
        _isCollected = true;
        // ⚠️ PlayerController 无 Instance；通过 player 参数获取
        player.GetComponent<PlayerController>()?.Stats.UnlockAbility(_abilityToUnlock);
        _onCollectiblePickup.Raise(_unlockId);
        // 触发解锁演出（Cutscene / UI 提示）
        gameObject.SetActive(false);
    }

    public void SetCollected(bool val)
    {
        _isCollected = val;
        if (val) gameObject.SetActive(false);
    }
}
```

---

## 7. IInteractable 接口

```csharp
// 路径: Assets/Scripts/World/IInteractable.cs
// ⚠️ 与 14_NarrativeModule §1 对齐（权威定义）：Transform 参数 + 5 成员
namespace BaseGames.World
{
    public interface IInteractable
    {
        bool   CanInteract    { get; }                    // 当前是否可交互
        string InteractPrompt { get; }                    // 显示在交互提示 UI 上的文字
        void   Interact(Transform player);                // 传入玩家 Transform；需要 PlayerController 时通过 player.GetComponent<PlayerController>() 获取（PlayerController 无 Instance）
        void   OnPlayerEnterRange(Transform player);      // 进入检测范围
        void   OnPlayerExitRange();                       // 离开检测范围
    }
}
```

---

## 8. InteractableDetector

```csharp
// 路径: Assets/Scripts/World/InteractableDetector.cs
// 挂在玩家上，检测周围可交互物并驱动交互 UI
public class InteractableDetector : MonoBehaviour
{
    [SerializeField] private float  _detectRadius = 1.5f;
    [SerializeField] private LayerMask _interactableLayer;
    [SerializeField] private InputReaderSO _inputReader;
    [SerializeField] private StringEventChannelSO _onShowInteractPrompt;  // 发布：显示交互提示
    [SerializeField] private VoidEventChannelSO   _onHideInteractPrompt;  // 发布：隐藏交互提示

    private IInteractable _nearest;
    private IInteractable _previousNearest;

    private void OnEnable()  => _inputReader.InteractEvent += TryInteract;
    private void OnDisable() => _inputReader.InteractEvent -= TryInteract;

    private void Update()
    {
        // OverlapCircle → 找最近 IInteractable
        var hits = Physics2D.OverlapCircleAll(transform.position, _detectRadius, _interactableLayer);
        _nearest = FindNearest(hits);
        if (_nearest != _previousNearest)
        {
            if (_previousNearest != null) { _previousNearest.OnPlayerExitRange(); _onHideInteractPrompt.Raise(); }
            if (_nearest        != null)  { _nearest.OnPlayerEnterRange(transform); _onShowInteractPrompt.Raise(_nearest.InteractPrompt); }
            _previousNearest = _nearest;
        }
    }

    private void TryInteract()
    {
        _nearest?.Interact(transform);  // 传入玩家自身 Transform；IInteractable 内部通过 player.GetComponent<PlayerController>() 获取组件（PlayerController 无 Instance）
    }
}
```

---

## 9. WorldStateRegistry

> **⚠️ 与 `14_NarrativeModule §8` 统一**：`WorldStateRegistry` 已改为 **ScriptableObject**（`CreateAssetMenu`），
> 通过 `[SerializeField]` 注入，不再使用静态 `Instance`。`HasFlag` / `SetFlag(key)` 接口与 Architecture 14 §8 保持一致。

```csharp
// 路径: Assets/Scripts/World/Narrative/WorldStateRegistry.cs
// 管理世界持久化状态（已收集物、已激活存档点、已开门、已销毁对象、通用标志）
// ScriptableObject 形式，各组件通过 [SerializeField] 注入，零耦合；与 14_NarrativeModule §8 统一
namespace BaseGames.World
{
    [CreateAssetMenu(menuName = "World/WorldStateRegistry")]
    public class WorldStateRegistry : ScriptableObject
    {
        private HashSet<string> _collectedIds        = new();
        private HashSet<string> _activatedSavePoints = new();
        private HashSet<string> _openedDoors         = new();
        private HashSet<string> _destroyedObjects    = new();

        public bool IsCollected(string id)            => _collectedIds.Contains(id);
        public void MarkCollected(string id)          => _collectedIds.Add(id);

        public bool IsSavePointActivated(string id)   => _activatedSavePoints.Contains(id);
        public void MarkSavePointActivated(string id) => _activatedSavePoints.Add(id);

        public bool IsDestroyed(string id)            => _destroyedObjects.Contains(id);
        public void MarkDestroyed(string id)          => _destroyedObjects.Add(id);

        public bool IsDoorOpened(string id)           => _openedDoors.Contains(id);
        public void MarkDoorOpened(string id)         => _openedDoors.Add(id);

        // 通用世界状态标记（过场记录、剧情事件等）
        // ⚠️ 接口与 14_NarrativeModule §8 统一：HasFlag（非 IsFlagSet）；SetFlag(key) 单参数添加
        private HashSet<string> _flags = new();
        public bool HasFlag(string key) => _flags.Contains(key);
        public void SetFlag(string key) => _flags.Add(key);

        // SaveManager 集成（非 ISaveable，由 SaveManager 在 SaveAsync/LoadAsync 中直接调用）
        public void LoadFromSave(WorldSaveData data);
        public HashSet<string> GetAllFlags();
    }
}
```

> **SaveManager 集成**：`WorldStateRegistry` 不实现 `ISaveable` 接口（ScriptableObject，非 MonoBehaviour）。
> `SaveManager` 在保存/加载时直接调用：
> ```csharp
> // SaveManager.CollectAllData() 内：
> saveData.World = WorldStateRegistry.Instance.GetSaveData();  // 通过 SO 引用而非静态 Instance
>
> // SaveManager.ApplyLoadedData() 内：
> WorldStateRegistry.Instance.LoadFromSave(saveData.World);
> ```
> `WorldStateRegistry` SO 资产路径：`Assets/Data/World/WorldStateRegistry.asset`。

---

## 10. DestructibleTile

```csharp
// 路径: Assets/Scripts/World/DestructibleTile.cs
// 可被攻击破坏的地形块（影响导航网格）
public class DestructibleTile : MonoBehaviour, IDamageable
{
    [SerializeField] private int   _maxHP = 1;
    [SerializeField] private string _destructedId;   // 存档唯一 ID

    private bool _isDestroyed = false;

    // IDamageable
    public bool IsInvincible => _isDestroyed;
    public int  Defense      => 0;
    public void TakeDamage(DamageInfo info)
    {
        if (_isDestroyed) return;
        if (!CheckDestroyCondition(info)) return;  // 子类可覆盖（DirectionalDestructible 方向校验）
        _isDestroyed = true;
        // 禁用 Renderer + 碰撞体
        // 通知 PathBerserker2d 重新烘焙局部导航网格
        // 记录到 WorldStateRegistry
    }

    // 子类覆盖以附加销毁前提条件（默认：无条件销毁）
    protected virtual bool CheckDestroyCondition(DamageInfo info) => true;
}
```

---

## 11. MovingPlatform

```csharp
// 路径: Assets/Scripts/World/MovingPlatform.cs
// 动态移动平台：Kinematic Rigidbody2D，乘客自动跟随（Passenger Pattern）
[RequireComponent(typeof(Rigidbody2D))]
public class MovingPlatform : MonoBehaviour
{
    public enum MoveType { LinearAB, WayPoints, TriggeredLinear }

    [Header("移动配置")]
    [SerializeField] private MoveType  _moveType = MoveType.LinearAB;
    [SerializeField] private Transform[] _wayPoints;      // LinearAB 仅用 [0][1]
    [SerializeField] private float       _speed = 3f;     // u/s
    [SerializeField] private float       _waitAtEndpoint = 0.5f; // 端点停留秒数

    [Header("TriggeredLinear 模式")]
    [SerializeField] private VoidEventChannelSO _activationChannel;  // 接收信号后单程运动

    // 乘客检测：顶面上方 0.05f 的 IsTrigger BoxCollider2D，检测到 Player/Enemy 层
    [Header("乘客检测")]
    [SerializeField] private BoxCollider2D _passengerSensor;  // Trigger，仅用于检测

    private Rigidbody2D _rb;
    private List<Transform> _passengers = new();
    private int    _waypointIndex;
    private bool   _movingForward = true;
    private bool   _triggered;

    private void Awake() => _rb = GetComponent<Rigidbody2D>();

    private void FixedUpdate()
    {
        if (_moveType == MoveType.TriggeredLinear && !_triggered) return;
        MoveTowardsNextWaypoint();
    }

    private void MoveTowardsNextWaypoint()
    {
        var target = _wayPoints[_waypointIndex].position;
        var next   = Vector2.MoveTowards(_rb.position, target, _speed * Time.fixedDeltaTime);
        _rb.MovePosition(next);

        if (Vector2.Distance(_rb.position, target) < 0.02f)
            StartCoroutine(WaitAndAdvance());
    }

    private IEnumerator WaitAndAdvance()
    {
        yield return new WaitForSeconds(_waitAtEndpoint);
        AdvanceWaypoint();
    }

    private void AdvanceWaypoint()
    {
        // LinearAB: 往返; WayPoints: 环形; TriggeredLinear: 到达终点后停止
        if (_moveType == MoveType.TriggeredLinear)
        {
            _waypointIndex = Mathf.Min(_waypointIndex + 1, _wayPoints.Length - 1);
            if (_waypointIndex == _wayPoints.Length - 1) _triggered = false;
            return;
        }
        if (_moveType == MoveType.LinearAB)
        {
            _movingForward = !_movingForward;
            _waypointIndex = _movingForward ? 1 : 0;
        }
        else  // WayPoints
        {
            _waypointIndex = (_waypointIndex + 1) % _wayPoints.Length;
        }
    }

    // ── 乘客跟随（Passenger Pattern）─────────────────────────────────
    private void OnTriggerEnter2D(Collider2D other)
    {
        if ((1 << other.gameObject.layer & LayerMask.GetMask("Player", "Enemy")) == 0) return;
        other.transform.SetParent(transform);
        _passengers.Add(other.transform);
    }

    private void OnTriggerExit2D(Collider2D other)
    {
        if (!_passengers.Contains(other.transform)) return;
        other.transform.SetParent(null);
        _passengers.Remove(other.transform);
        // 继承平台当前速度（仅玩家）
        if (other.CompareTag("Player"))
            other.GetComponentInParent<Rigidbody2D>()?.AddForce(
                _rb.velocity, ForceMode2D.Impulse);
    }

    private void OnEnable()
    {
        if (_activationChannel != null)
            _activationChannel.OnEventRaised += OnTriggered;
    }
    private void OnDisable()
    {
        if (_activationChannel != null)
            _activationChannel.OnEventRaised -= OnTriggered;
    }
    private void OnTriggered() => _triggered = true;
}
```

**MoveType 说明**：

| 类型 | 行为 |
|------|------|
| `LinearAB` | `_wayPoints[0]` ↔ `[1]` 往返循环 |
| `WayPoints` | 按 `_wayPoints[]` 顺序环形循环 |
| `TriggeredLinear` | 监听 `_activationChannel`，收到信号后单程 `[0]→[n-1]`，到达后停止 |

> **NavSurface 联动**：每个移动平台挂载独立 `LocalNavSurface`（局部坐标系），附着其上的敌人 NavAgent 使用该 LocalNavSurface 寻路；参见 Guides/PathBerserker2d_Technical_Evaluation.md §5。

---

## 12. DirectionalDestructible — 单向可破坏墙

继承 `DestructibleTile`，在其基础上增加**攻击方向校验**：

```csharp
// 路径: Assets/Scripts/World/DirectionalDestructible.cs
public class DirectionalDestructible : DestructibleTile
{
    public enum AttackSide { Left, Right, Top, Bottom, Any }

    [SerializeField] private AttackSide _validAttackSide = AttackSide.Any;

    protected override bool CheckDestroyCondition(DamageInfo info)
    {
        if (_validAttackSide == AttackSide.Any)
            return base.CheckDestroyCondition(info);

        // 判断攻击来源方向（info.SourcePosition 由 HitBox 传入）
        var dir = (info.SourcePosition - (Vector2)transform.position).normalized;
        bool valid = _validAttackSide switch
        {
            AttackSide.Left   => dir.x <  -0.5f,
            AttackSide.Right  => dir.x >   0.5f,
            AttackSide.Top    => dir.y >   0.5f,
            AttackSide.Bottom => dir.y <  -0.5f,
            _                 => true
        };
        return valid && base.CheckDestroyCondition(info);
    }

#if UNITY_EDITOR
    private void OnDrawGizmos()
    {
        // 有效攻击方向：橙色箭头；无效方向：灰色叉号
        var arrow = _validAttackSide switch
        {
            AttackSide.Left   => Vector2.left,
            AttackSide.Right  => Vector2.right,
            AttackSide.Top    => Vector2.up,
            AttackSide.Bottom => Vector2.down,
            _                 => Vector2.zero
        };
        if (arrow == Vector2.zero) return;
        Gizmos.color = new Color(1f, 0.5f, 0f, 0.9f);
        var origin = (Vector2)transform.position;
        Gizmos.DrawLine(origin, origin + arrow * 0.8f);
    }
#endif
}
```

| 典型场景 | 配置 |
|---------|------|
| 地板薄板：只能从下方砸穿 | `_validAttackSide = Bottom` |
| 密室封墙：仅能从房间内打开 | `_validAttackSide = Right`（依据朝向） |
| 普通脆弱墙 | 基类 `DestructibleTile`（`AnyAttack`）即可，不需此子类 |

---

## 13. DirectionalInteractable — 单向触发机关

```csharp
// 路径: Assets/Scripts/World/DirectionalInteractable.cs
// 可从特定方向触发的单向机关（零耦合：通过 SO 事件频道连接受体）
[RequireComponent(typeof(Collider2D))]
public class DirectionalInteractable : MonoBehaviour, IInteractable
{
    public enum TriggerSide      { Left, Right, Top, Any }
    public enum TriggerCondition { PlayerAttack, PlayerBody, InteractKey }

    [Header("触发条件")]
    [SerializeField] private TriggerSide      _triggerSide      = TriggerSide.Any;
    [SerializeField] private TriggerCondition _triggerCondition = TriggerCondition.InteractKey;

    [Header("行为")]
    [SerializeField] private bool                 _isOneShot;    // 一次性，触发后永久激活
    [SerializeField] private string               _interactableId;  // 存档用唯一 ID

    [Header("事件频道（零耦合连接关卡受体）")]
    [SerializeField] private VoidEventChannelSO   _activationChannel;
    [SerializeField] private VoidEventChannelSO   _deactivationChannel; // 非 OneShot 离开时

    [Header("反馈")]
    [SerializeField] private MMF_Player           _activateFeedback;

    private bool _activated;

    // ── IInteractable（InteractKey 模式）─────────────────────────────
    public string InteractPrompt => _activated ? "已激活" : "交互";
    public void Interact(Transform player)   // ⚠️ Transform 参数（与 §7 IInteractable 对齐）
    {
        if (_triggerCondition != TriggerCondition.InteractKey) return;
        if (!CheckSide(player.position)) return;
        TryActivate();
    }

    // ── PlayerBody / PlayerAttack 模式 ───────────────────────────────
    // PlayerBody：OnTriggerEnter2D（Collider IsTrigger）
    // PlayerAttack：挂配套 HurtBox → DamageInfo → TryInteractFromDamage
    private void OnTriggerEnter2D(Collider2D other)
    {
        if (_triggerCondition != TriggerCondition.PlayerBody) return;
        if (!other.CompareTag("Player")) return;
        if (!CheckSide(other.transform.position)) return;
        TryActivate();
    }

    private void OnTriggerExit2D(Collider2D other)
    {
        if (_triggerCondition != TriggerCondition.PlayerBody) return;
        if (!other.CompareTag("Player") || _isOneShot) return;
        _activated = false;
        _deactivationChannel?.Raise();
    }

    // 由外部 HurtBox 转发（PlayerAttack 模式）
    public void TryInteractFromDamage(DamageInfo info)
    {
        if (_triggerCondition != TriggerCondition.PlayerAttack) return;
        if (!CheckSide(info.SourcePosition)) return;
        TryActivate();
    }

    private void TryActivate()
    {
        if (_isOneShot && _activated) return;
        _activated = true;
        _activateFeedback?.PlayFeedbacks();
        _activationChannel?.Raise();
        if (_isOneShot)
        {
            // 持久化
            SaveManager.Instance?.SetMechanismState(_interactableId, true);
        }
    }

    private bool CheckSide(Vector2 sourcePos)
    {
        if (_triggerSide == TriggerSide.Any) return true;
        var dir = (sourcePos - (Vector2)transform.position).normalized;
        return _triggerSide switch
        {
            TriggerSide.Left  => dir.x < -0.4f,
            TriggerSide.Right => dir.x >  0.4f,
            TriggerSide.Top   => dir.y >  0.4f,
            _                 => true
        };
    }

    private void Start()
    {
        // 读档恢复
        if (_isOneShot && !string.IsNullOrEmpty(_interactableId)
            && (SaveManager.Instance?.GetMechanismState(_interactableId) ?? false))
        {
            _activated = true;
            _activationChannel?.Raise();  // 静默恢复联动状态
        }
    }
}
```

**零耦合连接示例**（Inspector 拖入同一 SO 资产）：

```
Switch_Forest_01._activationChannel  ──►  MovingPlatform._activationChannel
                                     ──►  Door_Locked._openChannel
                                     ──►  HazardZone_Spikes._disableChannel
```

---

## 14. CrumblePlatform — 碎裂平台

```csharp
// 路径: Assets/Scripts/World/CrumblePlatform.cs
[RequireComponent(typeof(BoxCollider2D))]
public class CrumblePlatform : MonoBehaviour
{
    [SerializeField] private float  _warningDuration = 0.6f;  // 踩上后警告时长（抖动）
    [SerializeField] private float  _crumbleDuration = 0.3f;  // 碎裂动画时长
    [SerializeField] private float  _respawnDelay    = 3.0f;  // 0 = 永久消失
    [SerializeField] private bool   _isOneShot       = false; // true = 碎裂后永久消失
    [SerializeField] private MMF_Player _crumbleFeedback;     // 预警震动 + 碎裂粒子 + 音效
    [SerializeField] private BoxCollider2D _passengerSensor;  // Trigger，检测玩家踩踏

    private BoxCollider2D  _col;
    private SpriteRenderer _sr;
    private bool _isCrumbling;

    private static readonly int[] StateFrames = { 0, 1, 2, 3 }; // Idle/Warning/Crumbling/Gone

    private void Awake()
    {
        _col = GetComponent<BoxCollider2D>();
        _sr  = GetComponent<SpriteRenderer>();
    }

    private void OnTriggerEnter2D(Collider2D other)
    {
        if (_isCrumbling || !other.CompareTag("Player")) return;
        StartCoroutine(CrumbleSequence());
    }

    private IEnumerator CrumbleSequence()
    {
        _isCrumbling = true;

        // 1. Warning（抖动）
        _crumbleFeedback?.PlayFeedbacks();
        yield return new WaitForSeconds(_warningDuration);

        // 2. Crumbling
        yield return new WaitForSeconds(_crumbleDuration);

        // 3. Gone：禁用碰撞体 + 隐藏 Sprite
        _col.enabled = false;
        _sr.enabled  = false;
        _passengerSensor.enabled = false;

        if (_isOneShot || _respawnDelay <= 0f)
        {
            yield break;  // 永久消失
        }

        // 4. Respawn
        yield return new WaitForSeconds(_respawnDelay);
        _col.enabled = true;
        _sr.enabled  = true;
        _passengerSensor.enabled = true;
        _isCrumbling = false;
    }
}
```

**状态机**：

```
        [玩家踩上]
Idle ────────────► Warning ──[warningDuration]──► Crumbling ──[动画]──► Gone
                    抖动                                                  │
                                           ←──[respawnDelay，非 OneShot]─┘
```

---

## 15. SkillInteractable — 技能专属交互物

> 这类物体不走伤害管线，而是监听**角色技能状态**或**物理层叠加**实现交互。  
> 三种类型对应游戏内三个形态的专属技能机关。

### 15.1 MagicWall — 魔法障壁（太虚斩专属）

太虚斩（命魂 SoulSkill）施放时，玩家进入 `PhysicsLayer: Ghost`；`MagicWall` 对 `Ghost` 层**无碰撞**，允许穿越。

```csharp
// 路径: Assets/Scripts/World/MagicWall.cs
// 组件挂法：MagicWall GO 同时挂 TilemapCollider2D / BoxCollider2D
// 不与 Ghost 层碰撞（Physics Layer Matrix 配置，非代码控制）
// 脚本职责：Gizmo 可视化 + 颜色联动（普通/幽灵两态视觉区分）
[ExecuteAlways]
public class MagicWall : MonoBehaviour
{
    [SerializeField] private Color _normalColor = new(0.4f, 0.2f, 1f, 0.8f);  // 紫色（可见）
    [SerializeField] private Color _ghostColor  = new(0.4f, 0.2f, 1f, 0.15f); // 淡紫（穿越提示）

    // 在 FormSkillSO（太虚斩）canPassMagicWalls = true 时，
    // SkillManager 在技能开始/结束时切换玩家的物理层：
    //   开始: player.gameObject.layer = LayerMask.NameToLayer("Ghost")
    //   结束: player.gameObject.layer = LayerMask.NameToLayer("Player")
    // Physics Layer Matrix 设置: Ghost vs MagicWall = IgnoreCollision
    // 因此 MagicWall 本身无需额外代码，只靠层矩阵实现穿越。

#if UNITY_EDITOR
    private void OnDrawGizmos()
    {
        Gizmos.color = _normalColor;
        var b = GetComponent<Collider2D>();
        if (b != null)
            Gizmos.DrawWireCube(transform.position, b.bounds.size);
    }
#endif
}
```

**Physics Layer Matrix 配置**：

| Layer A | Layer B | 碰撞 |
|---------|---------|------|
| `Player` | `MagicWall` | ✅ 碰撞（正常阻挡）|
| `Ghost` | `MagicWall` | ❌ 忽略（太虚斩穿越）|
| `Enemy` | `MagicWall` | ✅ 碰撞（敌人不能穿越）|

> 参见 [57_PhysicsLayerMatrix.md](../Design/57_PhysicsLayerMatrix.md)。  
> `SkillManager.TrySoulSkill()` 在技能激活/结束时调用 `SetPlayerLayer("Ghost"/"Player")`。

---

### 15.2 SoftTerrain — 松软地面（地行术专属）

地行术（地魂 SoulSkill）的 `GroundDive` 状态中，玩家进入地面移动。`SoftTerrain` 地块降低地行术**灵力消耗速率**（松软地面不消耗灵力）。

```csharp
// 路径: Assets/Scripts/World/SoftTerrain.cs
// 挂在松软地面的 Tilemap/GameObject 上
// GroundDiveState 通过 OverlapPoint 检测当前站立/穿行瓦片，查询是否 IsSoftTerrain
public class SoftTerrain : MonoBehaviour
{
    // Marker 组件——无逻辑，仅用于 GetComponent<SoftTerrain>() 检测
    // GroundDiveState（PlayerFSM）在每帧对角色脚下 Physics2D.OverlapPoint() 检测：
    //   若碰到实现了 SoftTerrain 的 Tilemap → SetSoulDrainRate(0)
    //   否则 → SetSoulDrainRate(FormSkillSO.soulCostPerSecond)
}
```

**关卡搭建**：
- 在 `[Level]` 下新增 `Tilemap_SoftGround` 层，铺设松软地面 Tile
- 该 Tilemap GameObject 挂载 `SoftTerrain` 组件
- `TilemapCollider2D.isTrigger = false`（正常地面碰撞，`GroundDiveState` 穿越时物理层切换为 `Ghost` 忽略该层）

**与 MagicWall 的关键区别**：

| | MagicWall | SoftTerrain |
|-|-----------|-------------|
| 穿越条件 | 太虚斩激活（`Ghost` 层）| 地行术激活（另一 `Ghost` 变体层）|
| 其余情况 | 实体阻挡 | 实体地面 |
| 游戏效果 | 到达秘密区域 / 跑图捷径 | 降低灵力消耗 / 速度加成 |

---

### 15.3 PhantomInteractable — 幻影机关（残阴术专属）

残阴术（命魂 SpiritSkill1）在原地留下灵体，灵体可代替玩家触发特定机关。  
普通 `PressurePlate` 仅响应玩家，`PhantomInteractable` 额外响应 `PhantomBody` 层。

```csharp
// 路径: Assets/Scripts/World/PhantomInteractable.cs
// 继承 DirectionalInteractable，额外监听 PhantomBody 层的 Collider 进入
// 用途：需要延迟触发的机关（先放灵体踩住，再操控玩家本体做其他事）
public class PhantomInteractable : DirectionalInteractable
{
    // 残阴术（SpiritSkill1）实例化 PhantomBody Prefab，
    // PhantomBody 挂载 Rigidbody2D，Layer = "PhantomBody"
    // 本组件的 Collider（Trigger）对 PhantomBody 层同样响应

    private new void OnTriggerEnter2D(Collider2D other)
    {
        bool isPlayer  = other.CompareTag("Player");
        bool isPhantom = other.gameObject.layer ==
                         LayerMask.NameToLayer("PhantomBody");
        if (!isPlayer && !isPhantom) return;

        // 方向校验：幻影机关通常 TriggerSide = Any（灵体无方向约束）
        TryActivate();
    }
}
```

**典型谜题**：

```
场景设置：
  PhantomInteractable（PressurePlate 型）── _activationChannel ──► Door

解谜流程：
  1. 玩家施放残阴术 → 留下灵体踩住 PhantomInteractable → 门打开
  2. 玩家快速通过门洞
  3. 残阴术持续时间结束 → 灵体消失 → PhantomInteractable 失活 → 门关闭（若非 OneShot）
```

---

## 16. 世界事件频道清单

| 资产名 | 类型 | Raise 方 | Subscribe 方 |
|--------|------|---------|-------------|
| `EVT_SavePointActivated` | `StringEventChannelSO` | `SavePoint` | `GameManager`（触发存档）、`HUDController`（显示提示） |
| `EVT_RoomTransitionRequest` | `SceneLoadRequestEventChannelSO` | `RoomTransition` | `SceneLoader` |
| `EVT_CollectiblePickup` | `StringEventChannelSO` | `Collectible`、`AbilityUnlock` | `WorldStateRegistry`、`QuestManager`、`AnalyticsManager` |
| `EVT_FastTravelOpen` | `VoidEventChannelSO` | `SavePoint` | `UIManager`（显示 FastTravel 面板） |
| `EVT_ShowInteractPrompt` | `StringEventChannelSO` | `InteractableDetector` | `HUDController` |
| `EVT_HideInteractPrompt` | `VoidEventChannelSO` | `InteractableDetector` | `HUDController` |