chore: initial commit

2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
--- a/Docs/Design/16_MapSystem.md
+++ b/Docs/Design/16_MapSystem.md
@@ -0,0 +1,488 @@
+# 16 · 地图系统
+
+> **命名空间** `BaseGames.World.Map`  
+> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
+> **依赖** `BaseGames.Core.Events` · `BaseGames.World`（SaveSystem）· `BaseGames.UI`
+
+---
+
+## 目录
+
+1. [系统总览](#1-系统总览)
+2. [MapRoomDataSO — 房间元数据](#2-maproomdataso--房间元数据)
+3. [MapManager — 探索状态管理](#3-mapmanager--探索状态管理)
+4. [雾战渲染（Fog of War）](#4-雾战渲染fog-of-war)
+5. [地图 UI — 全屏地图](#5-地图-ui--全屏地图)
+6. [小地图 HUD](#6-小地图-hud)
+7. [玩家位置追踪](#7-玩家位置追踪)
+8. [地图图钉系统](#8-地图图钉系统)
+9. [区域颜色与标记](#9-区域颜色与标记)
+10. [SaveData 集成](#10-savedata-集成)
+11. [场景搭建规范](#11-场景搭建规范)
+12. [事件频道](#12-事件频道)
+13. [编辑器友好设计](#13-编辑器友好设计)
+
+---
+
+## 1. 系统总览
+
+地图系统是类银河恶魔城游戏的核心特征之一：玩家在黑暗中探索，地图随着进入新房间逐渐揭开。
+
+```
+地图系统职责:
+  ├─ MapRoomDataSO     → 每个房间的形状/出口/区域元数据（Edit Time 配置）
+  ├─ MapManager        → 运行时探索状态，驱动地图揭露（OnRoomEntered 监听）
+  ├─ Fog of War        → 未探索黑色，已进入轮廓，已存档实色——三级显示
+  ├─ 全屏地图 UI       → 按 Map 键打开，可滚动/缩放
+  ├─ 小地图 HUD        → HUD 角落实时显示当前区域缩略图
+  ├─ 玩家位置          → 随房间切换实时更新图标
+  └─ 地图图钉          → 玩家手动标记感兴趣位置
+```
+
+**零耦合原则**：`MapManager` 仅监听 `OnRoomEntered` 事件频道，不持有 `PlayerController` 引用。
+
+---
+
+## 2. MapRoomDataSO — 房间元数据
+
+每个房间场景对应一个 `MapRoomDataSO` 资产，**Edit Time 配置**，不在运行时生成。
+
+```csharp
+[CreateAssetMenu(menuName = "World/Map/RoomData")]
+public class MapRoomDataSO : ScriptableObject
+{
+    [Header("基础信息")]
+    public string   roomId;               // 与场景名一致，如 "Room_Forest_01"
+    public string   displayName;          // 可选，地图 Tooltip 显示
+    public string   regionId;             // 所属区域，如 "Forest"
+
+    [Header("地图布局")]
+    public Vector2Int gridPosition;       // 地图格子坐标（手动填写，单位：格）
+    public Vector2Int gridSize;           // 房间占据的格子数，如 (2, 1)
+    public Texture2D  roomOutlineTex;     // 房间轮廓贴图（Edit Tool 自动生成，见 §13）
+
+    [Header("出口")]
+    public RoomExitData[] exits;          // 本房间所有出口（方向 + 目标房间 ID）
+
+    [Header("特殊标记")]
+    public bool isBossRoom;               // Boss 房间（地图特殊图标）
+    public bool isSavePoint;              // 含存档点（地图存档图标）
+    public bool isShop;                   // 含商店（地图商店图标）
+    public Sprite mapIconOverride;        // 自定义图标（如 None 则按 isXxx 自动选择）
+}
+
+[Serializable]
+public struct RoomExitData
+{
+    public ExitDirection direction;   // Left / Right / Up / Down
+    public string        targetRoomId;
+    public Vector2Int    exitGridPos; // 出口在格子中的相对位置（用于绘制连接线）
+}
+```
+
+**资产存放路径**：`Assets/ScriptableObjects/World/MapRooms/`  
+**命名规范**：`MR_{SceneName}.asset`，如 `MR_Room_Forest_01.asset`
+
+---
+
+## 3. MapManager — 探索状态管理
+
+`MapManager` 常驻 Persistent 场景，维护运行时探索状态并驱动地图 UI 刷新。
+
+```csharp
+namespace BaseGames.World.Map
+{
+    public class MapManager : MonoBehaviour
+    {
+        [Header("配置")]
+        [SerializeField] MapRoomDataSO[]     _allRooms;          // 所有房间 SO 数组
+        [SerializeField] MapDatabaseSO       _mapDatabase;       // 统一索引（见下）
+
+        [Header("事件频道（监听）")]
+        [SerializeField] StringEventChannelSO _onRoomEntered;        // 监听：进入新房间（传入 roomId）
+        [SerializeField] VoidEventChannelSO   _onSavePointActivated; // 监听：存档点激活
+
+        [Header("事件频道（发布）")]
+        [SerializeField] StringEventChannelSO _onRoomExploredForSave; // 发布：新房间已探索，SaveSystem 监听并写入 SaveData
+
+        // 运行时状态（与 SaveData 同步）
+        readonly HashSet<string> _exploredRooms   = new();  // 已进入房间
+        readonly HashSet<string> _mappedRooms     = new();  // 已存档房间（完整显示）
+        string _currentRoomId;
+
+        // 地图 UI 刷新事件（MapUI 订阅）
+        public event Action<string> OnRoomRevealed;    // roomId
+        public event Action<string> OnRoomMapped;      // roomId
+        public event Action<string> OnCurrentRoomChanged;
+
+        void OnEnable()
+        {
+            _onRoomEntered.OnEventRaised        += HandleRoomEntered;
+            _onSavePointActivated.OnEventRaised += HandleSavePointActivated;
+        }
+
+        void OnDisable()
+        {
+            _onRoomEntered.OnEventRaised        -= HandleRoomEntered;
+            _onSavePointActivated.OnEventRaised -= HandleSavePointActivated;
+        }
+
+        void HandleRoomEntered(string roomId)
+        {
+            _currentRoomId = roomId;
+            OnCurrentRoomChanged?.Invoke(roomId);
+
+            if (_exploredRooms.Add(roomId))         // 首次进入
+            {
+                OnRoomRevealed?.Invoke(roomId);      // 触发地图揭露
+                // 零耦合：通过事件频道通知 SaveSystem 记录，而非直接调用 SaveManager.Instance
+                _onRoomExploredForSave.Raise(roomId);
+            }
+        }
+
+        void HandleSavePointActivated()
+        {
+            if (_currentRoomId == null) return;
+            if (_mappedRooms.Add(_currentRoomId))    // 存档后升级为 Mapped
+                OnRoomMapped?.Invoke(_currentRoomId);
+        }
+
+        // 启动时从 SaveData 恢复状态
+        public void Initialize(SaveData data)
+        {
+            _exploredRooms.UnionWith(data.world.discoveredRooms);
+            _mappedRooms.UnionWith(data.world.mappedRooms);
+        }
+
+        // 查询接口（供 MapUI 使用）
+        public MapRoomState GetRoomState(string roomId)
+        {
+            if (_mappedRooms.Contains(roomId))    return MapRoomState.Mapped;
+            if (_exploredRooms.Contains(roomId))  return MapRoomState.Explored;
+            return MapRoomState.Unknown;
+        }
+
+        public string CurrentRoomId => _currentRoomId;
+    }
+
+    public enum MapRoomState { Unknown, Explored, Mapped }
+}
+```
+
+### MapDatabaseSO — 全局房间索引
+
+```csharp
+[CreateAssetMenu(menuName = "World/Map/Database")]
+public class MapDatabaseSO : ScriptableObject
+{
+    [SerializeField] MapRoomDataSO[] _rooms;
+    Dictionary<string, MapRoomDataSO> _dict;
+
+    public void BuildIndex()
+        => _dict = _rooms.ToDictionary(r => r.roomId, r => r);
+
+    public MapRoomDataSO GetRoom(string roomId)
+        => _dict.TryGetValue(roomId, out var r) ? r : null;
+
+    public IEnumerable<MapRoomDataSO> GetRoomsByRegion(string regionId)
+        => _rooms.Where(r => r.regionId == regionId);
+}
+```
+
+---
+
+## 4. 雾战渲染（Fog of War）
+
+地图采用**三级可见度**区分探索程度：
+
+| 状态 | 触发条件 | 渲染效果 |
+|------|---------|---------|
+| `Unknown` | 从未进入 | 完全黑色（不显示轮廓）|
+| `Explored` | 已进入但未存档 | 显示房间轮廓线（半透明灰色，填充黑色）|
+| `Mapped` | 已进入且存档 | 完整显示（填充区域色，出口连接线）|
+
+### 渲染实现
+
+地图使用 **Unity UI Image + RenderTexture** 渲染，而非 World Space GameObject：
+
+```
+MapUI Canvas
+└── MapRawImage (RawImage，显示 _mapRenderTexture)
+    └── 分辨率: 512×512（整个大地图）
+```
+
+`MapRenderer`（Editor Script + Runtime Renderer）：
+
+1. **Edit Time**：`MapEditorTool`（见 §13）根据 `MapRoomDataSO.roomOutlineTex` + `gridPosition` 将所有房间烘焙到一张 `MapAtlasTexture`
+2. **Runtime**：`MapRenderer` 在 `MapAtlasTexture` 基础上，叠加 `FogLayer`（黑色遮罩 Texture）；`MapManager` 揭露房间时，擦除对应格子的 `FogLayer`（填充透明）
+3. 玩家位置图标通过 UI Image 覆盖在最上层，位置由格子坐标实时映射
+
+### 雾战擦除算法
+
+```csharp
+void RevealRoom(string roomId)
+{
+    var data = _database.GetRoom(roomId);
+    if (data == null) return;
+
+    // 将格子坐标映射到贴图像素范围
+    int px = data.gridPosition.x * CELL_SIZE_PX;
+    int py = data.gridPosition.y * CELL_SIZE_PX;
+    int w  = data.gridSize.x * CELL_SIZE_PX;
+    int h  = data.gridSize.y * CELL_SIZE_PX;
+
+    // 按状态设置不同 Alpha
+    float alpha = state == MapRoomState.Mapped ? 0f : 0.6f;  // Mapped=全透明，Explored=半透
+
+    Color[] pixels = _fogTexture.GetPixels(px, py, w, h);
+    for (int i = 0; i < pixels.Length; i++)
+        pixels[i] = new Color(0, 0, 0, alpha);
+    _fogTexture.SetPixels(px, py, w, h, pixels);
+    _fogTexture.Apply();
+}
+```
+
+常量 `CELL_SIZE_PX = 32`（每个格子对应 32×32 像素）。
+
+---
+
+## 5. 地图 UI — 全屏地图
+
+按 **Map 键**（默认 Tab）打开全屏地图，`GameState` 不变（仍为 Gameplay），仅叠加地图 UI 层。
+
+### Canvas 结构
+
+```
+Canvas_Map  (Sorting Order: 25，叠加在 HUD 之上)
+└── MapPanel (全屏 Panel，默认隐藏)
+    ├── MapScrollView             ← ScrollRect，支持鼠标/摇杆滚动
+    │   └── MapContent
+    │       ├── MapRawImage       ← 地图渲染（RenderTexture）
+    │       └── MapIconLayer      ← 图钉/图标 UI（RectTransform 层）
+    │           ├── PlayerIcon    ← 玩家当前位置（Image，跟随格子坐标）
+    │           ├── BossIcons[]   ← Boss 房间图标
+    │           ├── SaveIcons[]   ← 存档点图标
+    │           └── PinIcons[]    ← 玩家图钉
+    ├── RegionLegend              ← 右侧区域图例（颜色说明）
+    ├── CurrentRoomLabel          ← 左上角当前房间名
+    └── CloseHint                 ← "按 Tab/B 关闭"提示
+```
+
+### 地图交互
+
+| 操作 | 键盘 | 手柄 | 效果 |
+|------|------|------|------|
+| 打开/关闭地图 | Tab | Select | 切换显示 |
+| 移动视角 | WASD / 方向键 | 左摇杆 | 滚动 MapScrollView |
+| 缩放 | 鼠标滚轮 / Z/X | L2/R2 | Scale MapContent（0.5× ~ 2×）|
+| 放置图钉 | F | Y（△）| 在当前光标位置放置图钉 |
+| 移除图钉 | F（在图钉上）| Y | 移除选中图钉 |
+| 快速居中（玩家）| R | R3 | ScrollView 居中到玩家图标 |
+
+---
+
+## 6. 小地图 HUD
+
+小地图始终显示在 HUD 右上角（游戏中常驻），仅显示当前区域的缩略图：
+
+```
+Canvas_HUD
+└── MinimapPanel (右上角，固定位置)
+    ├── MinimapMask     (圆形 Mask，裁剪显示范围)
+    │   └── MinimapImage (RawImage，与全屏地图共享 RenderTexture，但 ViewportRect 限制)
+    └── MinimapBorder   (装饰边框)
+```
+
+- 小地图使用与全屏地图**相同的 RenderTexture**，通过 UV Offset + Scale 仅显示当前房间周围 5×5 格
+- 玩家在当前格子的移动通过 `MinimapImage.uvRect.position` 实时微调（平滑偏移）
+- 死亡/Boss 战时：小地图隐藏（`Canvas_HUD` 对应 GameObject 由 `UIManager` 控制）
+
+---
+
+## 7. 玩家位置追踪
+
+`MapPlayerTracker` 维护玩家在地图中的像素坐标，供全屏地图和小地图使用：
+
+```csharp
+public class MapPlayerTracker : MonoBehaviour
+{
+    [SerializeField] MapManager _mapManager;
+    [SerializeField] Transform  _player;
+
+    // 注入玩家 Transform（通过事件频道，不直接 Find）
+    void OnEnable() => _onPlayerSpawned.OnEventRaised += t => _player = t;
+
+    // 当前玩家在地图中的像素坐标（供 MapUI 设置 Image.rectTransform.anchoredPosition）
+    public Vector2 GetPlayerMapPixelPos()
+    {
+        var room  = _mapManager.Database.GetRoom(_mapManager.CurrentRoomId);
+        if (room == null || _player == null) return Vector2.zero;
+
+        // 房间格子左下角像素 + 玩家在房间内的相对位置（0~1）映射到像素范围
+        Vector2 roomOrigin = (Vector2)room.gridPosition * CELL_SIZE_PX;
+        Vector2 roomSize   = (Vector2)room.gridSize     * CELL_SIZE_PX;
+
+        // 玩家世界坐标 → 房间内归一化坐标（需要 RoomBoundsData 提供世界坐标范围）
+        Vector2 normalized = GetNormalizedPosInRoom(_player.position, room);
+        return roomOrigin + normalized * roomSize;
+    }
+}
+```
+
+---
+
+## 8. 地图图钉系统
+
+玩家可在地图任意已探索位置放置图钉，用于标记未完成的密室、待回来的通道等。
+
+### 图钉数据
+
+```csharp
+[Serializable]
+public class MapPin
+{
+    public string   roomId;          // 所在房间
+    public Vector2  normalizedPos;   // 在房间内的归一化坐标（0~1）
+    public PinType  type;            // Exclamation / Question / Heart / Star
+    public string   note;            // 玩家可选输入的备注文字（最多 20 字）
+}
+
+public enum PinType { Exclamation, Question, Heart, Star }
+```
+
+### 图钉持久化
+
+图钉数组存入 SaveData：
+
+```json
+"mapPins": [
+  { "roomId": "Room_Cave_03", "normalizedPos": { "x": 0.7, "y": 0.5 },
+    "type": "Question", "note": "有密室待探索" }
+]
+```
+
+### 图钉 UI 预制件
+
+```
+MapPin_Prefab (World Space UI，挂在 MapIconLayer)
+├── PinIcon  (Image，按 PinType 切换 Sprite)
+└── NoteTooltip (TextMeshPro，鼠标悬停时显示)
+```
+
+---
+
+## 9. 区域颜色与标记
+
+每个区域在地图中使用不同颜色区分（颜色定义在 `RegionDefinitionSO.mapColor`）：
+
+| 区域 | 颜色（参考）| 地图图标 |
+|------|-----------|---------|
+| Forest（扎根森林）| 绿色 `#4A7C3F` | 叶片图标 |
+| Cave（腐蚀洞穴）| 紫色 `#6A3FA0` | 骨骼图标 |
+| Ruins（坍塌废墟）| 棕色 `#8B6530` | 石柱图标 |
+| Abyss（深渊裂隙）| 深蓝 `#1A2A4A` | 深渊图标 |
+| Core（核心熔炉）| 红橙 `#C84B20` | 火焰图标 |
+
+**特殊房间标记**（覆盖在格子上的图标层）：
+
+| 类型 | 图标 | 触发条件 |
+|------|------|---------|
+| Boss 房间 | 骷髅/特殊图标 | `MapRoomDataSO.isBossRoom = true` |
+| 存档点 | 长椅/火焰图标 | `MapRoomDataSO.isSavePoint = true` |
+| 商店 | 硬币图标 | `MapRoomDataSO.isShop = true` |
+| 传送点 | 旋涡图标 | 由 `QuickTravelManager` 解锁后标记 |
+
+---
+
+## 10. SaveData 集成
+
+`SaveData.world` 新增字段（在 `08_WorldSystem.md §5` JSON Schema 基础上扩展）：
+
+```json
+"world": {
+  "discoveredRooms": ["Room_Forest_01", "Room_Forest_02"],
+  "mappedRooms":     ["Room_Forest_01"],
+  "mapPins": [
+    { "roomId": "Room_Cave_03", "normalizedPos": {"x":0.7,"y":0.5},
+      "type": "Question", "note": "密室" }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `discoveredRooms` | `string[]` | 已进入的房间（轮廓显示）|
+| `mappedRooms` | `string[]` | 存档后升级的房间（完整显示）|
+| `mapPins` | `MapPin[]` | 玩家图钉列表 |
+
+---
+
+## 11. 场景搭建规范
+
+每个房间场景添加 `RoomMapSetup` 组件，链接到对应 `MapRoomDataSO`：
+
+```
+Room_Forest_01 (Scene)
+└── [MapSetup] (GameObject)
+    └── RoomMapSetup.cs
+        └── _roomData: MapRoomDataSO  ← 拖入 MR_Room_Forest_01.asset
+```
+
+`RoomMapSetup` 在 `Awake` 时通过事件频道向 `MapManager` 注册当前房间（实际是 `OnRoomEntered` 频道由 `RoomTransition` 触发，`RoomMapSetup` 不主动发布，只提供数据查询入口）。
+
+---
+
+## 12. 事件频道
+
+| 频道资产 | 类型 | 发布方 | 主要订阅方 |
+|---------|------|--------|----------|
+| `OnRoomEntered.asset` | `StringEventChannelSO`（roomId）| `RoomTransition` | `MapManager`、`CameraStateController` |
+| `OnMapOpened.asset` | `VoidEventChannelSO` | `InputReader` | `MapUI`（显示）、`InputReader`（切 ActionMap）|
+| `OnMapClosed.asset` | `VoidEventChannelSO` | `MapUI` | `InputReader`（恢复 ActionMap）|
+| `OnMapPinAdded.asset` | `MapPinEventChannelSO` | `MapUI` | `SaveManager` |
+| `OnMapPinRemoved.asset` | `StringEventChannelSO`（pinId）| `MapUI` | `SaveManager` |
+
+---
+
+## 13. 编辑器友好设计
+
+### MapEditorTool — EditorWindow（UI Toolkit）
+
+路径：`Tools → Zeling → Map Editor`
+
+实现：继承 `EditorWindow`，覆写 `CreateGUI()`，使用 `TwoPaneSplitView`（左侧房间列表 `ListView` + 右侧属性面板） + 自绘格子地图（`generateVisualContent` + `Painter2D`）。
+
+功能：
+
+```
+┌─ Map Editor ──────────────────────────────────────────────┐
+│  [自动扫描所有 MapRoomDataSO]  [全部重新生成轮廓贴图]       │
+│                                                            │
+│  ┌──────────────────────────────────────────────────────┐ │
+│  │  地图预览（格子视图，颜色区分区域）                    │ │
+│  │                                                       │ │
+│  │  [Forest]  [Forest_01] [Forest_02]                   │ │
+│  │  [Cave]    [Cave_01]   [Cave_02]   [Cave_03]         │ │
+│  │  ...                                                  │ │
+│  └──────────────────────────────────────────────────────┘ │
+│                                                            │
+│  选中 Room_Forest_01:                                     │
+│    gridPosition: (0, 0)    gridSize: (2, 1)               │
+│    区域: Forest             出口: [Right→Forest_02]       │
+│    [生成轮廓贴图]  [定位场景]                              │
+└────────────────────────────────────────────────────────────┘
+```
+
+### 轮廓贴图自动生成
+
+`MapEditorTool` 对每个 `MapRoomDataSO` 自动生成 `roomOutlineTex`：
+1. 打开对应场景（`EditorSceneManager.OpenScene`，仅读取）
+2. 在场景 Tilemap 上执行 `Physics2D.OverlapAreaAll` 扫描地形轮廓
+3. 将轮廓绘制到 32×n px 的贴图并保存为 `.png`（`AssetDatabase.CreateAsset`）
+4. 自动赋值到 `MapRoomDataSO.roomOutlineTex`
+
+### RoomMapSetup Inspector
+
+- Inspector 中显示**预览图**（对应 `MapRoomDataSO.roomOutlineTex`）
+- 一键按钮「在地图编辑器中定位」，打开 MapEditorTool 并滚动到此房间
+- 若 `MapRoomDataSO` 未指定（null），显示红色警告：`⚠ 缺少 MapRoomDataSO！房间不会在地图中显示。`