Nanami-UI/docs/MapReveal-Standalone.md

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 勾选框，方便用户直接开关迷雾揭示。

数据结构建议

角色级配置：

NanamiMapRevealDB = {
    enabled = true,
    unexploredAlpha = 0.7,
}

账号级扫描数据：

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
• standalone/Nanami-MapReveal/Core.lua
• 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 私服整合端分别适配。