Lua API & C_ Namespaces¶

-- Create a simple frame
local frame = CreateFrame("Frame", "MyAddonFrame", UIParent, "BackdropTemplate")
frame:SetSize(200, 100)
frame:SetPoint("CENTER")

-- Create a button from a template
local btn = CreateFrame("Button", nil, frame, "UIPanelButtonTemplate")
btn:SetSize(120, 25)
btn:SetText("Click Me")
btn:SetPoint("CENTER")
btn:SetScript("OnClick", function(self)
    print("Button clicked!")
end)

-- strsplit returns multiple values, not a table
local cmd, arg1, rest = strsplit(" ", msg, 3)

-- strjoin
local path = strjoin("/", "Interface", "AddOns", addonName)

-- strtrim
local cleaned = strtrim("  hello  ") -- "hello"

-- wipe reuses the table allocation
local cache = {}
-- ... fill cache ...
wipe(cache) -- clears it without creating garbage

-- tContains for membership checks
local validTypes = {"warrior", "mage", "priest"}
if tContains(validTypes, playerClass) then
    -- handle
end

-- tInvert for reverse lookups
local lookup = tInvert(validTypes)
-- lookup = { warrior = 1, mage = 2, priest = 3 }

-- CopyTable for safe defaults
local db = CopyTable(defaults)

-- Define a mixin
local HealthBarMixin = {}

function HealthBarMixin:Init(unit)
    self.unit = unit
    self:Update()
end

function HealthBarMixin:Update()
    local hp = UnitHealth(self.unit)
    local max = UnitHealthMax(self.unit)
    self.bar:SetValue(hp / max)
end

-- Create an instance
local healthBar = CreateFromMixins(HealthBarMixin)
healthBar.bar = CreateFrame("StatusBar", nil, UIParent)
healthBar:Init("player")

-- Or mixin into an existing frame
local frame = CreateFrame("Frame")
Mixin(frame, HealthBarMixin)
frame.bar = frame:CreateTexture()
frame:Init("target")

-- Profile a function
debugprofilestart()
MyExpensiveFunction()
local elapsed = debugprofilestop()
print(format("Took %.2f ms", elapsed))

-- Simple delay
C_Timer.After(2, function()
    print("2 seconds later!")
end)

-- Cancellable one-shot
local timer = C_Timer.NewTimer(5, function()
    print("This may never fire")
end)
timer:Cancel() -- cancel before it fires

-- Repeating ticker
local ticker = C_Timer.NewTicker(1, function()
    print("Every second")
end)

-- Stop it later
C_Timer.After(10, function()
    ticker:Cancel()
end)

-- Limited iterations (fires 5 times then stops)
C_Timer.NewTicker(0.5, function(self)
    print("Tick", self._remainingIterations)
end, 5)

local PREFIX = "MyAddon"
C_ChatInfo.RegisterAddonMessagePrefix(PREFIX)

-- Send a message to the raid
C_ChatInfo.SendAddonMessage(PREFIX, "PULL:10", "RAID")

-- Receive messages via event
function eventHandlers:CHAT_MSG_ADDON(prefix, message, channel, sender)
    if prefix ~= PREFIX then return end

    local cmd, data = strsplit(":", message, 2)
    if cmd == "PULL" then
        local countdown = tonumber(data)
        print(sender .. " is pulling in " .. countdown .. " seconds!")
    end
end

local mapID = C_Map.GetBestMapForUnit("player")
if mapID then
    local info = C_Map.GetMapInfo(mapID)
    print("Current zone:", info.name)

    local pos = C_Map.GetPlayerMapPosition(mapID, "player")
    if pos then
        local x, y = pos:GetXY()
        print(format("Position: %.1f%%, %.1f%%", x * 100, y * 100))
    end
end

-- Safe item info retrieval with async fallback
local function GetItemInfoAsync(itemID, callback)
    if C_Item.IsItemDataCachedByID(itemID) then
        callback(C_Item.GetItemInfo(itemID))
        return
    end

    -- Request load and wait for event
    local item = Item:CreateFromItemID(itemID)
    item:ContinueOnItemLoad(function()
        callback(C_Item.GetItemInfo(itemID))
    end)
end

local info = C_Spell.GetSpellInfo(12345)
if info then
    print(info.name, "cast time:", info.castTime / 1000, "sec")
end

-- Check if another addon is loaded
local loaded = C_AddOns.IsAddOnLoaded("Details")
if loaded then
    print("Details is loaded, enabling integration")
end

-- Read your own version from TOC
local version = C_AddOns.GetAddOnMetadata(addonName, "Version")
print(addonName, "v" .. version)

-- Count free bag slots
local freeSlots = 0
for bag = 0, 4 do
    local free = C_Container.GetContainerNumFreeSlots(bag)
    freeSlots = freeSlots + free
end
print("Free bag slots:", freeSlots)

-- Find an item in bags
local function FindItemInBags(targetItemID)
    for bag = 0, 4 do
        for slot = 1, C_Container.GetContainerNumSlots(bag) do
            local itemID = C_Container.GetContainerItemID(bag, slot)
            if itemID == targetItemID then
                return bag, slot
            end
        end
    end
    return nil
end

-- Check if player has a specific buff
local aura = C_UnitAuras.GetPlayerAuraBySpellID(1459) -- Arcane Intellect
if aura then
    print("Arcane Intellect active, expires in", aura.expirationTime - GetTime(), "sec")
end

-- Iterate all debuffs on target
local i = 1
while true do
    local aura = C_UnitAuras.GetAuraDataByIndex("target", i, "HARMFUL")
    if not aura then break end
    print(aura.name, "stacks:", aura.applications, "from:", aura.sourceUnit or "unknown")
    i = i + 1
end

local addonName, ns = ...

-- Register one or more slash command aliases
SLASH_MYADDON1 = "/myaddon"
SLASH_MYADDON2 = "/ma"

SlashCmdList["MYADDON"] = function(msg)
    local cmd, rest = strsplit(" ", msg, 2)
    cmd = (cmd or ""):lower()

    if cmd == "config" or cmd == "options" then
        ns:OpenConfig()
    elseif cmd == "reset" then
        ns:ResetPosition()
        print("|cff00ff00MyAddon:|r Position reset.")
    elseif cmd == "toggle" then
        ns.db.enabled = not ns.db.enabled
        print("|cff00ff00MyAddon:|r " .. (ns.db.enabled and "Enabled" or "Disabled"))
    elseif cmd == "debug" then
        ns.db.debug = not ns.db.debug
        print("|cff00ff00MyAddon:|r Debug " .. (ns.db.debug and "ON" or "OFF"))
    else
        print("|cff00ff00MyAddon|r commands:")
        print("  /ma config  — Open settings")
        print("  /ma toggle  — Enable/disable")
        print("  /ma reset   — Reset position")
        print("  /ma debug   — Toggle debug mode")
    end
end

-- Hook a global function
hooksecurefunc("TargetFrame_Update", function(self)
    -- Runs after every TargetFrame_Update call
    -- self is the same first argument passed to the original
    print("Target frame updated")
end)

-- Hook a method on a specific object
hooksecurefunc(GameTooltip, "SetUnitBuff", function(self, unit, index)
    -- Runs after GameTooltip:SetUnitBuff()
    -- Add extra info to tooltip
    self:AddLine("Custom addon info here", 0.5, 0.8, 1.0)
    self:Show() -- refresh tooltip height
end)

-- Hook ChatFrame to intercept messages
hooksecurefunc(ChatFrame1, "AddMessage", function(self, text, ...)
    -- Runs after every chat message is added
    if text and text:find("pattern") then
        -- do something
    end
end)

local addonName, ns = ...
local PREFIX = "MyAddon" -- max 16 characters

-- Must register before you can receive
C_ChatInfo.RegisterAddonMessagePrefix(PREFIX)

-- chatType: "PARTY", "RAID", "GUILD", "WHISPER", "CHANNEL"
C_ChatInfo.SendAddonMessage(PREFIX, "HELLO:1.0", "PARTY")

-- Whisper to a specific player
C_ChatInfo.SendAddonMessage(PREFIX, "VERSION:1.0", "WHISPER", "PlayerName")

-- Channel (must know the channel number)
C_ChatInfo.SendAddonMessage(PREFIX, data, "CHANNEL", channelNumber)

function eventHandlers:CHAT_MSG_ADDON(prefix, message, channel, sender)
    if prefix ~= PREFIX then return end

    -- Ignore messages from self
    local playerName = UnitName("player")
    if sender == playerName or sender:find(playerName) then return end

    local cmd, data = strsplit(":", message, 2)
    if cmd == "HELLO" then
        -- Respond with our version
        C_ChatInfo.SendAddonMessage(PREFIX, "HELLO:" .. ns.version, channel)
    end
end

local function CreateThrottle(interval)
    local lastCall = 0
    return function(func, ...)
        local now = GetTime()
        if now - lastCall >= interval then
            lastCall = now
            return func(...)
        end
    end
end

-- Usage
local throttledUpdate = CreateThrottle(0.1) -- max 10/sec
frame:SetScript("OnUpdate", function(self, elapsed)
    throttledUpdate(function()
        -- expensive work here
    end)
end)

local function CreateDebounce(delay)
    local timer = nil
    return function(func)
        if timer then
            timer:Cancel()
        end
        timer = C_Timer.NewTimer(delay, function()
            timer = nil
            func()
        end)
    end
end

-- Usage: only update after user stops typing for 0.3s
local debouncedSearch = CreateDebounce(0.3)
editBox:SetScript("OnTextChanged", function(self)
    local text = self:GetText()
    debouncedSearch(function()
        ns:PerformSearch(text)
    end)
end)

local function DeepEqual(a, b)
    if type(a) ~= type(b) then return false end
    if type(a) ~= "table" then return a == b end

    for k, v in pairs(a) do
        if not DeepEqual(v, b[k]) then return false end
    end
    for k in pairs(b) do
        if a[k] == nil then return false end
    end
    return true
end

local pendingActions = {}

local function ExecuteOrQueue(action)
    if InCombatLockdown() then
        table.insert(pendingActions, action)
    else
        action()
    end
end

function eventHandlers:PLAYER_REGEN_ENABLED()
    for _, action in ipairs(pendingActions) do
        action()
    end
    wipe(pendingActions)
end

-- Usage
ExecuteOrQueue(function()
    -- This involves protected operations (e.g., SetAttribute)
    mySecureButton:SetAttribute("macrotext", "/cast Fireball")
end)

local function AddonPrint(...)
    local prefix = "|cff00ccff[MyAddon]|r "
    print(prefix, ...)
end

-- Color codes: |cffRRGGBB starts color, |r resets
-- Common colors:
--   |cffff0000  red         |cff00ff00  green
--   |cff00ccff  light blue  |cffffff00  yellow
--   |cffff8800  orange      |cffff00ff  pink