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
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:
- Draw frames, bars and text.
- Read what your own UI already shows. That means your life, Aether, experience, buffs, bags and gold, your target's name, level and life percent, and chat.
- Hide, scale or move parts of the game HUD when you're out of combat.
- Hide chat lines for you.
- Save its settings on your PC.
An addon can't:
- Cast, move, target, use items, buy, sell, trade, send chat or run commands. You do every action yourself.
- See anything your UI doesn't show. No positions, ranges, other players' cooldowns, spawn timers or loot tables.
- Touch files, the network or anything else on your PC.
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
- Each addon is one folder with an
addon.jsonand its.luafiles. - Put the folder in
Documents\Primordial\Addons\. The folder name is the addon's id. - 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.
| Library | Functions |
|---|---|
| base | type tostring tonumber pairs ipairs next select unpack error assert pcall print _G _VERSION |
| string | len 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() |
| table | insert remove concat sort move pack unpack, and ours: wipe(t) |
| math | everything 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.
| Limit | Value |
|---|---|
| Lua instructions per frame | 150,000 per addon (1,000,000 while loading) |
| CPU time | 4 ms in any one frame, 1 ms per frame on average over 5 s |
| Memory | 4 MB per addon |
| Frames | 200 per addon |
| Errors | 10 in 10 seconds stops the addon |
OnUpdate | at most 30 times a second |
GetTime() | tenths of a second |
Print | 5 lines a second |
| Files | 32 per addon, 256 KB each, 1 MB in total |
| Addons | 50 |
| Saved variables | 256 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.
| Method | What 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).
| Function | player | target |
|---|---|---|
UnitExists(u) | true while there is one | |
UnitName(u) | your name | name, title |
UnitLevel(u) | level | |
UnitHealth(u) UnitHealthMax(u) | life and max | life as a percent (0 to 100), max 100, as the target frame shows it |
UnitPower(u) UnitPowerMax(u) | Aether and max | nil |
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 level | nil |
UnitAffectingCombat(u) | in combat | false |
InCombatLockdown() is true while you fight.
Buffs, bags, gold, time
| Function | Returns |
|---|---|
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_VERSION | Constants |
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
| Event | Arguments after (self, event) |
|---|---|
ADDON_LOADED | addon id |
PLAYER_ENTERING_WORLD | |
UNIT_HEALTH UNIT_POWER | unit |
PLAYER_TARGET_CHANGED | |
PLAYER_XP_UPDATE | |
PLAYER_LEVEL_UP | new level |
UNIT_AURA | "player" |
BAG_UPDATE PLAYER_MONEY | |
CHAT_MSG | channel, from, text, isSelf |
COMBAT_DAMAGE_DEALT | amount, crit, dot, school, target name (your own hits only) |
COMBAT_DAMAGE_TAKEN | amount |
PLAYER_REGEN_DISABLED PLAYER_REGEN_ENABLED | combat 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.