Addon API

Addons are small Lua scripts that change your UI. You can add unit frames, meters and chat filters, or move and hide parts of the HUD. They can't play the game for you.

API version 1 ยท Last updated October 21 2026

What addons can do
Install an addon
addon.json
The language
Limits
Frames
Units
Buffs, bags, gold, time
The game's HUD
Chat filters
Events
Saved variables
Examples

What addons can do

An addon can:

An addon can't:

Addons must be free. No paid addons and no paid features. Using an addon won't get you banned. Editing the game files or injecting code will, addon or not.

Only install addons from people you trust. The Addons menu shows a fingerprint for each addon so you can check it matches what the author posted.

Install an addon

  1. Each addon is one folder with an addon.json and its .lua files.
  2. Put the folder in Documents\Primordial\Addons\. The folder name is the addon's id.
  3. Open Addons (the small link under your character list, or Settings → Interface), tick it, and press Reload UI.

Addons are off until you turn them on. If one breaks your UI, start the game with -noaddons to turn them all off.

addon.json

{
  "id": "SelfMeter",              // must match the folder name: letters, digits, _
  "name": "Self Meter",
  "version": "1.0.0",
  "author": "You",
  "api": 1,                       // the API version it was written for
  "files": ["meter.lua"],         // loaded in this order
  "saved": ["SelfMeterDB"],       // globals kept between sessions
  "notes": "One line shown in the Addons menu."
}

An addon written for another API version shows as Out of date and stays off unless you tick Load out of date addons.

The language

Addons are written in Lua 5.4. The full language works.

Some library functions are removed: io, os, debug, package/require, load/dofile/loadfile, coroutine, utf8, collectgarbage, getmetatable/setmetatable, rawget/rawset/rawequal/rawlen, xpcall, string.dump/pack/unpack, string patterns (gsub, match, gmatch), math.randomseed. Scripts load from source only, not bytecode.

LibraryFunctions
basetype tostring tonumber pairs ipairs next select unpack error assert pcall print _G _VERSION
stringlen upper lower sub rep reverse byte char format, find (plain text only), and ours: replace(s, old, new) (plain text), split(s, sep), trim(s). Strings have methods: s:upper()
tableinsert remove concat sort move pack unpack, and ours: wipe(t)
matheverything except randomseed

Each addon runs in its own Lua state, so addons can't see or change each other.

Limits

If an addon goes over a limit it gets stopped and your chat says why. Tick it and press Reload UI to try again.

LimitValue
Lua instructions per frame150,000 per addon (1,000,000 while loading)
CPU time4 ms in any one frame, 1 ms per frame on average over 5 s
Memory4 MB per addon
Frames200 per addon
Errors10 in 10 seconds stops the addon
OnUpdateat most 30 times a second
GetTime()tenths of a second
Print5 lines a second
Files32 per addon, 256 KB each, 1 MB in total
Addons50
Saved variables256 KB per addon per character

The Addons menu shows how much CPU and memory each addon uses.

Frames

CreateFrame(kind, name, parent) makes a frame. kind is "frame" (a box), "text" or "bar". name is optional (needed for SetMovable). A child is placed and scaled inside its parent and hides with it.

The screen is 1080 units tall. The width depends on your screen shape, use GetScreenSize() to get it. x goes right and y goes up.

MethodWhat it does
f:SetPoint(point, x, y)
f:SetPoint(point, relPoint, x, y)
Puts the frame's point on its parent's relPoint (default the same), moved by x, y. Points: TOPLEFT TOP TOPRIGHT LEFT CENTER RIGHT BOTTOMLEFT BOTTOM BOTTOMRIGHT
f:SetSize(w, h) f:SetWidth(w) f:SetHeight(h)Size. A text frame with no size fits its text.
f:GetWidth() f:GetHeight()Size as laid out.
f:SetBackdrop(r, g, b, a)Fill colour (0 to 1).
f:SetBorder(r, g, b, a)A thin border.
f:SetText(s) f:GetText()Text on a text frame or over a bar.
f:SetTextColor(r, g, b, a) f:SetFontSize(n) f:SetJustify("LEFT"|"CENTER"|"RIGHT") f:SetOutline(bool)Text look (size 8 to 48).
f:SetValue(value, max)A bar's fill.
f:SetBarColor(r, g, b, a) f:SetBarBackground(r, g, b, a)A bar's colours.
f:Show() f:Hide() f:SetShown(bool) f:IsShown()Visibility.
f:SetAlpha(a) f:SetScale(s)Opacity, scale (0.25 to 4), passed on to children.
f:SetMovable(true)You can drag it with the mouse and its spot is saved. Only you can move it, not the script.
f:RegisterEvent(e) f:UnregisterEvent(e) f:UnregisterAllEvents()Listen to events.
f:SetScript("OnEvent", fn)fn(self, event, ...)
f:SetScript("OnUpdate", fn)fn(self, elapsed), up to 30 times a second while shown.
f:GetName()Its name.

Frames are tables too: f.label = CreateFrame("text", nil, f) and function f:Refresh() ... end work. Frames don't take clicks or key presses, except for dragging a movable one.

Units

Two units exist: "player" (you) and "target" (what you have selected).

Functionplayertarget
UnitExists(u)true while there is one
UnitName(u)your namename, title
UnitLevel(u)level
UnitHealth(u) UnitHealthMax(u)life and maxlife as a percent (0 to 100), max 100, as the target frame shows it
UnitPower(u) UnitPowerMax(u)Aether and maxnil
UnitReaction(u)"friendly""hostile", "friendly" or "neutral"
UnitIsElite(u) UnitIsDead(u)true or false
UnitSchool(u)"water", "fire", "wind", "earth", "sun" or "shadow"nil
UnitXP(u) UnitXPMax(u)experience and next levelnil
UnitAffectingCombat(u)in combatfalse

InCombatLockdown() is true while you fight.

Buffs, bags, gold, time

FunctionReturns
GetBuffs()Your buffs: a list of { kind, skill, school, left, total } (seconds, tenths)
GetBagItems()Your items: a list of { name, rarity, count, where } (where is "bag" or the equip slot)
GetGold()Your gold
GetTime()Seconds since you entered the world (tenths)
GetScreenSize()width, 1080
Print(...)A line in your chat, tagged with the addon's name. Only you see it.
ADDON_ID ADDON_VERSION API_VERSIONConstants

The game's HUD

HudElement(id) gives a handle to one piece of the game's HUD: orbs, player_frame, action_bar, minimap, tracker, chat, buffs, cast_bar.

local frame = HudElement("player_frame")
frame:Hide()              -- or :Show()
HudElement("minimap"):SetScale(0.8)            -- 0.5 to 2
HudElement("action_bar"):SetOffset(0, 40)     -- x right, y up

During combat these changes wait and apply when the fight ends.

Chat filters

AddChatFilter(fn) hides chat lines for you only. fn(channel, from, text, isSelf) returns true to hide the line. System lines always show. Up to 8 filters.

AddChatFilter(function(channel, from, text)
  return text:lower():find("cheap gold") ~= nil
end)

Events

EventArguments after (self, event)
ADDON_LOADEDaddon id
PLAYER_ENTERING_WORLD
UNIT_HEALTH UNIT_POWERunit
PLAYER_TARGET_CHANGED
PLAYER_XP_UPDATE
PLAYER_LEVEL_UPnew level
UNIT_AURA"player"
BAG_UPDATE PLAYER_MONEY
CHAT_MSGchannel, from, text, isSelf
COMBAT_DAMAGE_DEALTamount, crit, dot, school, target name (your own hits only)
COMBAT_DAMAGE_TAKENamount
PLAYER_REGEN_DISABLED PLAYER_REGEN_ENABLEDcombat starts, combat ends

Saved variables

List the globals you want kept under "saved" in addon.json. They're loaded before your files run. They're written when you leave the world and every 5 minutes. Numbers, strings, booleans and tables of those get saved. Functions and frames don't. The file stays on your PC, one per character.

MyAddonDB = MyAddonDB or { scale = 1 }

Examples

Both come with the game's addon examples. Copy a folder into your Addons folder to try one.

Unit Frames

A compact player frame (life, Aether coloured by school) and target frame (life share coloured by reaction). Hides the stock player frame. Drag either one.

local function MakeUnitFrame(name, unit, x, y)
  local f = CreateFrame("frame", name)
  f:SetSize(240, unit == "player" and 64 or 50)
  f:SetPoint("BOTTOM", x, y)
  f:SetBackdrop(0.05, 0.04, 0.03, 0.78)
  f:SetBorder(0.84, 0.69, 0.38, 0.55)
  f:SetMovable(true)

  f.title = CreateFrame("text", nil, f)
  f.title:SetPoint("TOPLEFT", 8, -5)
  f.hp = CreateFrame("bar", nil, f)
  f.hp:SetSize(224, 16)
  f.hp:SetPoint("TOPLEFT", 8, -26)
  f.hp:SetJustify("CENTER")

  function f:Refresh()
    if not UnitExists(unit) then self:Hide() return end
    self:Show()
    self.title:SetText(UnitName(unit))
    self.hp:SetValue(UnitHealth(unit), UnitHealthMax(unit))
    if unit == "target" then
      self.hp:SetText(string.format("%d%%", UnitHealth(unit)))
    end
  end

  f:RegisterEvent("PLAYER_ENTERING_WORLD")
  f:RegisterEvent("UNIT_HEALTH")
  f:RegisterEvent("PLAYER_TARGET_CHANGED")
  f:SetScript("OnEvent", function(self, event, u)
    if u == nil or u == unit then self:Refresh() end
  end)
  return f
end

MakeUnitFrame("UnitFramesPlayer", "player", -170, 190)
MakeUnitFrame("UnitFramesTarget", "target", 170, 190)
HudElement("player_frame"):Hide()

Self Meter

Your own damage this fight: total, damage per second, biggest hit, crit share and a bar per school. It only ever sees your own hits.

SelfMeterDB = SelfMeterDB or { bestDps = 0 }
local fight = { total = 0, hits = 0, crits = 0, start = nil, last = 0, by = {} }

local f = CreateFrame("frame", "SelfMeterMain")
f:SetSize(220, 132)
f:SetPoint("RIGHT", -24, -60)
f:SetBackdrop(0.05, 0.04, 0.03, 0.78)
f:SetMovable(true)
local dps = CreateFrame("text", nil, f)
dps:SetPoint("TOPRIGHT", -8, -5)

f:RegisterEvent("COMBAT_DAMAGE_DEALT")
f:RegisterEvent("PLAYER_REGEN_DISABLED")
f:RegisterEvent("PLAYER_REGEN_ENABLED")
f:SetScript("OnEvent", function(self, event, amount, crit, dot, school)
  if event == "COMBAT_DAMAGE_DEALT" then
    local now = GetTime()
    fight.start = fight.start or now
    fight.last = now
    fight.total = fight.total + amount
    fight.by[school] = (fight.by[school] or 0) + amount
    dps:SetText(string.format("%.0f dps", fight.total / math.max(1, fight.last - fight.start)))
  elseif event == "PLAYER_REGEN_DISABLED" then
    fight = { total = 0, hits = 0, crits = 0, start = nil, last = 0, by = {} }
  end
end)

These are shortened. The full files come with the game's addon examples.

Want something added to the API? Ask on the forum or Discord. We won't add anything that gives an edge in a fight, like timers, trackers or automation.