Welcome to the WeakAuras documentation.
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. You have many options regarding what auras and events will trigger your displays, what your displays 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 copying the WeakAuras and WeakAurasOptions folders to 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 used 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.
The basic building block of WeakAuras is called a "display". WeakAuras does not come with any pre-configured displays. 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 a display type. Different display types have different properties and capabilities, which are briefly explained underneath the names of the display types. If this is your first time using WeakAuras, stick with the simplest display type - Texture. Clicking the button labeled "Texture" will create a new Texture-type display in your displays sidebar.
For more information regarding display types, see Display Types.
Configuring A Display
First, you must name your new display. The name doesn't affect the operation of the display - 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 display ("New") if you want, and it can always be renamed later.
The sidebar will now contain a new button which represents your new display. It will have a thumbnail of the display, the name of the display, and under that, a row of small icons. The farthest left icon (a piece of paper with a folded corner) indicates whether your display 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 display. More information about Groups and Dynamic Groups can be found in Display Types.
- View (a green eyeball with a black lid) - Allows you to change the visibility of the display during configuration. Displays have three visibility levels during configuration: hidden, shown, and force shown. "Hidden" displays are indicated by a fully closed eye, and are not shown. "Shown" displays are indicated by a half-open eye, and are shown, but will be automatically hidden if you select another display. "Force shown" displays 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 display.
- Copy (a book) - Allows you to copy settings from another display. That display must be of the same type.
- Rename (a thin arrow that forms a circle) - Allows you to change the name of the display. Names must be unique, so if you try to choose a name that is already taken, nothing will happen.
- Delete (a large red X) - Deletes the display. You must hold down Shift for this button to work.
Once you select a display to configure (if you just created a display, it will be selected automatically), you will be presented with a set of tabs labeled "Display", "Trigger", "Load", "Actions", and "Animations". Each of these tabs gives you a different set of options, as follows:
The "Display" tab controls the appearance and position of your display. 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 display types, see Display Types.
The position options are (mostly) shared between all display types. These options include "Width", "Height", "Anchor", "X Offset", and "Y Offset". However, these options are unnecessary unless you want input precise values, because displays can also be sized and positioned directly on the screen. Whenever you select a display, WeakAuras will draw a positioning box around it. Drag the middle of this box to position your display, and drag the corners to change its size.
The "Trigger" tab controls what aura, event, status, etc. will control the visibility of your display (when not in configuration mode). The default trigger type is "Aura", which ties the visibility of your display to a buff or debuff. However, there are a multitude of other trigger types, which can be accessed by setting Type to "Status" or "Event". Status triggers are based on values about your character or environment that can always be checked (for example, your Health). Events are triggered by one-time occurrences (for example, a chat message), and are usually shown for a pre-defined duration of time. Additionally, setting the trigger Type to "Custom" will create a custom trigger, an advanced feature which requires knowledge of Lua. For more specific information on each trigger type, see Trigger Types, and for instructions on creating a Custom trigger, see Custom Triggers.
The "Load" tab controls at what times your display will even be considered for triggering. For most intents and purposes, a display that is not loaded does not exist to WeakAuras. It will never be shown or even considered for triggers. By default, a display will *always be loaded*. Enabling any of the options in the "Load" tab will restrict when the display is loaded. The options are as follows:
- Player Name - Enable this to indicate that your display should only be loaded for one specific character.
- Player Class - Enable this to restrict your display to a single class.
- Talent Specialization - Enable this to restrict your display to either your primary or secondary set of talents. This should generally be used with "Player Name", because one mage's primary spec might be another mage's secondary spec. This may be improved in Cataclysm
- Zone - Enable this to restrict your display to a given zone, e.g. "Icecrown Citadel". This is especially useful for displays triggered by boss-specific debuffs.
- Instance Type - Enable this restrict your display to a specific type of instance.
- Dungeon Difficulty - Enable this restrict your display 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 display will only be loaded on your Mage characters. Using Multiple mode will allow you to enable both "Mage" and "Priest", so that the display is loaded whenever you're playing a Mage or a Priest, but not any other class.
It is useful to make your "Load" settings for each display as specific as possible, for two reasons. First, it will make it easier for you to browse and search your displays, because the configuration window's display sidebar keeps Loaded and Unloaded displays in different sections. Second, WeakAuras does not need to check the triggers of non-loaded displays, which means that ensuring displays are not loaded when they're not needed can improve your framerate (especially if you use a large number of displays).
The "Actions" tab allows you to specify side-effects for when your display is shown or hidden. Side-effects can be:
- Playing a sound
- Sending a chat message
- Running custom Lua code
The "Animations" tab allows you to specify animations for your display. 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 display is shown), the Main animation will play and loop indefinitely. Finally, the Finish animation will play *after* the display untriggers. This means that if you have, for example, a display whose trigger is the Prayer of Fortitude buff, the Finish animation will not start playing until you actually lose Prayer of Fortitude.
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 display 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 display's trigger, which is a powerful visual tool.
- Fade (In/Out) - Controls the alpha (transparency) of the display 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 display during the animation.
- Zoom (In/Out) - Controls the size of the display 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 display at all (at least for the Normal type).
- Rotate (In/Out) - Controls the rotation of the display 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 display sidebar to hide and show your display to test its Start and Finish animations.
- Start animations are always played in reverse. This is so the display ends up in its "normal" appearance once the Start animation is finished.
- 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 a display 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 display 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 display type can be found in Display Types.
WeakAuras provides two special display types, Group and Dynamic Group, which can have other displays as children. Grouping is a powerful feature of WeakAuras that allows you organize many displays and set their configurations all at once. More information about the specific capabilities of Groups and Dynamic Groups can be found in Display Types, but the general mechanics of grouping will be explained here.
Once you've created a Group or Dynamic Group-type display, 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 display you want to include. The sidebar buttons of a group operate slightly differently than a regular display:
- 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.
- There is no Group button (sorry, you cannot put a group into another group).
- 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 does *not* delete displays recursively. If a group has any children when you delete it, those children will merely be un-grouped.
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 Display 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.
- Display 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.