235 lines
5.9 KiB
Markdown
235 lines
5.9 KiB
Markdown
# Nanami-Plates 姓名板仇恨查询 API 文档
|
||
|
||
## 快速开始
|
||
|
||
```lua
|
||
-- 检查 Nanami-DPS 是否加载
|
||
local TE = NanamiDPS and NanamiDPS.ThreatEngine
|
||
if not TE then return end
|
||
```
|
||
|
||
---
|
||
|
||
## API 1: QueryUnitThreat(unitID)
|
||
|
||
查询指定单位的仇恨信息（以当前玩家视角）。
|
||
|
||
### 签名
|
||
|
||
```lua
|
||
local data = NanamiDPS.ThreatEngine:QueryUnitThreat(unitID)
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `unitID` | `string` | WoW 单位 ID，如 `"target"`, `"mouseover"`, `"nameplate1"` 等 |
|
||
|
||
### 返回值
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `pct` | `number` | 当前玩家的仇恨百分比 (0-100，相对于最高仇恨者) |
|
||
| `threat` | `number` | 当前玩家的绝对仇恨值 |
|
||
| `tankName` | `string` | 当前坦克（最高仇恨者）名称 |
|
||
| `tankThreat` | `number` | 坦克的绝对仇恨值 |
|
||
| `isTanking` | `boolean` | 当前玩家是否持有仇恨 |
|
||
| `isMelee` | `boolean` | 当前玩家是否在近战范围 |
|
||
| `source` | `string` | 数据来源: `"api"` (服务端精确) / `"local"` (本地估算) |
|
||
| `secondName` | `string` | 仇恨第二名的名称 |
|
||
| `secondPct` | `number` | 第二名的仇恨百分比 |
|
||
| `secondThreat` | `number` | 第二名的绝对仇恨值 |
|
||
|
||
如果非战斗状态、单位不存在或无仇恨数据，返回 `nil`。
|
||
|
||
### 用法示例
|
||
|
||
```lua
|
||
local function GetNameplateThreatColor(unitID)
|
||
local TE = NanamiDPS and NanamiDPS.ThreatEngine
|
||
if not TE then return nil end
|
||
|
||
local data = TE:QueryUnitThreat(unitID)
|
||
if not data then return nil end
|
||
|
||
local pct = data.pct
|
||
if pct >= 80 then
|
||
return 1, 0.2, 0 -- 红色: 即将 OT
|
||
elseif pct >= 50 then
|
||
return 1, 1, 0 -- 黄色: 警戒
|
||
else
|
||
return 0.2, 1, 0.2 -- 绿色: 安全
|
||
end
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## API 2: QueryNameThreat(targetKey, playerName)
|
||
|
||
查询指定玩家在指定目标上的仇恨值。用于需要查看任意玩家（而非自己）仇恨的场景。
|
||
|
||
### 签名
|
||
|
||
```lua
|
||
local threat, isTanking, pct = NanamiDPS.ThreatEngine:QueryNameThreat(targetKey, playerName)
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `targetKey` | `string` | 目标唯一键，由 `GetTargetKey(unitID)` 生成 |
|
||
| `playerName` | `string` | 玩家名称 |
|
||
|
||
### 返回值
|
||
|
||
| 返回 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `threat` | `number` | 该玩家的绝对仇恨值 |
|
||
| `isTanking` | `boolean` | 该玩家是否持有仇恨 |
|
||
| `pct` | `number` | 百分比 (0-100) |
|
||
|
||
---
|
||
|
||
## API 3: GetTargetKey(unitID)
|
||
|
||
生成目标的唯一标识键。
|
||
|
||
```lua
|
||
local key = NanamiDPS.ThreatEngine.GetTargetKey("target")
|
||
```
|
||
|
||
键格式:
|
||
- `"G:<GUID>"` — 当 UnitGUID 可用时（最准确）
|
||
- `"I:<RaidIcon>"` — 当目标有团队标记时
|
||
- `"V:<Name>:<MaxHP>"` — 通过名称+最大生命值虚拟标识
|
||
|
||
---
|
||
|
||
## API 4: GetThreatList(targetKey)
|
||
|
||
获取指定目标的完整仇恨排行榜。
|
||
|
||
```lua
|
||
local list = NanamiDPS.ThreatEngine:GetThreatList(targetKey)
|
||
```
|
||
|
||
返回按仇恨降序排列的数组，每项:
|
||
|
||
```lua
|
||
{
|
||
name = "PlayerName",
|
||
threat = 12345,
|
||
tps = 500.5,
|
||
perc = 85.3,
|
||
isTanking = false,
|
||
isMelee = true,
|
||
relativePercent = 85.3,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API 5: GetOTStatus(targetKey)
|
||
|
||
获取当前玩家的 OT 风险分析。
|
||
|
||
```lua
|
||
local status = NanamiDPS.ThreatEngine:GetOTStatus(targetKey)
|
||
```
|
||
|
||
返回:
|
||
|
||
```lua
|
||
{
|
||
safe = false, -- 是否安全
|
||
pct = 92.5, -- OT 进度百分比
|
||
threshold = 1.3, -- OT 阈值倍数 (1.1 近战 / 1.3 远程)
|
||
otPoint = 65000, -- 触发 OT 的绝对仇恨值
|
||
buffer = 3750, -- 距离 OT 的缓冲值
|
||
myThreat = 61250, -- 当前玩家仇恨
|
||
tankThreat = 50000, -- 坦克仇恨
|
||
tankName = "TankPlayer",
|
||
isMelee = false,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 回调注册
|
||
|
||
```lua
|
||
-- 仇恨数据更新时触发
|
||
NanamiDPS:RegisterCallback("threat_update", "MyAddon", function()
|
||
-- 在此刷新所有姓名板的仇恨显示
|
||
end)
|
||
```
|
||
|
||
触发频率: 约每 0.5 秒一次（API 报文到达或本地计算完成时）。
|
||
|
||
---
|
||
|
||
## 姓名板集成完整示例
|
||
|
||
```lua
|
||
-- 在姓名板的 OnUpdate 或 threat_update 回调中:
|
||
|
||
local function RefreshNameplateThreat(frame, unitID)
|
||
local TE = NanamiDPS and NanamiDPS.ThreatEngine
|
||
if not TE or not TE.inCombat then
|
||
frame.threatText:SetText("")
|
||
return
|
||
end
|
||
|
||
local data = TE:QueryUnitThreat(unitID)
|
||
if not data then
|
||
frame.threatText:SetText("")
|
||
return
|
||
end
|
||
|
||
-- 显示自己的仇恨百分比
|
||
local pct = data.pct
|
||
local r, g, b = 0.2, 1.0, 0.2
|
||
if pct >= 80 then
|
||
r, g, b = 1.0, 0.2, 0.0
|
||
elseif pct >= 50 then
|
||
r, g, b = 1.0, 1.0, 0.0
|
||
end
|
||
|
||
frame.threatText:SetTextColor(r, g, b)
|
||
frame.threatText:SetText(string.format("%.0f%%", pct))
|
||
|
||
-- Tank Mode: 显示第二名信息
|
||
if data.isTanking and data.secondName then
|
||
frame.secondText:SetText(data.secondName .. " " ..
|
||
string.format("%.0f%%", data.secondPct))
|
||
if data.secondPct >= 80 then
|
||
frame.secondText:SetTextColor(1, 0.2, 0)
|
||
else
|
||
frame.secondText:SetTextColor(0.7, 0.7, 0.7)
|
||
end
|
||
else
|
||
frame.secondText:SetText("")
|
||
end
|
||
|
||
-- 数据来源指示
|
||
if data.source == "api" then
|
||
frame.sourceIndicator:SetVertexColor(0, 1, 0) -- 绿色 = 精确
|
||
else
|
||
frame.sourceIndicator:SetVertexColor(0.5, 0.5, 0.5) -- 灰色 = 估算
|
||
end
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **检查 nil**: 所有 API 在非战斗或无数据时返回 nil/0，调用方必须检查
|
||
2. **性能**: 避免在每帧调用查询 API，建议跟随 `threat_update` 回调或自行节流（0.3-0.5秒）
|
||
3. **数据来源**: `source == "api"` 表示服务端精确数据，`source == "local"` 表示本地估算
|
||
4. **依赖**: 需要 Nanami-DPS >= 1.0.0（含 ThreatEngine）
|
||
5. **兼容性**: WoW 1.12.x Lua 5.0 — 使用 `table.getn` 而非 `#`，使用 `mod()` 而非 `%`
|