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

Custom Untrigger

Args sent in to this function are the same as those in the Trigger
Expected return is a boolean. Return true if the trigger should untrigger, false if it should remain active.
The Untrigger function only runs if the trigger returns false/nil.

Duration Info

One arg sent in, the "trigger" table. This arg is sent for internal WA reasons and is unlikely to ever be useful to users.
Expected return - Duration Info can either carry a timer or a static value/total, the values returned are slightly different in each case

Returned values

Timed info should simply return two values return duration, expirationTime
- duration - number, total duration of the timer in seconds
- expirationTime - number, relative to GetTime(), when the timer will expire.
Static info should return three, return value, total, isStatic
- value - number, the current value
- total - number, the total or maximum value
- isStatic - boolean`, this simply tells WA that the previous 2 values given should be interpreted as Static Duration rather than Timed.

Name Info

One arg sent in, the "trigger" table. This arg is sent for internal WA reasons and is unlikely to ever be useful to users.
Expected return is a single string.

Icon Info

One arg sent in, the "trigger" table. This arg is sent for internal WA reasons and is unlikely to ever be useful to users.
Expected return is a valid texture path. This can be in the form of an iconID, or a path string.
This function is used for Icon and Progress Bar Aura Types, while Icon Info is used for Texture and Progress Texture Aura Types.

Examples:

function()
    return GetSpellTexture(123456)
end

function() 
     return "Interface\\TargetingFrame\\UI-RaidTargetingIcon_1"
end

IconIDs can also be found through a database site like Wowhead (example image) or WoW.tools (example link)

Texture Info

See Icon Info.

This function is used for Texture and Progress Texture Aura Types, while Icon Info is used for Icon and Progress Bar Aura Types.

Stack Info

One arg sent in, the "trigger" table. This arg is sent for internal WA reasons and is unlikely to ever be useful to users.
Expected return is a single number.

The way the Conditions tab processes this Info is as a number so it will cause errors if you try to return a string or other value.

Overlay Info

One arg sent in, the "trigger" table. This arg is sent for internal WA reasons and is unlikely to ever be useful to users.
Expected return - Overlays can behave in two distinct ways and the returned values required in each case differ

Returned values

For non-moving overlays return left_value, right_value
- The values are numbers and relative to the duration of "timed" Duration Info, or the total of an "static" Duration Info.
- you define both points of the Overlay
For moving overlays return direction, width
- direction - string, Either "forward" or "backward", setting whether the Overlay should lead or trail the progressing edge of the Aura.
- width - number, relative to the duration or total defined in the Duration Info, setting the size of the Overlay.

The Colours and Clipping Behaviours of each Overlay can be set in the Display tab.

Conditions

Run Custom Code

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

This function runs once when the Condition you made is passed, then not again until the Condition becomes false then true again. It also, of course, can't undo itself - if you use it to make a change that ought to return to the standard, then you'll need to add Conditions to handle that too.

Animation

Alpha (Opacity)

Args

progress A number value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
start The Alpha value that is defined as "normal" for the display, expressed as a value between 0 (invisible) and 1 (completely opaque). This is the value you set in the Display tab.
delta The difference between the "normal" alpha of the display and the alpha value specified for in the Animation settings. For example, if a display is set to 100% alpha normally, and its Alpha animation is set to 33%, then "delta" would be -0.66.

Expected Returns

alpha An Alpha animation function should return a single number value between 0 and 1, the alpha value that the display should have at the current point in the animation.

Example

The "Normal" Alpha animation path, which simply transitions from one Alpha value to another in a linear fashion, looks like this:

function(progress, start, delta)
  return start + (progress * delta)
end

Translate (Position)

Args

progress A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
startX The x coordinate that is defined as "normal" for the display (specifically, the x coordinate of its anchor point), expressed in pixels. This is the value you set in the Display tab.
startY The y coordinate that is defined as "normal" for the display (specifically, the y coordinate of its anchor point), expressed in pixels. This is the value you set in the Display tab.
deltaX The value specified by the animation using the "X Offset" slider in the Animation settings.
deltaY The value specified by the animation using the "Y Offset" slider in the Animation settings.

Expected Returns

x The resulting x coordinate of the display.
y The resulting y coordinate of the display.

Example

The "Normal" Translate animation path, which simply transitions from one position to another in a straight line, looks like this:

function(progress, startX, startY, deltaX, deltaY)
  return startX + (progress * deltaX), startY + (progress * deltaY)
end

Notes

A display's x and y coordinates are defined in terms of the distance between its reference anchor point and its self anchor point, both of which can be set in the Display tab. In WoW, x coordinates go from 0 at the left side of the screen to a positive value at the right side of the screen, and y coordinates go from 0 at the bottom of the screen to a positive value at the top of the screen. This is vertically inverse compared to many coordinate systems used in programming.

Scale (size)

Args

progress A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
startX The "normal" scale of the display in the x direction. This is always 1.
startY The "normal" scale of the display in the y direction. This is always 1.
scaleX The value specified by the animation using the "X Scale" slider in the Animation settings.
scaleY The value specified by the animation using the "Y Scale" slider in the Animation settings.

Expected Returns

scaleX The resulting scale of the display in the x direction.
scaleY The resulting scale of the display in the y direction.

Notes

An aura's scale in either the x or y direction is defined in relation to its normal size. This means that a display that is normally 200x200 pixels, if under a Scale animation whose current values are 1.5 and 0.8, will be 300x160 pixels.

Note that the scaleX and scaleY values passed to the Scale function are interpreted as being absolute values which denote the eventual maximum scale of the animation, not the difference between the original scale (which is always 1x1) and the end scale. This is a different behavior than the rest of the animation types.

Also note that Scale animations will differ slightly based on the display's anchor point, which will not change positions. A display anchored by its center will scale from the center, whereas a display anchored by a corner will scale from that corner.

Example

The "Normal" Scale animation path, which simply scales from one size to another in a linear fashion, looks like this:

function(progress, startX, startY, scaleX, scaleY)
  return startX + (progress * (scaleX - startX)),  startY + (progress * (scaleY - startY))
end

Rotate

Args

progress A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
start The Rotation value that is defined as "normal" for the display, expressed in degrees. This is the value you set in the Display tab.
delta The rotation value specified for the animation, using the slider in the Animation settings.

Expected Returns

rotation The rotation value that the display should have at the current point in the animation.

Notes

Texture displays are the only display type that is able to rotate (and only if Allow Full Rotation is enabled).

Example

The "Normal" Rotate animation path, which simply transitions from one Rotation value to another in a linear fashion, looks like this:

function(progress, start, delta)
  return start + (progress * delta)
end

Color

Args

`progress A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
r1
g1
b1
a1
- The RGBA Color values that define "normal" for the display. This is what you set in the Display tab.
r2
g2
b2
a2
- The RGBA color value specified for the animation, using the Color Picker in the Animation Settings.

Expected Returns

r
g
b
a
- The color values that the display should have at the current point in the animation.

Notes

Color values for frames in WoW are "percent" values between 0 and 1, not hex values as you might have used when formatting text. If you're working from 0-255 values then you can simply divide then (return 73/255, 122/255, 255/255, 255/255)

Example

The "Color" animation path, which simply transitions from one Color value to another in a linear fashion, looks like this:

function(progress, r1, g1, b1, a1, r2, g2, b2, a2)
    return r1 + (progress * (r2 - r1)), g1 + (progress * (g2 - g1)), b1 + (progress * (b2 - b1)), a1 + (progress * (a2 - a1))
end

Custom Code Blocks

Actions

On Init

On Show

On Hide

Chat Message - Custom Code

Display

Custom Text

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

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

Expected return:

"Update Custom Text On..."

Useful further reading:

Custom Anchor Function

Trigger

Custom Activation

Custom Trigger

Args

Examples

Further reading:

Custom Untrigger

Duration Info

Returned values

Further Reading:

Name Info

Further Reading:

Icon Info

Examples:

Further Reading:

Texture Info

Stack Info

Further Reading:

Overlay Info

Returned values

Further Reading:

Conditions

Run Custom Code

Animation

Alpha (Opacity)

Args

Expected Returns

Example

Further reading

Translate (Position)

Args

Expected Returns

Example

Notes

Further reading

Scale (size)

Args

Expected Returns

Notes

Example

Further reading

Rotate

Args

Expected Returns

Notes

Example

Further reading

Color

Args

Expected Returns

Notes

Example

Further reading

Group

Main Pages

Basics

Custom Code

Related

Clone this wiki locally