聊天重做前缓存

docs/MapReveal-Standalone.md

@@ -0,0 +1,126 @@
+# MapReveal Standalone
+
+## 目标
+
+把 `Nanami-UI` 里的地图迷雾揭示功能单独提纯出来，方便其他插件作者复用，而不依赖整套 `SFrames` / `Nanami-UI` 框架。
+
+## 当前实现包含什么
+
+原始实现位于 `MapReveal.lua`，核心能力有 4 部分：
+
+1. 基于 `LibMapOverlayData` / `MapOverlayData` 补全地图 overlay 数据。
+2. Hook `WorldMapFrame_Update`，在世界地图刷新后把未探索区域重新画出来，并降低亮度显示。
+3. 被动采集当前角色已经探索过的 overlay，持久化到 SavedVariables。
+4. 主动扫描全部大陆与区域，把当前角色已经探索到的 overlay 批量收集出来。
+
+## 与 Nanami-UI 的耦合点
+
+真正的强耦合不多，主要只有这些：
+
+1. `SFrames:Print`
+   用于聊天框输出提示。
+2. `SFramesDB` / `SFramesGlobalDB`
+   分别保存角色配置和账号级扫描数据。
+3. `SFrames:CallWithPreservedBattlefieldMinimap`
+   用来保护战场小地图状态，避免 `SetMapZoom` / `SetMapToCurrentZone` 带来副作用。
+4. `/nui ...`
+   命令入口挂在 `Nanami-UI` 的统一 Slash Command 里。
+5. `ConfigUI.lua`
+   只是配置面板入口，不影响核心迷雾逻辑。
+
+## 提纯后的最小依赖
+
+独立插件只需要：
+
+1. `LibMapOverlayData` 或兼容的 overlay 数据表。
+2. `WorldMapFrame_Update`
+3. `GetMapInfo` / `GetNumMapOverlays` / `GetMapOverlayInfo`
+4. `SetMapZoom` / `SetMapToCurrentZone`
+5. SavedVariables
+
+也就是说，这个功能本质上可以完全脱离 UI 框架。
+
+## 推荐拆分方式
+
+建议拆成一个独立插件：
+
+1. `Nanami-MapReveal.toc`
+2. `Core.lua`
+3. `MapReveal.lua`
+
+其中：
+
+1. `Core.lua` 负责初始化、打印、Slash 命令、配置默认值。
+2. `MapReveal.lua` 只保留地图迷雾逻辑、扫描逻辑、数据持久化。
+3. 独立版会在世界地图右上角放一个 `Reveal` 勾选框，方便用户直接开关迷雾揭示。
+
+## 数据结构建议
+
+角色级配置：
+
+```lua
+NanamiMapRevealDB = {
+    enabled = true,
+    unexploredAlpha = 0.7,
+}
+```
+
+账号级扫描数据：
+
+```lua
+NanamiMapRevealGlobalDB = {
+    scanned = {
+        ["ZoneName"] = {
+            "OVERLAYNAME:width:height:offsetX:offsetY",
+        },
+    },
+}
+```
+
+## Hook 策略
+
+最稳妥的方式仍然是包裹 `WorldMapFrame_Update`：
+
+1. 先隐藏现有 `WorldMapOverlay1..N`
+2. 调用原始 `WorldMapFrame_Update`
+3. 被动收集当前可见的 explored overlays
+4. 如果开关开启，再自行补画 unexplored overlays
+
+这样兼容原版地图逻辑，也不需要重做整张世界地图。
+
+## 兼容注意点
+
+1. `NUM_WORLDMAP_OVERLAYS` 不够时要动态扩容。
+2. 最后一行/列贴图可能不是 256，必须重新计算 `TexCoord`。
+3. 个别地图 overlay 偏移有 errata，需要单独修正。
+4. 扫描地图时可能影响当前地图上下文，结束后要恢复原地图层级。
+5. 如果服务端或整合包已经补过 `MapOverlayData`，合并时要按 overlay 名去重。
+
+## 已提取的独立插件样板
+
+仓库里已经附带一个可复用版本：
+
+- [standalone/Nanami-MapReveal/Nanami-MapReveal.toc](e:/Game/trutle%20wow/Interface/AddOns/Nanami-UI/standalone/Nanami-MapReveal/Nanami-MapReveal.toc)
+- [standalone/Nanami-MapReveal/Core.lua](e:/Game/trutle%20wow/Interface/AddOns/Nanami-UI/standalone/Nanami-MapReveal/Core.lua)
+- [standalone/Nanami-MapReveal/MapReveal.lua](e:/Game/trutle%20wow/Interface/AddOns/Nanami-UI/standalone/Nanami-MapReveal/MapReveal.lua)
+
+## 给其他作者的接入建议
+
+如果对方已经有自己的框架：
+
+1. 保留 `MapReveal.lua` 主体逻辑。
+2. 把打印函数替换成自己的日志函数。
+3. 把 DB 名称换成自己的 SavedVariables。
+4. 把 Slash 命令合并进自己的命令系统。
+
+如果对方只想直接用：
+
+1. 复制 `standalone/Nanami-MapReveal` 整个目录。
+2. 放进 `Interface/AddOns/`
+3. 确保客户端有 `LibMapOverlayData` 或兼容数据源。
+
+## 后续可继续提纯的方向
+
+1. 把 `TurtleWoW_Zones` 再单独拆成数据文件。
+2. 增加一个纯 API 层，只暴露 `Toggle` / `Refresh` / `ScanAllMaps` / `ExportScannedData`。
+3. 为不同端做兼容层，比如 Turtle WoW、Vanilla、1.12 私服整合端分别适配。