334 lines
16 KiB
Markdown
334 lines
16 KiB
Markdown
# Nanami-UI 插件功能概览
|
||
|
||
本文基于当前仓库代码结构整理，目标是快速回答两个问题：
|
||
|
||
1. 这个乌龟服插件当前做了什么。
|
||
2. 每块功能主要落在哪些代码文件里。
|
||
|
||
## 1. 插件定位
|
||
|
||
`Nanami-UI` 是一个面向 Turtle WoW 1.12 环境的大型整合型 UI 插件。整体风格以 `SFrames` 为统一命名空间，核心能力主要包括：
|
||
|
||
- 自定义单位框体：玩家、宠物、目标、目标的目标、队伍、团队、焦点、天赋树。
|
||
- 动作条与按键：动作条重排、绑定管理、绑定导入导出。
|
||
- 地图与导航：小地图/世界地图换肤、地图迷雾揭示、区域等级、队友图标、暗月马戏团辅助。
|
||
- 聊天与社交：聊天框接管、私聊容器、社交面板重做。
|
||
- 背包与交易：背包/银行整合、离线库存、商人、交易、邮件、拾取窗口。
|
||
- 任务与书籍：任务对话、任务日志皮肤、书籍阅读界面。
|
||
- 职业与养成：角色面板、装备统计、观察面板、法术书、训练师、专业/制造、野兽训练。
|
||
- 辅助与增强：Tooltip、Tweaks、AFK 屏保、Setup Wizard、配置面板等。
|
||
|
||
## 2. 加载主线
|
||
|
||
### 2.1 入口文件
|
||
|
||
- [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc)
|
||
负责定义加载顺序、依赖和 SavedVariables。
|
||
- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
|
||
定义全局表 `SFrames`、事件分发、初始化总流程、角色配置快照、斜杠命令。
|
||
- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
|
||
提供默认配置、主题预设、颜色与样式生成逻辑。
|
||
|
||
### 2.2 初始化方式
|
||
|
||
当前插件的模块大致分成两种启动方式：
|
||
|
||
- `Core.lua` 集中初始化
|
||
通过 `SFrames:DoFullInitialize()` 分批启动关键模块与延迟模块，避免登录瞬间内存尖峰。
|
||
- 模块自举初始化
|
||
一部分界面文件自己监听 `PLAYER_LOGIN` / `ADDON_LOADED` / 专用事件，在对应窗口可用时初始化。
|
||
|
||
### 2.3 Core 直接管理的模块
|
||
|
||
`Core.lua` 当前显式初始化的模块包括：
|
||
|
||
- 立即加载：`Player`、`Pet`、`Target`、`ToT`、`Party`、`FloatingTooltip`、`ActionBars`
|
||
- 延迟批量加载：`Raid`、`Bags`、`Focus`、`TalentTree`、`Minimap`、`MinimapBuffs`、`MinimapButton`、`Chat`、`MapReveal`、`WorldMap`、`ZoneLevelRange`、`MapIcons`、`Tweaks`、`AFKScreen`、`LootDisplay`
|
||
|
||
### 2.4 自举型模块
|
||
|
||
这类文件通常在自身内部注册事件并完成初始化：
|
||
|
||
- [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua)
|
||
- [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua)
|
||
- [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua)
|
||
- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)
|
||
- [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua)
|
||
- [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua)
|
||
- [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua)
|
||
- [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua)
|
||
- [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua)
|
||
- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)
|
||
- [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua)
|
||
|
||
## 3. 核心框架与基础设施
|
||
|
||
### 3.1 核心与公共能力
|
||
|
||
- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
|
||
事件总线、统一初始化、角色配置快照、斜杠命令、若干兼容性保护。
|
||
- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
|
||
默认配置、主题生成、颜色方案、类职业主题映射。
|
||
- [Media.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Media.lua)
|
||
字体与状态条材质列表，兼容 LibSharedMedia。
|
||
- [Factory.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Factory.lua)
|
||
通用边框、背景、按钮、下拉、输入框等 UI 工厂方法。
|
||
- [Movers.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Movers.lua)
|
||
布局模式、拖拽锚点、网格吸附、统一解锁/锁定框体。
|
||
- [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua)
|
||
`img/icon.tga` 的图标坐标表，供多个界面复用。
|
||
- [Bindings.xml](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bindings.xml)
|
||
插件按键绑定入口。
|
||
- [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua)
|
||
综合配置面板，覆盖 UI、背包、动作条、小地图、角色等多页设置。
|
||
- [SetupWizard.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SetupWizard.lua)
|
||
首次安装向导，也可作为二次配置入口。
|
||
- [GameMenu.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GameMenu.lua)
|
||
游戏菜单增强，提供 Nanami-UI 相关入口。
|
||
- [MinimapButton.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapButton.lua)
|
||
小地图按钮，用于打开主要面板或功能入口。
|
||
|
||
### 3.2 斜杠命令
|
||
|
||
[Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 中已确认的主命令入口为：
|
||
|
||
- `/nanami`
|
||
- `/nui`
|
||
|
||
从当前代码可见，至少包含以下子命令：
|
||
|
||
- `unlock` / `move`
|
||
- `lock`
|
||
- `chatreset`
|
||
- `test`
|
||
- `partyh`
|
||
- `partyv`
|
||
- `partylayout`
|
||
- `focus`
|
||
- `clearfocus`
|
||
- `targetfocus`
|
||
- `fcast`
|
||
- `focushelp`
|
||
|
||
此外还有若干模块自己的调试或快捷命令：
|
||
|
||
- [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua)：`/dmf`、`/darkmoon`
|
||
- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)：`/ftcdebug`、`/ftcexport`
|
||
- [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua)：`/gsdebug`
|
||
- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)：`/btdebug`
|
||
|
||
## 4. 功能与代码文件对应
|
||
|
||
### 4.1 单位框体与战斗信息
|
||
|
||
- [Units\Player.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Player.lua)
|
||
玩家框体，包含血量/能量、头像、施法条、buff/debuff、移动锚点等。
|
||
- [Units\Pet.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Pet.lua)
|
||
宠物框体。
|
||
- [Units\Target.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Target.lua)
|
||
目标框体，含施法识别与法术图标映射。
|
||
- [Units\ToT.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\ToT.lua)
|
||
目标的目标框体。
|
||
- [Units\Party.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Party.lua)
|
||
队伍框体，支持布局切换、拖拽物品到队友等逻辑。
|
||
- [Units\Raid.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Raid.lua)
|
||
团队框体。
|
||
- [Focus.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Focus.lua)
|
||
焦点系统，支持设置焦点、目标焦点、对焦点施法。
|
||
- [Tooltip.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tooltip.lua)
|
||
浮动 Tooltip、单位信息扩展。
|
||
- [MinimapBuffs.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapBuffs.lua)
|
||
小地图附近的 buff/debuff 重新排布。
|
||
- [ActionBars.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ActionBars.lua)
|
||
主动作条、姿态条、宠物条、键位显示、范围检测、布局修正。
|
||
- [KeyBindManager.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\KeyBindManager.lua)
|
||
按键绑定查看、导入导出、编辑。
|
||
|
||
### 4.2 地图与导航
|
||
|
||
- [Minimap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Minimap.lua)
|
||
小地图换肤，支持不同边框样式与职业主题皮肤。
|
||
- [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua)
|
||
世界地图整体重绘与窗口化，是地图类功能的主要承载文件。
|
||
- [MapReveal.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapReveal.lua)
|
||
迷雾揭示与 overlay 数据补丁。
|
||
- [ZoneLevelRange.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ZoneLevelRange.lua)
|
||
世界地图区域等级、阵营归属、副本/团队本信息提示。
|
||
- [MapIcons.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapIcons.lua)
|
||
世界地图、小地图、战场地图上的队伍/团队职业图标显示。
|
||
- [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua)
|
||
暗月马戏团 Sayge Buff 指引面板。
|
||
- [DarkmoonMapMarker.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonMapMarker.lua)
|
||
现在只保留兼容占位，实际标记逻辑已并入 `WorldMap.lua`。
|
||
- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)
|
||
飞行点目的地列表、飞行进度条与路径可视化。
|
||
- [FlightData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightData.lua)
|
||
飞行路线耗时数据库。
|
||
|
||
### 4.3 聊天与社交
|
||
|
||
- [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua)
|
||
聊天框全面换肤与接管，保留原生聊天后端。
|
||
- [Whisper.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Whisper.lua)
|
||
私聊联系人和聊天记录容器。
|
||
- [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua)
|
||
好友、忽略、Who、公会、团队管理界面重做。
|
||
|
||
### 4.4 背包、银行、商人、交易、邮件、拾取
|
||
|
||
- [Bags\Offline.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Offline.lua)
|
||
跨角色离线背包/银行数据采集。
|
||
- [Bags\Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Core.lua)
|
||
背包模块总入口。
|
||
- [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua)
|
||
背包容器 UI 与交互。
|
||
- [Bags\Bank.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Bank.lua)
|
||
银行界面与银行容器管理。
|
||
- [Bags\Sort.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Sort.lua)
|
||
背包整理逻辑。
|
||
- [Bags\Features.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Features.lua)
|
||
自动卖灰、自动开包等附加功能。
|
||
- [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua)
|
||
商人面板重做，含回购、批量购买、修理。
|
||
- [Trade.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Trade.lua)
|
||
交易窗口重做。
|
||
- [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua)
|
||
邮件面板重做，支持收件管理与多物品发送队列。
|
||
- [LootDisplay.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\LootDisplay.lua)
|
||
接管原生拾取窗口视觉层，同时尽量保留原生按钮交互。
|
||
- [SellPriceDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SellPriceDB.lua)
|
||
物品售卖价格数据库，服务于商人/背包场景。
|
||
|
||
### 4.5 任务、书籍、日志
|
||
|
||
- [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua)
|
||
NPC 任务对话、详情、进度、奖励等流程界面。
|
||
- [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua)
|
||
任务日志窗口换肤。
|
||
- [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua)
|
||
书籍/卷轴阅读窗口重做。
|
||
|
||
### 4.6 角色、法术、训练、专业
|
||
|
||
- [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua)
|
||
角色面板核心文件，体量很大，集成装备、属性、模型、称号、套装等内容。
|
||
- [StatSummary.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\StatSummary.lua)
|
||
装备统计摘要与独立统计面板。
|
||
- [InspectPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\InspectPanel.lua)
|
||
观察面板与目标装备信息展示。
|
||
- [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua)
|
||
法术书重做。
|
||
- [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua)
|
||
职业训练师界面重做。
|
||
- [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua)
|
||
专业制造/制作界面重做。
|
||
- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)
|
||
猎人宠物训练界面重做。
|
||
- [PetStableSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\PetStableSkin.lua)
|
||
宠物管理员/兽栏界面皮肤化。
|
||
- [Units\TalentTree.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\TalentTree.lua)
|
||
天赋树显示模块。
|
||
- [TalentDefaultDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TalentDefaultDB.lua)
|
||
默认天赋数据库。
|
||
- [TradeSkillDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillDB.lua)
|
||
专业/配方静态数据库。
|
||
- [ClassSkillData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ClassSkillData.lua)
|
||
职业训练技能数据。
|
||
- [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua)
|
||
装等/装备评分能力。
|
||
|
||
### 4.7 其他增强
|
||
|
||
- [Tweaks.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tweaks.lua)
|
||
各种杂项增强，当前能看到包括自动下马/取消变形、冷却文本、世界地图 Tooltip 处理、战斗提示等。
|
||
- [AFKScreen.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\AFKScreen.lua)
|
||
AFK 全屏界面，显示模型、时间、世界 Buff 等信息。
|
||
- [Roll.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Roll.lua)
|
||
与掷骰/需求贪婪相关的界面或逻辑扩展。
|
||
|
||
## 5. 数据、资源与文档文件
|
||
|
||
### 5.1 图片与材质资源
|
||
|
||
- `img/`
|
||
存放小地图底图、职业风格贴图、动作条材质、图标图集等资源。
|
||
- [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua)
|
||
对 `img/icon.tga` 提供图标索引。
|
||
|
||
### 5.2 现有文档
|
||
|
||
- [docs\LootDisplay-技术要点.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\LootDisplay-技术要点.md)
|
||
记录接管拾取窗口时的关键实现思路。
|
||
- [docs\AutoDismount-技术总结.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\AutoDismount-技术总结.md)
|
||
记录自动下马/取消变形的实现方案。
|
||
|
||
### 5.3 辅助脚本与研究资料
|
||
|
||
- `agent-tools/`
|
||
看起来用于生成或整理职业训练相关数据。
|
||
- `*.pdf`
|
||
当前仓库中包含乌龟服属性收益研究资料，更偏设计/数值参考，不属于插件运行时代码。
|
||
|
||
## 6. SavedVariables 与依赖
|
||
|
||
### 6.1 SavedVariables
|
||
|
||
根据 [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc)：
|
||
|
||
- `SFramesDB`
|
||
角色级配置。
|
||
- `SFramesGlobalDB`
|
||
全局配置和跨角色数据。
|
||
|
||
### 6.2 可选依赖
|
||
|
||
`toc` 中声明的可选依赖包括：
|
||
|
||
- `ShaguTweaks`
|
||
- `Blizzard_CombatLog`
|
||
- `HealComm-1.0`
|
||
- `DruidManaLib-1.0`
|
||
- `!Libs`
|
||
- `pfQuest`
|
||
- `RDbItems`
|
||
|
||
从代码上看，这些依赖主要用于：
|
||
|
||
- 治疗预测、Debuff/Overlay 数据读取。
|
||
- 地图尺寸与覆盖层补全。
|
||
- 额外物品/任务数据支持。
|
||
|
||
## 7. 维护视角下的重点文件
|
||
|
||
如果后续要继续分析或改功能，优先关注下面这些“枢纽文件”：
|
||
|
||
- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
|
||
初始化顺序、模块开关、斜杠命令、配置快照。
|
||
- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
|
||
默认值和主题系统。
|
||
- [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua)
|
||
用户可见设置入口。
|
||
- [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua)
|
||
当前仓库里体量最大、耦合也较高的角色面板核心。
|
||
- [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua)
|
||
体量大、接管深，聊天相关问题通常会从这里开始查。
|
||
- [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua)
|
||
地图增强的主要承载点。
|
||
- [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua)
|
||
背包显示与交互核心。
|
||
|
||
## 8. 当前文档的边界
|
||
|
||
这份文档是“基础概览版”，目前更偏结构和职责映射，尚未逐项展开：
|
||
|
||
- 每个模块的详细事件流。
|
||
- 每个配置项对应的具体字段。
|
||
- 模块之间的调用关系图。
|
||
- Turtle WoW 私有 API 或兼容处理的逐点说明。
|
||
|
||
如果继续往下做，比较自然的下一步是：
|
||
|
||
1. 补一份“初始化时序图”。
|
||
2. 补一份“配置字段与模块对应表”。
|
||
3. 针对地图、角色面板、聊天三个大模块分别拆详细设计文档。
|