8.4 Standard Library: Game Data

Modules for querying game data that work the same across flavors. Each module selects the best available client API at compile time in split flavor mode, and with a runtime check in shared mode. Availability comes from the flavor table. When a client lacks an API and the module has no fallback, using the affected function for that flavor is error E8300. When a fallback with reduced functionality is used, warning W8301 lists the missing fields.

All modules respect secret values (Types §2.11): values that the client may return as secrets are typed T | Secret<T> and are passed through unchanged. The modules never compare, index or do arithmetic on them internally. Where a function needs such an operation (e.g. matching a spell ID), it skips values it cannot access and says so in its contract.

secret

wowlua:secret holds the small helpers secret values need (decision S26). Each tests for secrecy first, so it never compares, tests or does arithmetic on a secret. On clients without secret values nothing is secret.

import * as secret from "wowlua:secret" local hp = UnitHealth("target")                       -- number | Secret<number>bar:SetValue(secret.amount(hp))                       -- secrets pass, nil becomes 0local shown = secret.known(hp, 0)                     -- number: 0 when secretif secret.flag(UnitIsUnit("target", "focus")) then … end   -- a secret boolean reads as falseif not secret.isSecret(hp) then print(hp + 1) end     -- narrows like issecretvalue

The generated wow-api declarations type the arguments Blizzard documents with SecretArguments = "AllowedWhenTainted" (widget setters such as StatusBar:SetValue, FontString:SetText) as T | Secret<T>, except those marked NeverSecret.

unit

wowlua:unit provides unit information helpers.

import * as unit from "wowlua:unit"import * as color from "wowlua:color" local info = unit.info("target")                 -- UnitInfo?if info then    label:SetText(color.wrap(info.name, unit.classColor("target")))end local hp, maxHp = unit.health("target")           -- number | Secret<number> eachbar:SetMinMaxValues(0, maxHp)bar:SetValue(hp)                                  -- widget setters accept secrets for token in unit.group({ includePlayer = true }) do    refreshRow(token)end

The client's newer APIs (UnitHealthPercent, GetUnitName) are detected at run time in every flavor mode; the result is the same as a compile-time choice.

Roster

unit.roster keeps the group's members (the player included) by GUID and reports who joins and leaves.

const m = unit.roster.byGuid(sourceGuid)            -- RosterMember?if m then print(m.fullName, m.unit) endunit.roster.onChange(function(joined: RosterMember[], left: RosterMember[])    for _, m in ipairs(joined) do print(`{m.name} joined`) endend)

Semantics (decision S34):

• Lazy. The roster starts on first use: it registers GROUP_ROSTER_UPDATE, PLAYER_ENTERING_WORLD and UNIT_NAME_UPDATE, and the group at that moment counts as already there (no joins are reported for it).
• Coalesced. A burst of roster events rebuilds once, 0.2 seconds after the first. A query while a rebuild is pending rebuilds first, so queries are always current.
• Moves are not changes. A member whose unit token changes (party to raid, a raid reshuffle) keeps their entry with the new token.
• Secrets. A member whose GUID reads as secret keeps the last known entry for that unit token; one never seen is left out until it can be read.

aura

wowlua:aura reads auras and wraps the engine's aura containers. On clients with secret auras (retail 12.x, WoW: Forever) every addon read of auras errors in combat ("cannot be accessed when secret while tainted"), in the open world too. The reads here are guarded and find nothing then; the engine's aura containers are the way to show auras in combat: the engine fills them, the addon only styles their buttons (decision S26).

import * as aura from "wowlua:aura" if aura.readable("player") then    for a in aura.each("player", "HELPFUL") do        print(a.name, a.applications)    endend local debuff = aura.find("target", 589, "HARMFUL|PLAYER")    -- AuraData? local sub = aura.onChange("player", function(u: UnitToken, changes: UnitAuraUpdateInfo?)    if changes == nil or changes.isFullUpdate then rescan() else applyDelta(changes) endend) -- Shown in combat too: the engine matches filters and spell lists itself.local box = aura.container(frame, {    unit = "target",    groups = {        { key = "mine", filter = "HARMFUL|PLAYER", max = 8 },        { key = "curses", filter = "HARMFUL", dispelTypes = { "Curse" } },        { key = "tracked", filter = "HELPFUL", spells = { 1459, 21562 } },    },    size = 26,    growth = { "LEFT", "DOWN" },})

• AuraData is the type the flavor's wow-api declarations give C_UnitAuras aura data. Every flavor has C_UnitAuras, so no legacy UnitAura fallback is needed. On clients with secret auras its fields may be secret; the module never compares them.
• AuraFilter is a string of |-separated words. Each flavor's words come from its client's AuraUtil.AuraFilters, extracted into the AuraFilterWord type of its wow-api declarations (decision S27; ! negation where the flavor has it). Literal filters are checked for every targeted flavor (E8310); container groups' filters too.
• The default button (no initialize) looks like the client's buffs (decisions S17, S28): the icon, the stack count at the bottom right, the engine's duration text below the icon, a debuff-type border on harmful auras, and right click cancels the player's own buffs.
• Engine calls are guarded: an error inside one would abort the engine's whole button batch. Layout methods renamed between client builds (SetFlowLayout…/SetAuraLayout…) are tried in turn.
• Iteration stops at the first missing index, matching the client APIs.

spell

wowlua:spell provides spell information across C_Spell and the legacy global functions.

import * as spell from "wowlua:spell" local s = spell.info(133)            -- SpellInfo?if s then icon:SetTexture(s.iconID) endlocal cd = spell.cooldown(133)       -- SpellCooldownInfo?

item

wowlua:item loads and caches item and spell data asynchronously. WoW loads item and spell data from the server lazily. The first query for an uncached item returns nil, and the data arrives later.

import * as item from "wowlua:item" item.load(19019, function(data: ItemData?)    if data then print(data.link, data.itemLevel) endend) local cached = item.get(19019)                   -- ItemData? (nil and starts loading if uncached) item.loadMany({ 19019, 17182 }, function(all: { [number]: ItemData? }) … end) item.loadSpell(133, function(ok: boolean) print(spell.description(133)) end) -- inside a wowlua:jobs joblocal info = item.await(ctx, 19019)              -- yields until loaded

Implementation: C_Item.RequestLoadItemDataByID and C_Spell.RequestLoadSpellData, answered by ITEM_DATA_LOAD_RESULT (or GET_ITEM_INFO_RECEIVED) and SPELL_DATA_LOAD_RESULT; every flavor's client has them, so no item or spell mixins are needed. Concurrent loads of the same item (and gets while it loads) share one request. Loaded ItemData records are cached per addon. The cache holds at most item.configure({ cacheSize = 500 }) entries, with least-recently-used eviction. Callbacks run through the stdlib error policy (Infrastructure: errors).

tooltip

wowlua:tooltip provides typed post-hooks for tooltips. On clients with the tooltip data system it uses TooltipDataProcessor.AddTooltipPostCall, and elsewhere it hooks the OnTooltipSet* scripts of the standard tooltips.

import onTooltip from "wowlua:tooltip"import * as tooltip from "wowlua:tooltip" @onTooltip("Item")local function addItemLevel(tip: GameTooltip, data: TooltipData)    local info = item.get(data.id :: number)    if info then tip:AddLine(`iLvl {info.itemLevel}`, 1, 1, 1) endend local h = tooltip.hook("Unit", function(tip: GameTooltip, data: TooltipData) … end)h:disable()                          -- hooks cannot be removed; this stops calling the handlertooltip.attach(MyAddonTooltip)       -- also apply hooks to a custom tooltip (fallback clients)

• Fallback clients hook GameTooltip, ItemRefTooltip and the shopping tooltips with HookScript, reading the item, spell or unit with the tooltip's getter methods.
• Handlers run through the stdlib error policy. A failing handler never breaks the tooltip or other handlers.
• With the data system, forbidden tooltips (tip:IsForbidden()) are skipped. TooltipHook is a class; hooks run in registration order.
• These are post-hooks only. They cannot suppress or replace tooltip content.

Testing

wowlua:mock support used by this chapter: mock.setUnit, mock.setGroup, mock.secret(v) / mock.setRestricted(bool) (secret simulation for issecretvalue / canaccessvalue), mock.setAuras(unit, auras), mock.fireUnitAura(unit, changes?), mock.setSpell(id, info), mock.setSpellCooldown(id, info), mock.setItem(id, info, { cached?, delay? }) (data arrives after mock.advanceTime), and mock.showTooltip(kind, data), which runs post-hooks against a stub GameTooltip whose added lines can be read back with tip:lines().