WeakAuras

Usage

r1

Overview

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.

Installation

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.

There are several other addons that will improve WeakAuras by adding more media files. It is recommended that you install all of the following addons:

  • For bar textures, install and enable SharedMedia
  • For additional fonts, install and enable SharedMediaAdditionalFonts
  • For sounds and additional textures, install PowerAuras - You do not need to enable it - WeakAuras can identify sounds and textures in the PowerAuras folder. You can also copy the Auras and Sounds folders from the PowerAuras folder to the WeakAuras folder, and then delete PowerAuras.

Getting Started

The basic building block of WeakAuras is called a "display". WeakAuras does not come with any pre-configured displays. In order to add more, 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

Sidebar Options

The first thing that must be done for every new display is to name it. The name doesn't affect the operation of the display, except that sidebar buttons are listed in alphabetical order - the name is simply 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 siderbar 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 simply 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* - 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* - 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 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* - Allows you to copy settings from another display. That display must be of the same type.
  • *Rename* - 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* - Deletes the display. You must hold down Shift for this button to work.

Options Pane

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:

Display

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 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. Simply drag the middle of this box to position your display, and drag the corners to change its size.

Trigger

The "Trigger" tab controls what aura, event, value, etc. will control the visibility of your display in practice. 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 "Other". For more specific information on each trigger type, see Trigger Types.

Load

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. 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.

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 in the "Loaded" section of the sidebar if there are not a lot of unnecessarily loaded displays. Second, WeakAuras does not need to check for 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).''

Actions

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

Animations

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 Durations, Values, Icons, and Other 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. (Alternatively, you could say Main and Finish animations are played in reverse - the point is that they are opposite).
  • Fade, Slide, Zoom, and Rotate options each have different "Type" options, which change the way they are applied. The best way to see how these options affect the appearance of the animation is to just try them out. Furthermore, 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.

Grouping

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, nested groups are not possible).
  • 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 Display Types 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.

Other Considerations

  • 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 Durations, Values, Icons, and Other 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.