Custom Code Blocks

Actions

On Init

• No function() ... end required.
• Nothing sent in.
• No return expected.

Init does not run each time the Aura is loaded, it runs once when the aura is first loaded then never again until a UI reload/restart or if WA config is opened and changes made to this code block or to Custom Options.

This code block is exceptionally useful for creating settings (any settings that users may want to alter should be done with Custom Options), tables of data, or functions. Anything that will be used throughout your Aura, or repeatedly by a function. Create variables like this in the aura_env table.

If the Aura you're making produces clones then this code block runs before they exist and so aura_env.state won't exist and aura_env.region will refer to the "base" Aura, not any clones you create later.

On Show

• No function() ... end required.
• Nothing sent in.
• No return expected.

On Show runs once when the Aura as a whole change from not being active to being active. Then will not run again until it hides, and shows again.

If the Aura you're making produces clones then this code block will run for each clone that is shown. And aura_env.state and aura_env.region carry that clone's info.

On Hide

• No function() ... end required.
• Nothing sent in.
• No return expected.

On Hide runs once when the Aura as a whole change from being active to not being active. Then will not run again until it shows, and hides again.

If the Aura you're making produces clones then this code block will run for each clone that hides. And aura_env.state and aura_env.region carry that clone's info.

Chat Message - Custom Code

This code block is accessed by using the Chat Message option, with %c in the Message text. The string(s) you return will be inserted into the message that you send.

Although it's likely that Custom Text functions in Actions will be much simpler than those in Display, all the info is the same so see below for extensive details

Display

Custom Text

If the trigger currently providing Dynamic Info uses "timed" duration info (e.g. buff duration) then:

function(expirationTime, duration, progress, formatedDuration, name, icon, stacks)

• expirationTime - number When the displayed timer will expire, relative to GetTime()
• duration - number The total number of seconds, e.g. 123
• progress - string A formatted string showing remaining duration, equivalent of the %p text replacement
• formatedDuration - string A formatted string showing minutes if applicable, e.g. 2:03, equivalent of the %t text replacement
• name - string Whatever string the active trigger carries on its Name Info, equivalent of the %n text replacement
• icon - string A formatted string with the Escape Sequences needed to display the Dynamic Info's icon in text, equivalent to the %i text replacement.
• stacks - number The value carried by the Dynamic Info's Stacks, equivalent to %s

Despite looking like a number when below a minute, the "progress" value is actually a formatted string and shouldn't be used for arithmetic. If you need a remaining duration in your custom function then calculate yourself. e.g.

function()
  if aura_env.state and aura_env.state.duration and aura_env.state.duration > 0 then
    local remaining = aura_env.state.expirationTime - GetTime()
    return remaining > 3600 and ceil(remaining/3600).."h" or remaining > 60 and ceil(remaining/60).."m" or floor(remaining)
  end
end

If the trigger currently providing Dynamic Info uses "static" duration info (e.g. health values) then:

function(total, value, value, total, name, icon, stacks)

• total - number The total or max value, equivalent to the %t text replacement
• value - number The current value carried by dynamic Info, equivalent to the %p text replacement
• value and total are repeated just to match argument positions with those with timed info.
• Other args are as above.

Expected return:

return string[, string, string]

• You can return multiple values.
• You can return nil, it will be handled as an empty string.

"Update Custom Text On..."

Above this code block in the interface is a setting "Update Custom Text On..."

• "Trigger Update" will fire the custom function when the Dynamic Info from any trigger in the Aura changes in any way. It will not fire when a custom trigger returns true from its trigger function unless that custom trigger also adjusts one of the Dynamic Infos it carries
• "Every Frame" will fire the custom function every time the screen redraws (your Frames Per Second). This should be avoided where possible, since it means it will often be running when there is no change to update. When it is necessary though, don't worry too much, just code your function with efficiency in mind. Any application where you're outputting a timer will inevitably require "Every Frame".

Useful further reading:

• Text Replacements

Custom Anchor Function

• No args are sent in to the function
• It is Fired on Trigger Update
• Expected return is a reference to a UI Frame. This frame can be a WA Aura/region, a Blizzard UI element, or another Addon's frame.

This example, using with a Status - Cast trigger with setting Unit = Player, will anchor the region to your target's nameplate

function()
    if aura_env.state.destUnit then
        return C_NamePlate.GetNamePlateForUnit(aura_env.state.destUnit)
    end
end

For dynamically anchoring multiple auras to multiple frames refer to dynamic group Custom Grow Functions and Group by Frame

Trigger

Custom Activation

• One argument sent in to the function, the triggers table, an array containing a boolean for the activated state of each trigger in the Aura
• Runs when any trigger in the Aura's "active" state changes from false to true or vice versa.
• Expected return is a single Boolean for whether the Aura should show or not.

Example - this example function would display the aura if trigger 1 is active and at least one of triggers 2 or 3 is also active.

function(triggers)
  return triggers[1] and (triggers[2] or triggers[3])
end

See this page for general info on Activation.

Custom Trigger

• Args sent in to the function depend on the trigger type, see below
• Expected return is a boolean for whether the trigger should be active or not.

Args

• If you use Custom - Status - Every Frame, then no args will be sent in to the function.
• If you use Custom Status - Event(s) - or Custom - Event(s) - , then WA will send the event name as the first arg, followed by the event's own args, into your function.
• If you use Custom - Trigger State Updater then WA will always send the allstates table as the first arg
  • If you use Every Frame then there will be no following args.
  • If you use Event(s) - , then the second arg will be the event's name, followed by the event's own args.

Examples

Using Custom - Status - Event - UNIT_HEALTH

function(event, unit)
    if unit == "player" then
        return UnitHealth("player") > 1000
    end
end

Using Custom - Event - CLEU

function(event, timestamp, subEvent, hideCaster, sourceGUID, sourceName, sourceFlags, sourceRaidFlags, destGUID, destName, destFlags, destRaidFlags, ...)
    if subEvent == "SPELL_CAST_SUCCESS" and sourceGUID == UnitGUID("player") then
        return true
    end
end

Using Custom - TSU - Event - UNIT_HEALTH

function(allstates, event, unit)
    if unit == "player" then
        allstates[""] = {
            show = true,
            changed = true,
            progressType = "static",
            value = UnitHealth("player"),
            total = UnitHealthMax("player"),
        }
        return true
    end
end

Further reading:

• Custom Triggers Wiki page
• TSU Wiki page
  • With TSU being an advanced trigger type it is strongly advised to read the full wiki page for it before using.