wow-api-lua-environment（WOW API LUA environment 文档）

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

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

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

1. Any variable set by addon code becomes tainted
2. Tainted values propagate — if tainted data flows into Blizzard code, it taints that path
3. Protected functions check taint before executing — they fail if execution path is tainted
4. 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

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).

Restriction Events

C_Log — Logging

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:

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

1. No require() — WoW has no module system. Use the TOC file to control load order. Libraries are embedded directly.
2. setfenv() / getfenv() — Severely restricted. Do not rely on environment manipulation.
3. collectgarbage() — Only "count" mode works. Cannot force GC collection.
4. Taint is sticky — Once a variable is tainted, it stays tainted. Even if you set it back to the original value, the taint remains.
5. print() goes to chat — Unlike standard Lua, print() outputs to the default chat frame, not stdout.
6. String library additions — WoW adds strsplit, strjoin, strtrim, and strmatch as globals (in addition to string.match).
7. No os.exit() — Cannot terminate the client programmatically.
8. Coroutines work — Full coroutine support is available and commonly used for async patterns.
9. 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.
10. Instance restrictions (12.0.0) — SendAddonMessage() is blocked in instances. Design addons to work without inter-player communication during instanced content.