127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# 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 私服整合端分别适配。
|