Lua Environment & Security (Retail — Patch 12.0.0)

Comprehensive reference for the WoW Lua sandbox, security model, taint system, secure execution, timers, hooks, logging, and restricted actions.

Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API Secure Execution: https://warcraft.wiki.gg/wiki/Secure_Execution_and_Tainting Lua Functions: https://warcraft.wiki.gg/wiki/Lua_functions Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only.

Scope

This skill covers:

Lua Sandbox — WoW's Lua 5.1 environment, restricted standard library, blocked functions
Taint System — How addon code becomes tainted and what tainted code cannot do
Secure Execution — Protected functions, secure frames, secure handlers
Combat Lockdown — What addons can and cannot do during combat
C_Timer — Timer functions (After, NewTicker, NewTimer)
Hooks — hooksecurefunc, securecallfunction, securecallmethod
C_RestrictedActions — Addon restriction state queries
C_Log — Logging utilities
FrameScript — Frame script environment, secret values, scrubbing
Debugging — Error handling, stack traces, debugging utilities

When to Use This Skill

Use this skill when you need to:

Understand what Lua functions are available vs blocked in WoW
Work with or debug taint issues
Write code that interacts with secure/protected frames
Use timers, delayed execution, or ticker patterns
Hook existing functions safely
Understand combat lockdown restrictions
Handle addon restriction states (12.0.0 instance restrictions)
Log messages for debugging
Work with secret values and the FrameScript sandbox

WoW Lua 5.1 Sandbox

WoW runs Lua 5.1.4 with significant modifications. The following standard library functions are blocked or removed:

Blocked Standard Functions

Blocked	Reason
`loadfile()`	No filesystem access
`dofile()`	No filesystem access
`io.*`	No filesystem access
`os.execute()`	No shell access
`os.exit()`	Cannot close client
`os.remove()`	No filesystem
`os.rename()`	No filesystem
`os.tmpname()`	No filesystem
`os.getenv()`	No environment access
`package.*`	No package system
`require()`	No module loading
`module()`	No module system
`newproxy()`	Removed
`getfenv()`	Limited — returns read-only
`setfenv()`	Very restricted
`collectgarbage()`	Limited modes

Available Standard Functions

Most core Lua functions work normally:

All string.*, table.*, math.* functions
type(), tostring(), tonumber(), rawget(), rawset(), rawequal(), rawlen()
pairs(), ipairs(), next(), select(), unpack()
pcall(), xpcall(), error(), assert()
setmetatable(), getmetatable()
coroutine.* (full coroutine support)
os.time(), os.date(), os.clock(), os.difftime()
print() — outputs to default chat frame

WoW-Added Global Functions

Function	Description
`strsplit(delimiter, str [, pieces])`	Split string by delimiter
`strsplittable(delimiter, str [, pieces])`	Split to table
`strjoin(delimiter, ...)`	Join strings
`strtrim(str [, chars])`	Trim whitespace
`tContains(table, value)`	Table contains value?
`tInsert(table, value)`	Insert into table (alias)
`tDeleteItem(table, value)`	Remove first occurrence of value
`tInvert(table)`	Invert key/value pairs
`wipe(table)`	Clear table (preserving reference)
`CopyTable(table [, shallow])`	Deep or shallow copy
`MergeTable(dest, source)`	Merge source into dest
`Mixin(object, ...)`	Copy mixin methods to object
`CreateFromMixins(...)`	Create new object from mixins
`CreateAndInitFromMixin(mixin, ...)`	Create + call Init
`format(formatString, ...)`	Alias for string.format
`tostringall(...)`	Convert all args to strings
`DevTools_Dump(value, startKey)`	Dump value for debugging

Taint System

All addon code runs as "tainted" (insecure). Blizzard UI code runs as "secure" (untainted). The taint system prevents addons from calling protected functions or modifying secure frames.

How Taint Works

Any variable set by addon code becomes tainted
Tainted values propagate — if tainted data flows into Blizzard code, it taints that path
Protected functions check taint before executing — they fail if execution path is tainted
Secure frames inherit security from their creation context

Checking Taint

-- Check if a global variable is tainted
local isTainted, source = issecurevariable("SomeGlobalVar")
-- isTainted: false = secure, true = tainted
-- source: string name of the addon that tainted it (or nil if secure)

-- Check table field
local isTainted, source = issecurevariable(someTable, "someKey")

Common Taint Pitfalls

-- WRONG — This taints the Blizzard settings table
Settings.RegisterAddOnCategory = myFunc  -- TAINT!

-- WRONG — Modifying secure frame in insecure context
local btn = PlayerFrame  -- This is a secure Blizzard frame
btn:SetAttribute("type", "spell")  -- TAINT — can cause action blocked errors

-- RIGHT — Use hooksecurefunc for observation without tainting
hooksecurefunc("SomeBlizzardFunction", function(...)
    -- Your code runs AFTER the original — doesn't taint
end)

Secure Execution & Protected Functions

Protected Function Restrictions

Functions marked #protected can only be called from:

Secure (Blizzard) code
Secure click handlers triggered by hardware events
Inside SecureActionButtonTemplate handlers

Protected functions include:

All combat-related casting: CastSpellByName(), CastSpellByID(), UseAction()
Item use: UseItemByName(), UseContainerItem() (in combat)
Target changes: TargetUnit(), AssistUnit(), FocusUnit()
Movement: MoveForwardStart(), JumpOrAscendStart()
UI state: SetAttribute() on secure frames (in combat)

Combat Lockdown

-- Check if in combat lockdown
if InCombatLockdown() then
    -- Cannot: create/destroy secure frames, change secure attributes
    -- Cannot: set points on secure frames, change parent/visibility of secure frames
    -- Can: read attributes, modify non-secure frames, queue changes for later
    return
end

-- Queue changes for after combat
local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_REGEN_ENABLED")
frame:SetScript("OnEvent", function()
    -- Combat ended — safe to modify secure frames now
    DoSecureFrameChanges()
end)

Secure Handlers & Templates

-- SecureActionButtonTemplate — allows protected actions via user clicks
local btn = CreateFrame("Button", "MySecureBtn", UIParent, "SecureActionButtonTemplate")
btn:SetAttribute("type", "spell")
btn:SetAttribute("spell", "Fireball")
-- When clicked by hardware event, this will cast Fireball

-- SecureHandlerBaseTemplate — run secure snippets
local frame = CreateFrame("Frame", nil, UIParent, "SecureHandlerBaseTemplate")
frame:SetAttribute("_onstate-combat", [[
    -- This snippet runs in the secure environment
    if newstate == "combat" then
        self:Hide()
    else
        self:Show()
    end
]])
RegisterStateDriver(frame, "combat", "[combat] combat; nocombat")

State Drivers

-- Register a state driver for automatic secure attribute updates
RegisterStateDriver(frame, "stateName", "conditionalString")
-- e.g., RegisterStateDriver(frame, "visibility", "[combat] hide; show")

UnregisterStateDriver(frame, "stateName")

C_Timer — Timer API

Wiki: https://warcraft.wiki.gg/wiki/API_C_Timer.After

Timer Functions

Function	Returns	Description
`C_Timer.After(seconds, callback)`	—	One-shot timer
`C_Timer.NewTimer(seconds, callback)`	`timer`	Cancellable one-shot timer
`C_Timer.NewTicker(seconds, callback [, iterations])`	`ticker`	Repeating timer

Timer Object Methods

local timer = C_Timer.NewTimer(5, function()
    print("5 seconds elapsed")
end)
timer:Cancel()  -- Cancel before it fires

local ticker = C_Timer.NewTicker(1, function()
    print("Every second")
end, 10)  -- Stop after 10 iterations
ticker:Cancel()  -- Or cancel early

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

Hooks — Function Hooking

hooksecurefunc

The primary safe hooking mechanism. Your hook runs after the original function, without tainting it.

-- Hook a global function
hooksecurefunc("UseAction", function(slot, checkCursor, onSelf)
    print("Action used:", slot)
end)

-- Hook a method on an object
hooksecurefunc(GameTooltip, "SetUnitAura", function(self, ...)
    -- Runs after GameTooltip:SetUnitAura
end)

-- IMPORTANT: You CANNOT prevent the original from executing
-- IMPORTANT: You CANNOT modify the return values
-- IMPORTANT: Your hook does NOT taint the original function

securecallfunction / securecallmethod

-- Call a function in secure context (if possible)
securecallfunction(func, arg1, arg2)

-- Call a method in secure context
securecallmethod(object, "MethodName", arg1, arg2)

C_RestrictedActions — Addon Restriction State

New in 12.0.0. Tracks when addon restrictions are active (e.g., inside instances).

Function	Returns	Description
`C_RestrictedActions.GetAddOnRestrictionState(type)`	`state`	Current restriction state
`C_RestrictedActions.IsAddOnRestrictionActive(type)`	`active`	Is restriction currently active?
`C_RestrictedActions.CheckAllowProtectedFunctions(object [, silent])`	`protectedFunctionsAllowed`	Can object call protected funcs?
`InCombatLockdown()`	`inCombatLockdown`	Combat lockdown active?

Restriction Events

Event	Description
`ADDON_RESTRICTION_STATE_CHANGED`	Restriction state changed (entering/leaving instance)
`PLAYER_REGEN_DISABLED`	Entering combat
`PLAYER_REGEN_ENABLED`	Leaving combat

C_Log — Logging

Function	Description
`C_Log.LogMessage(message)`	Log info message
`C_Log.LogWarningMessage(message)`	Log warning
`C_Log.LogErrorMessage(message)`	Log error
`C_Log.LogMessageWithPriority(priority, message)`	Log with specific priority

Note: ConsolePrint() was removed in 12.0.0. Use C_Log.LogMessage() instead.

FrameScript Functions

WoW provides special FrameScript functions for working with the secure/secret value system:

Function	Returns	Description
`issecurevariable([table,] name)`	`isSecure, taintSource`	Check taint status
`issecretvalue(value)`	`isSecret`	Is value a secret?
`issecrettable(table)`	`isSecretOrContentsSecret`	Is table or contents secret?
`canaccessvalue(value)`	`isAccessible`	Can addon access this value?
`hasanysecretvalues(values)`	`isAnyValueSecret`	Any arg secret?
`scrubsecretvalues(values)`	`scrubbed`	Replace secrets with nil
`secretwrap(values)`	`wrapped`	Wrap values as secrets
`mapvalues(func, values)`	`mapped`	Map function over values (secret-safe)
`securecallfunction(func, ...)`	`results`	Call in secure context
`securecallmethod(obj, method, ...)`	`results`	Call method in secure context
`forceinsecure()`	—	Force insecure execution
`seterrorhandler(handler)`	—	Set global error handler
`geterrorhandler()`	`handler`	Get current error handler

Debugging Utilities

Error Handling

-- Set a custom error handler
seterrorhandler(function(msg)
    -- msg is the error string
    print("ERROR:", msg)
end)

-- Protected call with error handling
local success, err = pcall(function()
    -- Code that might error
end)
if not success then
    print("Error:", err)
end

-- xpcall with message handler
local success, err = xpcall(function()
    error("something broke")
end, function(msg)
    return msg .. "\n" .. debugstack(2)
end)

Debug Stack & Info

-- Get a stack trace
local stack = debugstack([thread,] [start [, count1 [, count2]]])

-- Get debug info
local info = debuglocals([thread,] [level])

-- Profile timing
debugprofilestart()
-- ... code to measure ...
local elapsed = debugprofilestop()  -- microseconds

Slash Commands for Debugging

-- /dump expression — evaluates and prints
-- /run code — executes Lua code
-- /script code — same as /run
-- /console cvarName [value] — get/set console variables

Common Patterns

Deferred Initialization (Wait for Login)

local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event)
    -- Safe to initialize — player is logged in
    self:UnregisterEvent(event)
    InitializeAddon()
end)

Safe OnUpdate Throttle

local elapsed = 0
local THROTTLE = 0.1  -- 100ms
frame:SetScript("OnUpdate", function(self, dt)
    elapsed = elapsed + dt
    if elapsed < THROTTLE then return end
    elapsed = 0
    -- Do periodic work
end)

Post-Combat Action Queue

local pendingActions = {}

local function QueueAction(action)
    if InCombatLockdown() then
        tinsert(pendingActions, action)
    else
        action()
    end
end

local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_REGEN_ENABLED")
frame:SetScript("OnEvent", function()
    for _, action in ipairs(pendingActions) do
        action()
    end
    wipe(pendingActions)
end)

Graceful Secret Value Handling (12.0.0)

-- When values might be secret, pass them directly to widgets
local name = UnitName(unit)  -- may be secret
myFontString:SetText(name)   -- widgets accept secrets

-- Check if a value is secret before trying operations
if not issecretvalue(someValue) then
    -- Safe to compare, do arithmetic, etc.
    if someValue == "expected" then ... end
else
    -- Cannot inspect — pass to UI widget directly
    myWidget:SetText(someValue)
end

Gotchas & Restrictions

No require() — WoW has no module system. Use the TOC file to control load order. Libraries are embedded directly.
setfenv() / getfenv() — Severely restricted. Do not rely on environment manipulation.
collectgarbage() — Only "count" mode works. Cannot force GC collection.
Taint is sticky — Once a variable is tainted, it stays tainted. Even if you set it back to the original value, the taint remains.
print() goes to chat — Unlike standard Lua, print() outputs to the default chat frame, not stdout.
String library additions — WoW adds strsplit, strjoin, strtrim, and strmatch as globals (in addition to string.match).
No os.exit() — Cannot terminate the client programmatically.
Coroutines work — Full coroutine support is available and commonly used for async patterns.
Secret values (12.0.0) — Some API returns are now opaque "secret" values that cannot be inspected, compared, or used in arithmetic. See the wow-api-important instructions for full details.
Instance restrictions (12.0.0) — SendAddonMessage() is blocked in instances. Design addons to work without inter-player communication during instanced content.

wow-api-lua-environment