Overlay - ennvina/spellactivationoverlay GitHub Wiki

An overlay, also known as spell alert, is a visual cue inviting a call to action.

Overlays display a rectangular texture close to screen center, to maximize its visibility during combat. It surrounds the main character at one of the three pre-defined locations: top, left or right.

Classes

Each class defines its own list of overlays. The code is designed to load only intended overlay of the class of the currently logged in avatar. This includes:

  • setting up trackers that will detect when an overlay triggers
  • adding overlay options to the options panel

Lists below summarize all available overlays. Unless otherwise stated, an overlay is available to all flavors.

Death Knight

Main article: Death Knight

The following overlays are supported for Death Knight:

  • Rime
  • Killing Machine
  • Crimson Scourge (Cataclysm)
  • Sudden Doom (Cataclysm)
  • Will of the Necropolis (Cataclysm)

Druid

Main article: Druid

The following overlays are supported for Druid:

  • Omen of Clarity
  • Predatory Strikes
  • Lunar and Solar Eclipse (Season of Discovery, Wrath, Cataclysm)
  • Nature's Grace (Wrath)
  • Wrath of Elune (Wrath)
  • Elune's Wrath (Wrath)
  • Fury of Stormrage (Season of Discovery, Cataclysm)
  • Healing Trance / Soul Preserver (Wrath)

Hunter

Main article: Hunter

The following overlays are supported for Hunter:

  • Improved Steady Shot (Wrath)
  • Master Marksman (Cataclysm)
  • Lock and Load (Season of Discovery, Wrath, Cataclysm)
  • Flanking Strike (Season of Discovery)
  • Cobra Strikes (Season of Discovery)

Mage

Main article: Mage

The following overlays are supported for Mage:

  • Arcane Concentration
  • Frozen debuff
  • Arcane Missiles! (Cataclysm)
  • Missile Barrage (Season of Discovery, Wrath)
  • Arcane Blast (Season of Discovery)
  • Arcane Potency (Cataclysm)
  • Heating Up (Season of Discovery, Wrath, Cataclysm)
  • Hot Streak (Season of Discovery, Wrath, Cataclysm)
  • Impact (Wrath, Cataclysm)
  • Firestarter (Wrath)
  • Fingers of Frost (Season of Discovery, Wrath, Cataclysm)
  • Brain Freeze (Season of Discovery, Wrath, Cataclysm)

Paladin

Main article: Paladin

The following overlays are supported for Paladin:

  • Infusion of Light (Wrath, Cataclysm)
  • The Art of War (Wrath, Cataclysm)
  • Healing Trance / Soul Preserver (Wrath)

Priest

Main article: Priest

The following overlays are supported for Priest:

  • Surge of Light (Burning Crusade, Wrath, Cataclysm)
  • Serendipity (Season of Discovery, Wrath, Cataclysm)
  • Mind Spike (Season of Discovery)
  • Healing Trance / Soul Preserver (Wrath)

Rogue

Main article: Rogue

The following overlay is supported for Rogue:

  • Riposte (Classic Era, Burning Crusade, Wrath)

Shaman

Main article: Shaman

The following overlays are supported for Shaman:

  • Elemental Focus
  • Maelstrom Weapon (Season of Discovery, Wrath, Cataclysm)
  • Tidal Waves (Season of Discovery, Wrath)
  • Power Surge (Season of Discovery)
  • Molten Blast (Season of Discovery)
  • Rolling Thunder (Season of Discovery)
  • Healing Trance / Soul Preserver (Wrath)

Warlock

Main article: Warlock

The following overlays are supported for Warlock:

  • Nightfall, a.k.a. Shadow Trance
  • Backlash (Wrath)
  • Molten Core (Wrath)
  • Decimation (Wrath)
  • Empowered Imp (Wrath)

Warrior

Main article: Warrior

The following overlays are supported for Warrior:

  • Sudden Death (Wrath)
  • Bloodsurge (Wrath)
  • Sword and Board (Season of Discovery, Wrath)
  • Raging Blow (Season of Discovery)

Development

Ultimately, an overlay is displayed using the SpellActivationOverlay engine, based on the functionality of the same name introduced in Cataclysm.

Low-level

The lowest level display function is performed by:

function SpellActivationOverlay_ShowOverlay(self, spellID, texturePath, position, scale, r, g, b, vFlip, hFlip, cw, autoPulse, forcePulsePlay, endTime, combatOnly, extra)
  • self is the SpellActivationOverlay frame, which is the main frame of the addon
  • spellID is the numerical spell identifier, used here as an index in the table that lists all displayed overlays
  • texturePath is the texture location to pass to TextureBase::SetTexture
  • position is a string among a list of predefined locations
  • scale is the scale factor e.g. 0.5 means 50% of its normal size
  • r, g, and b are numbers in the 0-255 range to modulate texture color
  • vFlip and hFlip are booleans that tells if the texture should be flipped vertically or horizontally, respectively
  • cw is an optional number that tells if the texture should be rotated 90 degrees clockwise (if positive) or 90 degrees counter-clockwise (if negative); default is 0, meaning no rotation
  • autoPulse is an optional flag telling to start a pulse animation automatically after fade-in; default is false
  • forcePulsePlay is an optional flag telling to start the pulse animation right away; default is false
  • endTime is an optional time value, based on GetTime measurement, indicating when the effect will expire inevitably; default is nil, meaning the effect has no set expiration time, either because we don't know its duration, or because it has a virtually infinite duration
  • combatOnly is an optional flag telling that the effect is intended only for combat and shall quickly fade out after leaving combat; default is false
  • extra is an optional table that defines advanced parameters, it has been added to avoid multiplying individual parameters to the already long list of params; default is nil

The list of predefined locations is setup in the overlay.SetGeometry function. Strings are case-insensitive. Source code always uses e.g. "Top" instead of "TOP":

  • "CENTER"
  • "LEFT"
  • "RIGHT"
  • "TOP"
  • "BOTTOM"
  • "TOPRIGHT"
  • "TOPLEFT"
  • "BOTTOMRIGHT"
  • "BOTTOMLEFT"

In practice, the only ones that are used are: "TOP", "LEFT" and "RIGHT". "CENTER" would prevent the player from seeing their avatar. "BOTTOM" is provided for orthogonality, but has been avoided so far, to avoid either confusion or conflict with other addons. Corner positions are also provided for orthogonality, but have been avoided as well.

The SpellActivationOverlay_ShowOverlay function is internal and shall not be called directly. The one true function that shall be called to display an overlay is:

function SpellActivationOverlay_ShowAllOverlays(self, spellID, texturePath, positions, scale, r, g, b, autoPulse, forcePulsePlay, endTime, combatOnly, extra)

Its parameters are almost identical to SpellActivationOverlay_ShowOverlay but positioning, flipping and rotating is defined in a single string. The positions string can either use one of the predefined locations (see above list), or one of the predefined complex locations using the complexLocationTable.

  • "RIGHT (FLIPPED)"
  • "BOTTOM (FLIPPED)"
  • "LEFT + RIGHT (FLIPPED)"
  • "TOP + BOTTOM (FLIPPED)"
  • "LEFT (CW)"
  • "LEFT (CCW)"
  • "RIGHT (CW)"
  • "RIGHT (CCW)"
  • "TOP (CW)"
  • "TOP (CCW)"
  • "BOTTOM (CW)"
  • "BOTTOM (CCW)"

For example:

  • "TOP (CW)" will display an overlay with position == "TOP", vFlip == false, hFlip == false and cw == 1
  • "RIGHT (FLIPPED)" will display an overlay with position == "RIGHT", vFlip == false, hFlip == true and cw == 0
  • "LEFT + RIGHT (FLIPPED)" will display two overlays, equivalent to dispaying "LEFT" alongside "RIGHT (FLIPPED)":
    • an overlay with position == "LEFT", vFlip == false, hFlip == false and cw == 0
    • an overlay with position == "RIGHT", vFlip == false, hFlip == true and cw == 0

When a component needs to call SpellActivationOverlay_ShowAllOverlays, it usually calls the SAO.ShowAllOverlays alias instead.

Mid-level

At a higher level, the addon may use an aura, which defines a set of triggers and and the visual appearance of the overlay.

Auras are registered using the SAO.RegisterAura function:

function SAO.RegisterAura(self, name, stacks, spellID, texture, positions, scale, r, g, b, autoPulse, glowIDs, combatOnly)
  • self is SAO, the main object of the addon
  • name is a human-readable name, usually unique but can be shared
  • stacks is the number of stacks to trigger the aura, or 0 to trigger at any stacks
  • texture is not quite the same as texture path passed to the ShowAllOverlays function
  • positions, scale, r, g, b, autoPulse and combatOnly are passed as is to ShowAllOverlays
  • glowIDs is the optional list of glowing button IDs for the glowing button functionality

The texture parameter is either:

  • the empty string, which means "do not display an overlay"
  • any other string, in which case it designates a short form e.g., "rime" instead of "Interface\\Addons\\SpellActivationOverlay\\textures\\rime"
  • a function, in which case it will be invoked when the aura is triggered

High-level

At the highest level, the addon may use an effect. Here are the base effect elements that are of interest for overlays:

{
    spellID = 12345,
    combatOnly = false, -- Default is false

    overlays = {{
        texture = "genericarc_05",
        location = "Top",
        scale = 1, -- Default is 1
        color = {255, 255, 255}, -- Default is {255, 255, 255}
        pulse = true, -- Default is true
    }},
}

There is an even higher effect, using SAO.CreateEffect:

SAO:CreateEffect(
    "rime",
    SAO.WRATH + SAO.CATA,
    59052, -- Freezing Fog (buff)
    "aura",
    {
        talent = 49188, -- Rime (talent)
        overlay = { texture = "rime", location = "Top" },
        buttons = {
            [SAO.WRATH] = howlingBlast,
            [SAO.CATA] = { howlingBlast, icyTouch },
        },
    }
);

In the above example, the overlay is simply defined by its spell ID 59052 and its overlay definition overlay = { texture = "rime", location = "Top" }, the rest is implied e.g., scale is set to 1 by default. The other parameters passed to CreateEffect are used for glowing buttons, options or conditional loading based on project.