222 lines
7.3 KiB
Markdown
222 lines
7.3 KiB
Markdown
# Nanami-Plates 仇恨系统对接需求文档
|
||
|
||
## 概述
|
||
|
||
Nanami-DPS 已完成仇恨监控系统的全面重做，采用自适应双轨混合架构（TWThreat API 服务端直读 + 本地战斗日志推演）。本文档定义 Nanami-Plates 姓名板插件需要对接的数据接口、渲染要求和交互规范。
|
||
|
||
---
|
||
|
||
## 一、数据接口
|
||
|
||
### 1.1 全局引用
|
||
|
||
```lua
|
||
local TE = NanamiDPS.ThreatEngine -- 仇恨引擎实例
|
||
local TC = NanamiDPS.ThreatCoefficients -- 系数常量
|
||
```
|
||
|
||
### 1.2 核心 API 函数
|
||
|
||
| 函数签名 | 返回值 | 说明 |
|
||
|----------|--------|------|
|
||
| `TE:GetActiveTargetKey()` | `string` 或 `nil` | 获取当前激活目标的唯一键（优先API目标键，回退到本地目标） |
|
||
| `TE:GetCurrentTargetKey()` | `string` 或 `nil` | 获取玩家当前 target 的唯一键 |
|
||
| `TE.GetTargetKey(unitID)` | `string` 或 `nil` | 根据 unitID 计算目标唯一键（格式: `G:GUID` / `I:RaidIcon` / `V:Name:MaxHP`） |
|
||
| `TE:GetThreatList(targetKey)` | `table` | 返回按仇恨降序排列的列表，每项包含 `{name, threat, tps, perc, isTanking, isMelee, relativePercent}` |
|
||
| `TE:GetOTStatus(targetKey)` | `table` | 返回当前玩家的 OT 分析: `{safe, pct, threshold, otPoint, buffer, myThreat, tankThreat, tankName, isMelee}` |
|
||
| `TE:IsAPIActiveForTarget(targetKey)` | `boolean` | 判断该目标是否使用服务端 API 数据（精确模式） |
|
||
| `TE.IsEliteOrBoss(unitID)` | `boolean` | 判断目标是否为精英/Boss |
|
||
| `TE.IsInGroup()` | `boolean` | 判断玩家是否在小队/团队中 |
|
||
|
||
### 1.3 状态字段（只读）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `TE.inCombat` | `boolean` | 当前是否在战斗中 |
|
||
| `TE.apiActive` | `boolean` | API 直读引擎是否激活 |
|
||
| `TE.playerName` | `string` | 当前玩家名称 |
|
||
| `TE.playerClass` | `string` | 当前玩家职业 token（大写） |
|
||
| `TE.targets` | `table` | 三维数据表，结构见下文 |
|
||
|
||
### 1.4 三维数据结构
|
||
|
||
```
|
||
TE.targets[targetKey] = {
|
||
players = {
|
||
[playerName] = {
|
||
threat = number, -- 绝对仇恨值
|
||
tps = number, -- 每秒仇恨制造率
|
||
isTanking = boolean, -- 是否持有仇恨
|
||
isMelee = boolean, -- 是否在近战范围
|
||
perc = number, -- 相对百分比 (0-100)
|
||
history = table, -- TPS 计算用历史数据
|
||
lastThreatTime = number, -- 最后一次仇恨更新时间
|
||
},
|
||
...
|
||
},
|
||
tankName = string, -- 当前坦克名称
|
||
tankThreat = number, -- 坦克仇恨值
|
||
lastUpdate = number, -- 最后更新时间戳
|
||
source = string, -- "api" | "api_tm" | "local"
|
||
}
|
||
```
|
||
|
||
### 1.5 回调注册
|
||
|
||
```lua
|
||
-- 仇恨数据更新时触发（API 报文到达或本地计算完成）
|
||
NanamiDPS:RegisterCallback("threat_update", "NanamiPlates", function()
|
||
-- 在此刷新姓名板仇恨显示
|
||
end)
|
||
```
|
||
|
||
### 1.6 OT 阈值常量
|
||
|
||
```lua
|
||
TC.OT_MELEE_THRESHOLD = 1.10 -- 近战 110%
|
||
TC.OT_RANGED_THRESHOLD = 1.30 -- 远程 130%
|
||
```
|
||
|
||
---
|
||
|
||
## 二、姓名板渲染要求
|
||
|
||
### 2.1 仇恨百分比指示器
|
||
|
||
**位置**: 锚定在每个敌方姓名板的名称文字正上方或正下方
|
||
**格式**: `XX%` 数字文本，字号 10-12
|
||
**更新频率**: 跟随 `threat_update` 回调，约 0.5 秒一次
|
||
|
||
### 2.2 颜色渐变规则
|
||
|
||
根据玩家在当前目标上的仇恨百分比（相对于 OT 阈值）分级着色：
|
||
|
||
| 百分比区间 | 颜色 | 含义 |
|
||
|-----------|------|------|
|
||
| 0% - 49% | 绿色 `(0.2, 1.0, 0.2)` | 安全 |
|
||
| 50% - 79% | 黄色 `(1.0, 1.0, 0.0)` | 警戒 |
|
||
| 80% - 100%+ | 红色 `(1.0, 0.2, 0.0)` | 危险，即将 OT |
|
||
|
||
### 2.3 仇恨条背景色
|
||
|
||
为已持有仇恨（`isTanking = true`）的目标姓名板生命条添加边框高亮：
|
||
- 坦克视角: 正在坦克的怪物边框为**绿色**
|
||
- DPS/治疗视角: 自己正在被攻击的怪物边框为**红色**
|
||
|
||
### 2.4 数据来源标识（可选）
|
||
|
||
在仇恨百分比旁边显示小图标区分数据来源：
|
||
- API 数据: 小圆点 (绿色) — 表示服务端精确数据
|
||
- 本地推算: 小圆点 (灰色) — 表示基于战斗日志估算
|
||
|
||
---
|
||
|
||
## 三、Tank Mode 姓名板增强
|
||
|
||
当玩家为坦克角色（防御姿态/巨熊形态）时：
|
||
|
||
### 3.1 多目标仇恨概览
|
||
|
||
在每个姓名板上显示**仇恨排名第二**的玩家名称和百分比，格式：
|
||
|
||
```
|
||
[怪物名称]
|
||
██████████████ 100% ← 仇恨条（自己）
|
||
紧随: Mage_A 85% ← 第二名信息
|
||
```
|
||
|
||
### 3.2 松动目标高亮
|
||
|
||
如果某个怪物上的第二名仇恨超过坦克仇恨的 80%（接近 110% OT 线），该姓名板整体加红色闪烁边框，提示坦克需要立即补仇恨技能。
|
||
|
||
### 3.3 快速目标切换（SuperWoW 依赖）
|
||
|
||
如果检测到 SuperWoW/SuperAPI 可用：
|
||
- 姓名板上的仇恨区域可点击
|
||
- 点击后调用 `TargetUnit` 或 `SetTarget` 切换到该怪物
|
||
- 方便坦克无需 TAB 键即可快速切换目标
|
||
|
||
---
|
||
|
||
## 四、Healer Mode 姓名板增强
|
||
|
||
当玩家为治疗角色时：
|
||
|
||
### 4.1 主坦锁定
|
||
|
||
允许设置一个"主坦克焦点"（通过 `/nanami mt [name]` 或右键团队框架）
|
||
|
||
### 4.2 未稳固目标标记
|
||
|
||
在姓名板上对**主坦克仇恨不是最高**的怪物添加特殊标记（橙色感叹号），提示治疗者该怪物仇恨不稳定，可能随时转向治疗者。
|
||
|
||
---
|
||
|
||
## 五、性能要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| 姓名板遍历频率 | 最大 0.5 秒一次（跟随 `threat_update` 回调） |
|
||
| 内存开销 | 单个姓名板附加元素不超过 3 个 FontString + 1 个 Texture |
|
||
| 不可见姓名板 | 必须隐藏对应的仇恨指示器，避免孤立 UI 元素 |
|
||
| 战斗外 | 所有仇恨指示器隐藏，不做任何查询 |
|
||
| 数据清理 | 离开战斗后清除所有姓名板附加元素 |
|
||
|
||
---
|
||
|
||
## 六、对接代码示例
|
||
|
||
```lua
|
||
-- Nanami-Plates 中的对接示例
|
||
|
||
local TE = NanamiDPS and NanamiDPS.ThreatEngine
|
||
local TC = NanamiDPS and NanamiDPS.ThreatCoefficients
|
||
|
||
-- 获取某个 nameplate 对应怪物的玩家仇恨百分比
|
||
local function GetMyThreatPct(unitID)
|
||
if not TE or not TE.inCombat then return nil end
|
||
|
||
local targetKey = TE.GetTargetKey(unitID)
|
||
if not targetKey then return nil end
|
||
|
||
local td = TE.targets[targetKey]
|
||
if not td then return nil end
|
||
|
||
local pd = td.players[TE.playerName]
|
||
if not pd then return nil end
|
||
|
||
return pd.perc, pd.isTanking, pd.isMelee
|
||
end
|
||
|
||
-- 获取该怪物仇恨第二名
|
||
local function GetSecondThreat(unitID)
|
||
if not TE or not TE.inCombat then return nil end
|
||
|
||
local targetKey = TE.GetTargetKey(unitID)
|
||
if not targetKey then return nil end
|
||
|
||
local list = TE:GetThreatList(targetKey)
|
||
if list and list[2] then
|
||
return list[2].name, list[2].perc, list[2].threat
|
||
end
|
||
return nil
|
||
end
|
||
|
||
-- 注册回调
|
||
if NanamiDPS then
|
||
NanamiDPS:RegisterCallback("threat_update", "NanamiPlates_Threat", function()
|
||
-- 遍历所有可见姓名板，刷新仇恨数据
|
||
NanamiPlates:RefreshAllThreatIndicators()
|
||
end)
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 七、版本兼容性
|
||
|
||
- **必须依赖**: Nanami-DPS >= 1.0.0（含 ThreatEngine 模块）
|
||
- **可选依赖**: SuperWoW / SuperAPI（用于姓名板高级交互）
|
||
- **WoW 客户端**: 1.12.x (Turtle WoW)
|
||
- **Lua 环境**: 不支持现代 Lua 特性（使用 `table.getn` 代替 `#`，`pairs` 代替 `next`）
|