Custom Triggers

Custom triggers are an advanced feature that is only intended for users who know Lua. As such, the following page will assume you are familiar with Lua and related programming concepts.

(For more information on Lua, see Programming in Lua.)

---

Custom triggers are a way for you to trigger a WeakAuras display using any arbitrary Lua code. There are two types of custom triggers: Status and Event.

Status

"Status" type Custom Triggers are based on the assumption that they will be used to check a value that can always be determined. They can be set to update on certain events, or simply every frame. The main way they differ from "Event" type Custom Triggers is that they receive a dummy (no args) STATUS event when doing things like logging in, reloading, or exiting WA config. This dummy event let you check the current status of whatever you're showing.

A simple example of a Status Trigger would be, if you're trying to monitor the health of a unit then you register UNIT_HEALTH, but when you close WeakAuras config you don't want to have to wait for the unit's health to change before you can show your Aura. The dummy event of a Status trigger let you establish the initial state.

Event

"Event" type Custom Triggers are based on the assumption that they will be used with events that pass relevant information. As such, the main way in which they differ from Status type custom triggers is that they will not be forced to update at time when Status type custom triggers would. Event type custom triggers can be set to hide on a timer, or they can have a custom untrigger.

To use events that you specify in the Event(s) field you need to set up your functions in a specific way. Say for example you wanted to check on events ENCOUNTER_START and ENCOUNTER_END and you want to use these events in your trigger function:

--Event(s): ENCOUNTER_START, ENCOUNTER_END
--Trigger
function(event, arg1, arg2, ...)
    if event == "ENCOUNTER_START" then
        --Use the arguments for this event
        return true
    end
end

--Untrigger
function(event, arg1, arg2, ...)
    if event == "ENCOUNTER_END" then
        --Use the arguments for this event, or dont, just untrigger.
        return true
    end
end

The actual event name is always passed into the function as the first arg (except in Trigger State Update triggers, see below), followed by all of the event's arguments. For more details on available events see WarcraftWiki.

A side note about arguments in Lua: If you are using more than one event you can use an ellipsis, known as a "vararg" (...), to store arguments from an event, letting you check the event name before assigning pertinent variable names to the arguments for that specific event. select(number, ...) can be used to pick args out of the vararg as needed. You can learn more about varargs in Lua via their documentation.

Trigger State Updater

Trigger State Updater directly modify the structures that contain information about the trigger state. The main benefit to the other two trigger methods is, that it allows for creating multiple displays from your custom trigger function. See the TSU Wiki page for more info on how to use this trigger type.

---

Trigger Options

Check On...

Only available for Status type custom triggers. When set to Every Frame, the trigger will not require any events, but will instead be checked using an OnUpdate script.

Event(s)

A list of events which will cause the custom trigger function to be called (as well as the untrigger function, if the trigger function returns false). Multiple events can be listed, separated by whitespace and/or commas.

As of WeakAuras 2.12.4, you can do some limited filtering on specific events.

• On all UNIT events you can filter by the unitID the event carries. e.g.:
  • UNIT_SPELLCAST_SUCCEEDED:player
  • UNIT_TARGET:boss1:boss2

You can also use meta-units arena, boss, nameplate or group

• For COMBAT_LOG_EVENT_UNFILTERED you can also filter subevents. e.g.:
  • COMBAT_LOG_EVENT_UNFILTERED:SPELL_CAST_START
  • CLEU:SPELL_CAST_START:SPELL_AURA_APPLIED (Note you can use the abbreviated event name "CLEU" too)

The events that do fire into the trigger will still carry all the args you would normally expect to see. All this does is fire the trigger for less unwanted events.

Watched Triggers

The keyword TRIGGER can be used along with trigger numbers for as many other triggers in the Aura as you want to track. e.g.:

• TRIGGER:5
• TRIGGER:1:2

This will have your Custom Trigger fire any time the specified triggers update, with the parameters (event, updatedTriggerNumber, updatedTriggerStates). The updatedTriggerStates parameter is a table containing all states that the trigger in question carries, keyed by cloneID. Note: a trigger which does not clone will have the cloneID of "" (an empty string). Those used to TSU (Advanced Custom Trigger) will recognise the way this table is set up.
You can watch other Custom Triggers but WA will block "reciprocal" triggers (trigger1 requests trigger2, and trigger2 requests trigger1).

Example: https://wago.io/WatchedTriggerExample
Imagine you want to track nameplate units and range check on them. This Aura gets WA to handle the unit tracking then uses the units gathered to create states in a TSU and range check them.

Note: this isn't necessarily the best way to achieve a goal like this but provides a simple example of how Watched Triggers can be useful. You get a built in WA trigger to collect information then use it as you need in a custom trigger.

The easiest way to examine what information is contained in a state is to use DevTool. Add DevTool:AddData(updatedTriggerStates, "your name") to your watching trigger.

Custom Trigger

The custom trigger field should be an anonymous function which returns true if the trigger should become active. The function will be passed all the arguments that are specified for the event that triggered, starting with the name of the event. If the function returns false, nil, or nothing, the trigger will not automatically become inactive - instead, failure of the trigger function will cause the untrigger function to be called. For trigger state updater triggers, please refer to the section at the bottom.

Custom Untrigger

The custom untrigger field, just like the custom trigger field, should be an anonymous function, and will be passed the same arguments as the trigger function. However, it should return true if the trigger should become inactive - i.e., the trigger's display should be hidden. If the untrigger function returns false, nil, or nothing, no change will be made to the display. It will remain visible if it is already visible, or it will remain invisible if it is already invisible. Most of the time, for status type custom triggers, the untrigger function can always return true. However, it can be useful to define a trigger and untrigger in such a way that there is a grey area. See Triggers and Untriggers for more info.

Hide

Only available for Event type custom triggers. If set to Timed, the Custom Untrigger field will be hidden, and the custom trigger will simply last for a pre-defined amount of time. If set to Custom, a custom untrigger function can be defined.

Dynamic Information

The status and event custom triggers can return dynamic information by implementing the duration, name, icon, stacks, and texture functions. The return values of the name, icon,texture and stacks function is simply the value of that dynamic information. The duration function for timed progress should be two values: duration, expirationTime and for static progress, three values: value, total, true.

FRAME_UPDATE event

A fake event "FRAME_UPDATE" is triggered every frame. It can be used to handle normal events and an OnUpdate script in a same function.

STATUS event

On loading and after the Options window is closed, all loaded "status" auras receive a fake "STATUS" event. Custom auras can react to this event and setup their states.

Note, that auras that have the compatibility option enabled instead get fake events for all events listed in the event list.

OPTIONS event

Each aura that is displayed in the Options receives a fake "OPTIONS" event. Custom auras can react to this event and setup states that are useful while the options are open. These states are automatically cleared on closing the options.

If a trigger does not provide any states in response to the OPTIONS event, fake states are automatically created.

Note, that errors from triggers while reacting to the OPTIONS event are silently ignored for auras that have the compatibility option enabled.