Macros: Essential Information

Table of Contents:


  1. Intro - Macro Basics
  2. Macros - What can they do?
  3. Macros - What can they NOT do?
  4. Conditionals - How do they work?
  5. Scripting - What is possible in a macro?
  6. Macros - Tips, Tricks, and Shortcuts

1. Intro - Macro Basics

Macros are a very useful tool within the World of Warcraft client. They allow you to combine multiple actions onto a single button. While the entire macro will run every time, actions which trigger the Global Cooldown will stop later GCD actions from functioning.

You can make a macro to take almost any action you can click or keybind, with certain restrictions.

Macro commands can be made more useful with [conditionals], snippets that check on various things to allow a small degree of decision making. While macros execute the first valid item from the top down, individual commands execute the first valid conditional, from left to right.

Macros can be used to execute scripts, small snippets of Lua code, from within WoW without the use of an external addon. This is done by using the /run command. Scripting is an advanced feature and is explained more in detail further down.

There are a number of tips, tricks, and shortcuts to help you get the most out of your macros. Most of the ones listed have come from this very forum, and I have consolidated them here to make it easier.

As the macro system is continually updated with new patches, and new discoveries are made about how certain commands and conditionals work, I will do my best to keep this thread up to date with current information.

2. Macros - What can they do?

Macros can make many actions within the game environment. Most often, macros are created to use items or abilities. However, macros can also be used to send chat messages, equip gear, change class specializations, and adjust settings, among many, many other things.

Macro commands are prefaced with a /

Examples:
/use
/cast
/say
/equip
/console
/castsequence
/target
/click

There are many other slash commands that can be used in a macro, and more are added in patches or expansions on a regular basis. WoWPedia has a list of many possible slash commands available to the default game client. If you want to see a full list, you can pull it directly, in-game, with a script below in the Tips and Tricks section of the guide. Many addons also add their own slash commands, usually to open a configuration menu or perform a specific action; most of these can be used from a macro as well as typed directly into the chat edit box (e.g. /recount).

There is also a special macro command, #showtooltip. This will show the icon and information for an item or ability, the same as if you had dragged the item or ability onto your action bar.

Example:

#showtooltip
/cast Flash Heal

This macro, when placed on your action bar, would function exactly the same as dragging the spell Heal from your spellbook.

One other special command is /click, which can be used to click on UI elements, such as action bars or pop up buttons. This can be very helpful when trying to keybund UI actions not visible in the default keybinding UI. Another powerful use would be conditional branching for scripts, which enables you to do some pretty advanced stuff.

3. Macros - What can they not do?

Macros cannot make smart decisions for you. They can’t cast spells based on cooldown, or check if a buff is active, or magically fit all your abilities onto one button.

Macros cannot be any longer than 255 characters, unless you use an addon to circumvent this limit.

Macros cannot circumvent the global cooldown to use more than one item or ability at a time. There are some exceptions, but this is the general rule.

Macros cannot simulate additional keypresses. One keypress = one action.

Macros cannot include a delay for most commands. Certain commands (e.g. chat) can be delayed with an addon.

4. Conditionals - How do they work?

Conditionals are a way to extend the macro interface. They allow limited decision-making to macros; be aware that they are limited to what Blizzard has specifically allowed for each command, and that not all commands may accept the same conditionals.

As an example, let’s take the simple macro from earlier:

#showtooltip
/cast Flash Heal

We are going to modify this macro with the [harm] conditional, so it does something different when an enemy is targeted:

#showtooltip
/cast [harm]Smite;Flash Heal

Now, the macro will use Smite if you have an enemy targeted, and Flash Heal otherwise.

You can use multiple conditionals in a macro command. Example:

#showtooltip
/cast [harm,mod]Holy Fire;[harm]Smite;[mod]Heal;Flash Heal

The macro will now use Holy Fire if you are pressing a modifier (Ctrl, Shift, or Alt) and you have an enemy target, Smite if you have an enemy target and are not pressing a modifier, Heal if you are pressing a modifier without an enemy target, and Flash Heal if none of the other conditions are true.

It is important to remember the proper syntax when using multiple conditionals. [combat,mod] would require you to be in combat and holding a modifier, while [combat][mod] would only require one or the other.

Another important feature of conditionals is the ability to use an empty conditional, []. Empty conditionals function exactly as if you had dragged the spell from your spell book, meaning they will respect your auto-self-cast settings, and will properly alert you if a target is required rather than silently failing without a target. They also serve as a fallback option to ensure a tooltip is generated if other conditions are not met.

IT IS IMPORTANT TO REMEMBER THAT A MACRO WILL EXECUTE THE FIRST TRUE CONDITION .

In the above example, if you have an enemy targeted, the macro will never cast Heal or Flash Heal, no matter what you do. You need to target a friendly or clear your target in order to cast a healing spell.

Conditionals available for use in macros:
(Note that any of these conditions (excepting [@unit]) can be inverted with no, meaning [nocombat], [nopet], etc, will work exactly as you’d expect.

  • [@unit]

Attempts to perform the action on the listed unit, unit can be a UnitID (player, target, focus, pet, party1, raid1targettarget, etc) or a name (Adreaver-Undermine). Names are case-sensitive and only valid if the named player is a member of your group. Additionally, for Cross-Realm players, omit spaces (but not punctuation) in the realm name (e.g. Jaina-KulTiras, Zekhan-Vol’Jin, etc). A full list of UnitIDs is available at WoWPedia.

Casting a spell [@unit] in this way will allow you to target one unit and cast the macro’d spell at something else. For example, you could set the tank as your focus, and use /use [@focus,help,nodead]Misdirection to cast Misdirection on the tank while still targeting the enemy.

A special unit is [@mouseover], which refers to the unit (or unitframe) you are pointing your cursor at. Particularly useful for healers to cast healing spells on party members without having to change targets, they are also useful for things like interrupts, offensive dispels, and sending your pet to attack one target while you attack another.

Note that [@unit] assumes the unit is there unless you specifically check for it. Use [@unit,harm] to check for enemies, [@unit,help] to check for friendlies, or [@unit,exists] to check for either.

  • [modifier], [mod]

This allows you to cast a different spell when pressing ctrl, shift, or alt. [mod] will register any modifier, while [mod:shift] will only register shift, and ignore ctrl or alt. If desired, you can use multiple modifiers together - [mod:ctrlalt] for example, will only register when pressing ctrl AND alt at the same time.

  • [button], [btn]

This checks which mouse button you used to click the macro. [btn:1] is implied by default, but you can specify [btn:2] for right click, [btn:3] for middle click, and 4/5 for side buttons on your mouse.

  • [exists], [help], [harm], [dead]

These check the status of your target. [exists] simply checks for any target, living or dead, friendly or hostile. [help] and [harm] check for a friendly or hostile target respectively, while [dead] check if your target is dead. [help][harm][dead] all imply [exists] - if your target is dead, you obviously have a target.

  • [combat]

Combat allows you to check if you are in combat. This is helpful when you have certain spells that can only be used out of combat, for example mounts.

#showtooltip
/use [combat]Aspect of the Cheetah;Brown Ram

The above macro would use your Aspect of the Cheetah in combat, and summon your mount out of combat, thus giving you a speed boost in either scenario.

  • [known:Spell Name] or [known:SpellID]

This checks if you know a certain ability (typically a talent). For example, this macro will make you invisible, using Camouflage if known, and a potion if not:

#showtooltip
/use [known:Camouflage]Camouflage;Potion of Concealment

  • [stance], [form]; [stealth]

These check if you are in a stance or form, with [stealth] specifically checking for Stealth (or Prowl, for Cat Form Druids). [stance] and [form] are functionally identical, so you can use either [form:1] or [stance:1] to look for a Druid’s Bear Form. Rogues also have additional stances, with rogues using additional [form:2] for Vanish and [form:3] for Shadow Dance.

  • [equipped], [worn]

This is used to check if you have the specified item type equipped, like [equipped:Shirts] to check if you are wearing a shirt. [worn] is functionally the same but using less characters. You can only check for a specific item type, not for an individual item by name.

  • [pet]

This checks if you have a pet out, and optionally, what kind. [pet] will check for any pet, while [pet:bear] or [pet:imp] will look for that specific type.

  • [spec]

This checks which of your specializations you are currently in. [spec:1] through [spec:4] go in the same order as the Specializations Window, from left to right. Demon Hunters only have 2 specializations, and Druids have 4. All other classes have 3.

  • [actionbar]

This checks which actionbar you are currently on. In the default UI, you may have noticed that you can press Shift+1 through Shift+6 (or click the small arrows to the right of your actionbar) to change your actionbar page, granting you access to an additional row of abilities. This would allow the same macro, placed on two different pages, to function differently depending on which page you were on at any given moment. Primarily used in actionbar swap macros, not particularly useful outside of this limited context.

  • [group], [group:party], [group:raid]

This indicates whether you are in a group. [group] is true for a group of any size, while [group:party] is only true for a 5-man party, and [group:raid] is only true for a raid group, regardless of size.

  • [channeling]

This indicates if you are channeling a spell, like Rapid Fire, Mind Flay, Blizzard, or Soothing Mist. You can use [channeling:SpellName] to check if you are channeling a specific spell, or don’t specify a spell and it will be true if you are channeling any spell. A great usage here is to invert the conditional, which will allow you to spam your abilities near the end of a channel without clipping it early, like so:

#showtooltip Aimed Shot
/use [nochanneling:Rapid Fire]Aimed Shot
  • [indoors], [outdoors], [flyable]

These all refer to the area where you are. If you are outside (in an area where you can summon your mount), [outdoors] will be true. Otherwise, [indoors] will be true. [flyable] is true in areas where flying on a mount is permitted, regardless of whether you have the requisite flying skill learned.

  • [mounted], [flying], [swimming]

These indicate your current movement status. [mounted] checks if you are on a mount of any kind, [flying] checks if you are on a flying mount AND flying in the air, and [swimming] checks if you are in a body of water, regardless of whether or not you are submerged or at the surface.

5. Scripting - What is possible in a macro?

Scripting is an advanced feature sometimes used in macros. Be aware that scripting can’t be used to cast a spell, use an item, or take any other “secure” action. Secure actions are those things which are reserved for the Blizzard UI, and are not available to addons.

Essentially, if you use a script in a macro, you are using a micro-addon. It has all the abilities and limitations of a normal addon, but restricted to a 255 character limit. Useful examples are announcing cooldown or crowd control targets in a raid environment, calculating variables and returning the result (e.g. How many glyphs do I have left to learn?), or making non-protected spell casts (e.g. determining which mount to use based on what zone you are in).

There are far more possibilities available with scripting than I could possibly describe here, so if you have specific questions or a script you want to share, feel free to mention it here or post a new thread.

As a result of some scammers passing off malicious scripts as legitimate, Blizzard has implemented a Lua script warning anytime you run a macro with the “/script” or “/run” commands. You get this same warning if you type a script directly in the chat window without a macro.

The warning is essentially telling players to be careful of running custom scripts they get on the internet or from other players, that they should not run any scripts they do not trust.

6. Classic WoW Macro Changes

There are a few changes to the macro system specific to WoW Classic. For the most part, the API is unchanged, and live macros should work in most cases.

NEW: Spell Ranks

  • Classic WoW returns to the ranking system for spells. Most spells with an absolute value effect (read: not percentage-based) have multiple ranks, which cost an increasing amount of mana (and sometimes have a longer cast time) for higher ranks. Some spells (primarily buffs) are level restricted for certain ranks, (You can’t buff a level 1 character with max rank Blessing of Might or Power Word: Fortitude). Use spell ranks in macros like so:

    • /cast Spell will cast Spell at the highest possible rank for that target. For offensive spells, this will always be the highest rank. For beneficial spells, this will be the highest rank depending on target level.
    • /cast Spell(Rank #) will cast Spell at the specified rank. This is primarily useful for healers to conserve mana, or if you have an offensive spell that applies a debuff and you want the debuff effect but not necessarily the spell damage. Rank 1 Frostbolt for Mages is a common tool for kiting as the mana cost is lower and the cast time is shorter than higher ranks.

REMOVED: Focus (UnitID)

  • In Classic, Focus (and related unitIDs, like focustarget) is not recognized as a valid target for spells.
  • This means that you will need to target the unit you want to cast at. You an use other unitIDs like targettarget, pettarget, or party1target, but this is less reliable as the intermediate unitID can swap to a different target.
  • Mouseover is generally a better option as it is 100% within your control, but it does take more coordination and mouse accuracy than Focus macros from BfA.

REMOVED: Reticle Targeting (Conditionals)

  • In Classic, reticle (ground targeted) spells require two keypresses to activate. The first press will bring up the targeting reticle, and the second press will cast the spell.
  • This is a change from BfA, where you can use [@cursor] to immediately drop the spell on your mouse, or [@player] to immediately drop the spell on yourself.
  • There is no effective workaround for this issue, though it may be helpful to bind these types of spells to additional mouse buttons (Mouse3 (wheel click), Mouse4 (forward), Mouse5 (back), or other buttons as available depending on your mouse), as that doesn’t require the use of both hands to cast a single spell.

7. Macros - Tips, Tricks, and Shortcuts

There are a number of tricks and shortcuts you can use in your macros to make them go a bit further within the 255 character limit. Take a look at some of the examples below, and feel free to submit your own in a reply.

  • /cast and /use can be used interchangeably in most situations (with /use preferring items and /cast preferring spells, if you have a spell and an item with the same name). So in our initial example, you could instead write it as: /use Flash Heal to shorten it by 1 character.

  • Certain conditionals imply other conditionals. For example, [exists] means “if I have a target”. [help] means “if I have a friendly target”. Thus [help] implies [exists]; if you have a friendly target, it is obvious that you have a target. Thus only the [help] condition is needed.

  • Additional whitespace and punctuation are not needed in the macro interface.
    /use [help]Flash Heal is the same as /use [help] Flash Heal. Removing additional whitespace can be helpful with complex macros when trying to stay below the 255 character limit.

  • Multiple modifiers can be used in the same macro command. For example, the following macro combines a number of useful teleport spells for a Mage, as well as Hearthstones, and Blink, into a single line:
#showtooltip
/use [mod:ctrlaltshift]Teleport:Shattrath;[mod:ctrlalt]Teleport:Dalaran;[mod:ctrlshift]Teleport:Stormshield;[mod:altshift]Teleport:Vale of Eternal Blossoms;[mod:ctrl]Teleport:Stormwind;[mod:alt]Garrison Hearthstone;[mod]Hearthstone;Blink
  • You can use the following script (courtesy of @Ehiztari) to pull an up-to-date listing of all the slash commands available to your client at any time. These commands can then be used in macros.
function CommandList()

  local HT = {}
  HT.Commands = {}
  HT.NormalizedCommands = {}

  for key, value in pairs(_G) do
    if strsub(key, 1, 6) == "SLASH_" then
      local cTypeKey = gsub(key, "%d+$", "")
      for cSeq = 1, 20 do
        local cPrime = cTypeKey.."1"
        local cKey = cTypeKey..tostring(cSeq)
        if _G[cPrime] and _G[cKey] then
          if strsub(_G[cPrime], 1, 1) == "/" and 
             strsub(_G[cKey], 1, 1) == "/" then
            HT.Commands[_G[cKey]] = _G[cPrime]
            if HT.NormalizedCommands[_G[cPrime]] then
            -- skip it
            else
            -- make it
              HT.NormalizedCommands[_G[cPrime]] = {}
            end
            HT.NormalizedCommands[_G[cPrime]][_G[cKey]] = true
          end
        else
          break
        end
      end
    end
  end
  return CopyTable(HT)

end
  • I will put some info about off-GCD abilities here, but need to do some research before I write this up as I am not familiar with the BfA changes for anyone other than Hunters.

www.macroexplain.com

  • This is a great resource for players writing macros, particularly those who are inexperienced. You copy and paste your macro into this web site, and it will tell you, in plain text, what the macro will do. It will also let you know how much room you have to expand the macro, if you go over the 255 character limit, and if you have any errors. This site does have some limitations: it is not up to date on many of the more recent syntax changes, and it is missing a large amount of spell data, but the basic functionality works very well.

Okay, that should be all the (still relevant) content from the original thread, migrated to the new forum and taking full advantage of the new markdown syntax. If anyone has suggestions for adds/changes, please let me know.

Changelog

Changelog 20230122:

  • Removed [talent] which is deprecated and nonfunctional in 10.x.
  • Added [known] with description and example.
  • Added missing example for [channeling].

Changelog 20200110:

  • Clarified the functionality of [@unit] with an example.

Changelog 20200105:

  • Added caveat regarding [@unit] requiring an existence check to function properly.
46 Likes

From the old forums

(I miss you old forum :sob: )

Macros - What Every Player Needs to Know
https://us.battle.net/forums/en/wow/topic/16200990425

External Links

Intro to Making Macros
http://wowwiki.wikia.com/wiki/Making_a_macro

Macro Syntax
https://wow.gamepedia.com/Macro_commands

/cast Syntax
https://wow.gamepedia.com/MACRO_cast

Macro Conditionals
https://wow.gamepedia.com/Macro_conditionals

Unit IDs
https://wow.gamepedia.com/UnitId

FItzcairn’s Macro Explain-o-matic
http://www.macroexplain.com/
inb4 a certain someone says, “It’s out of date doesn’t always work”. Yep, that’s true but it’s still useful for the macro novice.

5 Likes

Forgot to Add

EB’s amazo using macro’s to condense your physical keys
https://us.forums.blizzard.com/en/wow/t/macros-condensing-your-physical-keys/16422/33

It’s actually messed up cuz I tried to edit it to update it to the new markdown :frowning:

1 Like

Due to the whole trust baloney preventing links need to put links in side these: `

It allowed those cuz they’re links to the same forums
But it like completely tossed out the formatting including line breaks

Also, if you want to make code blocks (rather than inline code), surround your code in `x3

Yay… managed to fix the formatting in my posts a bit and get the links updated

1 Like

Grats on getting the sticky back @Adreaver

1 Like

I’m actually going to report that thread and request the sticky be removed and the thread locked. Since it migrated from the old forums, and I have transferred servers twice since the OP was originally written back in 2015, I can’t edit it anymore to fix the formatting or correct the outdated info (the GCD section is particularly out of date).

I’m currently in the process of reorganizing the guide to go into the OP here, and will be requesting a sticky for this thread instead.

@Tinkerizmo please remove the link to my old thread from your first post - the entirety of the relevant content has been copied to the OP here, and between the formatting changes and BfA spell changes I think the old thread is best left on the old forums.

@Adreaver might want to mention

[this, and this]
[this] [or this]

as it seems to be a pretty common confusion for beginners.

1 Like

This is a “how-to” guide, not a history lesson. Historical API changes, while interesting in their own right, are not relevant for the purpose of this guide.

If you can provide any current examples (current meaning exists in game as of 8.0, not necessarily related to BfA content), I am happy to amend that portion. Otherwise, it stands as is - the commands are functionally identical, in that they are used the same way and the result (i.e. what action is taken by the player) is the same regardless of which command you use.

Again, happy to modify this if you can provide examples. /run executes the code that follows the same as if that code was dropped in an addon.lua file, properly called by a .toc file, and there was a command or event to execute the code at the given time.

Circumventing the character limit with /click chains does not remove the 255 character limit per statement. You can’t pass vars between macros, even /click chained macros, so the point stands.

This is also way more in depth than I want to go here - this is meant to be comprehensive information about macros, not about scripting in Lua.

I will definitely add /click to the slash command section, as it ought to be covered.

Will do, this was an oversight.

An oversight - see above.

I will make a note of that. When I have more time, I will pull a listing and include them all, but for now I will just link to your post.

CastRandom, UseRandom, and CastSequence Silliness

/castrandom SharedNameBetweenItemAndSpell,SomeSpell,SomeItem

That will make use of the ITEM preferentially in the first step, not the spell.

The handler for /userandom literally is just a pointer to the handler for /castrandom as you can see from lines 1246 to 1258 of ChatFrame.lua:

SecureCmdList["CASTRANDOM"] = function(msg)
    local actions, target = SecureCmdOptionParse(msg);
  if ( actions ) then
    local action = ExecuteCastRandom(actions);
    local name, bag, slot = SecureCmdItemParse(action);
    if ( slot or GetItemInfo(name) ) then
      SecureCmdUseItem(name, bag, slot, target);
    else
      CastSpellByName(action, target);
    end
  end
end
SecureCmdList["USERANDOM"] = SecureCmdList["CASTRANDOM"];

/castsequence makes preferential use of items over spells or abilities as well.

The portion of the handler that manages this is lines 998 to 1021 of ChatFrame.xml:

  -- Execute the sequence!
  local item, spell = entry.items[entry.index], entry.spells[entry.index];
  if ( item ) then
    local name, bag, slot = SecureCmdItemParse(item);
    if ( slot ) then
      local spellID;
      if ( name ) then
        local spellName;
        spellName, spellID = GetItemSpell(name);
        spell = strlower(spellName or "");
      else
        spell = "";
      end
      entry.spellNames[entry.index] = spell;
      entry.spellID[entry.index] = spellID;
    end
    if ( IsEquippableItem(name) and not IsEquippedItem(name) ) then
      EquipItemByName(name);
    else
      SecureCmdUseItem(name, bag, slot, target);
    end
  else
    CastSpellByName(spell, target);
  end

I haven’t been able to determine a consistent pattern for #showtooltip as it seems to give different results for item or spell/ability in different situations and I haven’t located the code that governs it (it may not be visible to use).

Do you have any example where the /use vs /cast issue is relevant? Any items and spells that share a name and could conceivably both be usable by the same character at the same time?

When I say functionally identical, I mean they perform the same function in the same way. Which they do.

You seem to be missing the point of this guide: a quick, easy to digest write-up of some of the most common macro questions that come in this forum on a day to day basis. I’m not writing scripting guide, or a dissection of chatframe.lua, that is way outside scope for what I am trying to do here.

1 Like

I haven’t noticed anything in BFA yet but in Legion DKs had both a Horn of Winter item and talent.

1 Like

You could just adjust the TargetPriorityPvp CVar instead:
1 - default
2 - prioritize all pvp targets
3 - prioritize players only

/run SetCVar("TargetPriorityPvp", 3)

Has no effect outside of PVP so there’s no need to unset it.

Changelog 20181118:

  • Added [this, and that] vs [this][or that] explanation. (Elvenbane)
  • Clarified /use vs /cast. (Ehiztari)
  • Added explanation of /click. (Ehiztari)
  • Added script to dump all valid /commands to Tips and Tricks. (Ehiztari)
  • Removed outdated PvP tab targeting tip, instead use the TargetPriorityPvp CVar (Elvenbane)
2 Likes

That looks very good, @Adreaver. Thank you for making the updates and for putting the time in to create this.

I deleted all of my conversational posts from the thread except one that seemed to offer relevant data for those wishing to dig deeper and I edited it to be a stand-alone post.

2 Likes

I thought /userandom was still broken? Have I missed something, cause my random mount macros are still not working (they summon a new mount only after a reload)

It is, as far as I am aware.