Nanami-DPS/NanamiPlates-ThreatAPI.md

Nanami-Plates 姓名板仇恨查询 API 文档

快速开始

-- 检查 Nanami-DPS 是否加载
local TE = NanamiDPS and NanamiDPS.ThreatEngine
if not TE then return end

---

API 1: QueryUnitThreat(unitID)

查询指定单位的仇恨信息（以当前玩家视角）。

签名

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。

用法示例

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)

查询指定玩家在指定目标上的仇恨值。用于需要查看任意玩家（而非自己）仇恨的场景。

签名

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)

生成目标的唯一标识键。

local key = NanamiDPS.ThreatEngine.GetTargetKey("target")

键格式:

• "G:<GUID>" — 当 UnitGUID 可用时（最准确）
• "I:<RaidIcon>" — 当目标有团队标记时
• "V:<Name>:<MaxHP>" — 通过名称+最大生命值虚拟标识

---

API 4: GetThreatList(targetKey)

获取指定目标的完整仇恨排行榜。

local list = NanamiDPS.ThreatEngine:GetThreatList(targetKey)

返回按仇恨降序排列的数组，每项:

{
    name = "PlayerName",
    threat = 12345,
    tps = 500.5,
    perc = 85.3,
    isTanking = false,
    isMelee = true,
    relativePercent = 85.3,
}

---

API 5: GetOTStatus(targetKey)

获取当前玩家的 OT 风险分析。

local status = NanamiDPS.ThreatEngine:GetOTStatus(targetKey)

返回:

{
    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,
}

---

回调注册

-- 仇恨数据更新时触发
NanamiDPS:RegisterCallback("threat_update", "MyAddon", function()
    -- 在此刷新所有姓名板的仇恨显示
end)

触发频率: 约每 0.5 秒一次（API 报文到达或本地计算完成时）。

---

姓名板集成完整示例

-- 在姓名板的 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() 而非 %