Home
Welcome to the WeakAuras wiki.
WeakAuras is a framework that is intended to give you the power to display all sorts of information on your screen in useful and aesthetically pleasing ways. The basic building block of WeakAuras is commonly called an "Aura", not to be confused with the generic term for buffs and debuffs in the game. You have many options regarding what events will trigger your Auras, what your Auras will look like, and what information they will show you. The purpose of this documentation is to explain these options to you, so that you can use the framework to its fullest extent.
WeakAuras is installed by extracting the WeakAuras package into your Interface/Addons folder. The WeakAuras folder contains core functionality, and the WeakAurasOptions folder contains the configuration UI. Make sure they are both enabled.
WeakAuras is designed to use LibSharedMedia for many textures and fonts, but it is not permitted for those fonts and textures to be directly distributed with WeakAuras. It is recommended that you install both of the following addons:
- For bar textures, install and enable SharedMedia
- For additional fonts, install and enable SharedMediaAdditionalFonts
WeakAuras is distributed with all of the textures and sound files that are included with PowerAuras. This has been explicitly allowed by the authors of PowerAuras.
WeakAuras does not come with any pre-configured Auras. In order to create some, open the configuration UI by typing /wa or /weakauras. This will display the "New" screen, which prompts you to pick an Aura type. Different Aura types have different properties and capabilities, which are briefly explained underneath their names in the UI. If this is your first time using WeakAuras, stick with the simplest Aura type - a Texture. Clicking the button labelled "Texture" will create a new Texture-type Aura in the sidebar.
For more information regarding Aura types, see Aura Types.
First, you must name your new Aura. The name doesn't affect the operation of the Aura - except that sidebar buttons are listed in alphabetical order - it is only for your own reference. You can simply press return to keep the default name for your new Aura ("New") if you want, and it can always be renamed later.
The sidebar will now contain a new button which represents your Aura. It will have a thumbnail of the Aura, the name of the Aura, and under that, a row of small icons. The farthest left icon (a piece of paper with a folded corner) indicates whether your Aura is currently loaded or not (more on what that means later) - yellow means loaded, grey means not loaded. The remaining icons are buttons that aid in configuration. From left to right, they are:
- Group (a large arrow pointing the right) - Allows you to choose a parent Group or Dynamic Group for the Aura. More information about Groups and Dynamic Groups can be found in Aura Types.
- View (a green eyeball with a black lid) - Allows you to change the visibility of the Aura during configuration. Auras have three visibility levels during configuration: hidden, shown, and force shown. "Hidden" Auras are indicated by a fully closed eye and are not shown. "Shown" Auras are indicated by a half-open eye, and are shown, but will be automatically hidden if you select another Aura. "Force shown" Auras are indicated by a fully open eye, and will be shown until you deliberately hide them, or close the configuration. Clicking the View button will toggle between "Hidden" and "Force Shown"; "Shown" is automatically applied to the currently selected Aura.
- More actions for example "Delete" and "Rename" are found in a context menu.
Once you select an Aura to configure (if you just created an Aura, it will be selected automatically), you will be presented with a set of tabs labelled "Display", "Trigger", "Conditions", "Actions", "Animations", "Load", "Custom Options", and "Information". Each of these tabs gives you a different set of options, as follows:
The "Display" tab controls the appearance and position of your Aura. Generally, there will be two sections, the top being devoted to appearance, and the bottom being devoted to position and size. For information on the specific appearance options of different Aura types, see Aura Types.
The position options are (mostly) shared between all Aura types. These options include "Width", "Height", "Anchor", "X Offset", and "Y Offset". However, these options are unnecessary unless you want input precise values, because Auras can also be sized and positioned directly on the screen. Whenever you select an Aura, WeakAuras will draw a positioning box around it. Drag the middle of this box to position your Aura and drag the corners to change its size. Holding down Shift temporarily hides the positioning box.
The "Trigger" tab controls what auras (buff/debuff), events, statuses, etc. will control the visibility of your Aura (when not in configuration mode). The default Trigger type is "Aura" (not to be confused with the common name for an individual WeakAuras display), which ties the visibility of your Aura to a buff or debuff. However, there are a multitude of other trigger types, which can be accessed via the dropdown settings. For more specific information on each Trigger type, see Trigger Types, and for instructions on creating a Custom Trigger, see Custom Triggers.
The "Conditions" tab allows you to change the appearance of an Aura based on its trigger states. These Conditions can evaluate global states (e.g., are you in combat) or states specific to one or more of your triggers (e.g., is the spell in Trigger 1 on cooldown or what is the remaining duration of the buff from Trigger 2.) If the condition is met you may update the Aura’s icon, appearance or position, as well as fire a sound or run some custom code. Conditions are evaluated separately from top to bottom and multiple conditions may be active at one time. If two conditions are triggered that set the same property to different values, only the later (lower in the list) change will prevail.
The "Actions" tab allows you to carry out some actions based on key events for the Aura.
On Show actions are executed whenever an Aura goes from being inactive to active.
On Hide actions are executed whenever an Aura goes from being active to inactive.
On Init actions are executed before any other custom code is run.
Examples of Actions provided are:
- Playing a sound
- Sending a chat message
- Highlighting a frame
- Running custom Lua code (the only option available On Init).
See Custom Actions for more info.
The "Animations" tab allows you to specify animations for your Aura. There are three animation types: Start, Main, and Finish. The Start animation will play when your animation is shown. Once the Start animation is finished (or if there is no Start animation, immediately after the Aura is shown), the Main animation will play and loop indefinitely. Finally, the Finish animation will play after the Aura untriggers. This means that if you have, for example, an Aura whose trigger is the Rejuvenation buff, the Finish animation will not start playing until you actually lose Rejuvenation.
Each of these three animations has roughly the same settings. First, you can choose between no animation, a preset animation, or a custom animation. If you want to see the exact mechanics of each preset animation, the best way is simply to try them.
If you choose a custom animation, you will be presented with several sets of options. They are as follows:
- Duration - An animation needs a duration, or it will not play. If the trigger type of your Aura provides duration info (see Dynamic Information), you will be allowed to express the duration of the animation as a percentage of the duration. This allows you to use the progress of your animation as an indicator of the duration of your Aura's trigger, which is a powerful visual tool.
- Fade (In/Out) - Controls the alpha (transparency) of the Aura during the animation. The transparency will always transition from the alpha value you set in the "Display" tab to the alpha value you specify in the animation (or vice-versa for Start animations).
- Slide (In/Out) - Controls the position of the Aura during the animation.
- Zoom (In/Out) - Controls the size of the Aura during the animation, as a multiple of its "normal" size. This means that values of 1 for both X and Y Scale will not change the size of the Aura at all (at least for the Normal type).
- Rotate (In/Out) - Controls the rotation of the Aura during the animation.
A few caveats regarding animations:
- Start and Finish animations are not automatically played when you set them. Use the View button on the Aura sidebar to hide and show your Aura to test its Start and Finish animations.
- Fade, Slide, Zoom, and Rotate options each have different "Type" options, which change the way they are applied. For example, by default, a Slide animation will simply move an Aura in a straight line, but using a different "Type" option can make it move in a circle instead. The best way to see how these options affect the appearance of the animation is to just try them out.
- Each option's "Type" field can be set to "Custom", which allows you to specify a custom animation path function. This is an advanced feature which requires knowledge of Lua code. See Custom Animation Functions for more info.
- Some Aura types cannot Zoom (Scale), and most cannot Rotate. This is essentially a limitation of the WoW client in general. More information about the animation capabilities of each Aura type can be found in Aura Types.
The "Load" tab controls at what times your Aura will even be considered for triggering. For most intents and purposes, an Aura that is not loaded does not exist to WeakAuras. It will never be shown or even considered for triggers. By default, an Aura will loaded at all times. Enabling any of the options in the "Load" tab will restrict when the Aura is loaded. There are too many load options to mention them all, but the most important ones are:
- In Combat - Enable this to indicate that your Aura should only be loaded in combat.
- Player Name - Enable this to indicate that your Aura should only be loaded for one specific character.
- Player Class - Enable this to restrict your Aura to a single class.
- Talent Specialization - Enable this to restrict your Aura to a specific talent tree. This should usually be used in conjunction with the Player Class option, but it doesn't have to be.
- Zone - Enable this to restrict your Aura to a given zone, e.g. "Icecrown Citadel". This is especially useful for Auras triggered by boss-specific debuffs.
- Instance Type - Enable this restrict your Aura to a specific type of instance.
- Dungeon Difficulty - Enable this restrict your Aura to either normal or heroic difficulty.
Some of the "Load" options can be set in either Single or Multiple mode. For example, if you have "Player Class" set to "Mage" Single mode, then the Aura will only be loaded on your Mage characters. Using Multiple mode will allow you to enable both "Mage" and "Priest", so that the Aura is loaded whenever you're playing a Mage or a Priest, but not any other class.
Other load conditions are tristates. For example, the "In Combat" load option switches between "Off", "Green Text" and "Red Text". A red text negates the meaning of the load condition. For this example the Aura would only be loaded outside of combat.
It is useful to make your "Load" settings for each Aura as specific as possible, for two reasons. First, it will make it easier for you to browse and search your Auras, because the configuration window's sidebar keeps Loaded and Unloaded Auras in different sections. Second, WeakAuras does not need to check the triggers of non-loaded Auras, which means Auras that are not loaded will not use any CPU time. Ensuring Auras are not loaded when they're not needed can improve your framerate (especially if you use a large number of Auras).
The "Custom Options" tab allows you to specify your own options for an Aura. This allows authors of complex Auras with lots of code to let users modify the behaviour of those Auras without having to worry about the user editing code. For more information, refer to Custom Options.
The "Information" tab allows you to specify contextual information for your Aura. This tab does not affect the behaviour of your Aura. From here you can change the name of the Aura, provide a URL for where the Aura is hosted (normally on Wago.io), and provide a description of what the Aura does.
WeakAuras provides two special Aura types, Group and Dynamic Group, which can have other Auras as "children". Grouping is a powerful feature of WeakAuras that allows you organize many Auras and set their configurations all at once. More information about the specific capabilities of Groups and Dynamic Groups can be found in Aura Types, but the general mechanics of grouping will be explained here.
Once you've created a Group or Dynamic Group-type Aura, it will not do anything or show anything on its own. You can add a child to your group by pressing "Group" on the sidebar button of the Aura you want to include. The sidebar buttons of a group operate slightly differently than a regular Aura:
- There is no "Loaded" indicator. Instead, there is an Expand/Collapse button. This simply determines whether all of the group's children will displayed on the sidebar.
- The View button controls the visibility of all the group's children. A closed eye indicates that all of the group's children are hidden, a fully open eye indicates that all of the group's children are force-shown, and a half-open eye indicates anything in between.
- The Delete button is replaced with "Delete children and group". If you want to keep any child Auras then be sure to ungroup them before deleting the Group.
When you select a Group, it will have an extra tab called "Group", which controls Group-specific settings (again, see the descriptions of Group and Dynamic Group on the Aura Types page for more info). The rest of the tabs will still be present, but do not control the Group itself. Instead, they allow you to change settings of all the group's children at once. This works as follows:
- If the children are not all the same type, the "Display" tab will be invalid. The other tabs will still be valid.
- On each tab, only the options that are shared by every child will be shown. If an option is shared by all children, but at least one of the children would display that option as disabled, the option will show as disabled.
- If the option has the same value for each child, it will be shown normally, in white. If any of the children has a differing value for that option, it will be shown in blue, and the tooltip for that option will show the value of each child for that option.
- Setting any option's value will copy that value to every child.
Groups can be nested to allow for some organisation of Auras. You can have multiple Dynamic Groups inside a regular Group, but cannot put Groups or Dynamic Groups inside a Dynamic Group. This basically means that group nesting provides options for organisation but not layout.
There is no forced limit on how deep nesting goes, nor how many total Auras can be inside a group. So bear in mind that if you nest many large groups (totalling hundreds or even thousands of Auras) then when you select the base group WeakAuras will try to make the config apply to all children in all the different sub-groups. This may mean that changing settings will apply to many more Auras than you intended, but in extreme cases could lead to "Script ran too long" errors.
- Aura types and triggers were designed to be modular and separate from one another. This means that occasionally, they will share information in unexpected ways. See Dynamic Information for more information.
- Almost all UI options that are represented by sliders will accept values beyond what they display. Just type a value into the box below the slider.
- Home
- API Documentation
- Getting Involved
- Setting up a Lua Dev Environment
- Deprecations
- Useful Snippets
- Aura Types
- Trigger Types
- Triggers and Untriggers
- Aura Activation
- Dynamic Information
- Text Replacements