# 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 私服整合端分别适配。