From 89c705b922ef2dedd5c045b384f130c8037c24c4 Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Mon, 14 Sep 2026 01:38:13 -0500 Subject: [PATCH] docs: describe the four macro commands added today Covers /castsequence, /castrandom, /userandom and /stopmacro in the Lua reference, plus StopMacro beside GetMacroSpell, and updates the README groups and counts. Two caveats are worth having written down rather than found: a list names no single action, so the random commands give the action button nothing to show, and being static lines they end the #showtooltip collection -- a /castrandom above a /cast takes the icon from it. --- README.md | 12 ++++--- docs/API.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c8d7e3d5..6336281c 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ reference in **[docs/API.md](docs/API.md)**. | [LootHistory](docs/API.md#loothistory) | `C_LootHistory.GetNumItems`, `C_LootHistory.GetItem`, `C_LootHistory.GetPlayerInfo`, `C_LootHistory.Clear` | | [LossOfControl](docs/API.md#lossofcontrol) | `C_LossOfControl.GetActiveLossOfControlData`, `C_LossOfControl.GetActiveLossOfControlDataCount` | | [Lua](docs/API.md#lua) | `collectgarbage` (5.1 options), `coroutine.create`, `coroutine.resume`, `coroutine.running`, `coroutine.status`, `coroutine.wrap`, `coroutine.yield`, `CreateFromMixins`, `math.fmod`, `math.huge`, `math.modf`, `Mixin`, `select`, `string.gmatch`, `string.gsub` (table replacement), `string.match`, `string.reverse`, `strjoin`, `strreplace`, `strrev`, `strsplit`, `strtrim`, `table.count`, `table.maxn`, `table.wipe`, `unpack` (range args), `xpcall` (argument forwarding) | -| [Macros](docs/API.md#macros) | `C_Macro.CreateMacro`, `C_Macro.EditMacro`, `C_Macro.SetMacroDisplay`, `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItem`, `GetMacroItemIcons`, `GetMacroSpell` | +| [Macros](docs/API.md#macros) | `C_Macro.CreateMacro`, `C_Macro.EditMacro`, `C_Macro.SetMacroDisplay`, `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItem`, `GetMacroItemIcons`, `GetMacroSpell`, `StopMacro` | | [Mail](docs/API.md#mail) | `GetInboxItemLink`, `GetSendMailItemLink` | | [Map](docs/API.md#map) | `C_Map.CanSetUserWaypointOnMap`, `C_Map.ClearUserWaypoint`, `C_Map.GetAreaInfo`, `C_Map.GetAreas`, `C_Map.GetAreaTriggerInfo`, `C_Map.GetAreaTriggers`, `C_Map.GetBestMapForUnit`, `C_Map.GetFallbackWorldMapID`, `C_Map.GetMapAreaIDs`, `C_Map.GetMapArtLayers`, `C_Map.GetMapArtLayerTextures`, `C_Map.GetMapChildrenInfo`, `C_Map.GetMapInfo`, `C_Map.GetMapInfoAtPosition`, `C_Map.GetMapOverlays`, `C_Map.GetMapPosFromWorldPos`, `C_Map.GetMapRectOnMap`, `C_Map.GetMapWorldSize`, `C_Map.GetPlayerMapPosition`, `C_Map.GetUserWaypoint`, `C_Map.GetUserWaypointFromHyperlink`, `C_Map.GetUserWaypointHyperlink`, `C_Map.GetUserWaypointPositionForMap`, `C_Map.GetWorldPosFromMapPos`, `C_Map.HasUserWaypoint`, `C_Map.MapHasArt`, `C_Map.SetUserWaypoint` | | [MapExplorationInfo](docs/API.md#mapexplorationinfo) | `C_MapExplorationInfo.GetExploredMapTextures`, `C_MapExplorationInfo.GetUnexploredMapTextures` | @@ -150,7 +150,7 @@ details. | Form | What it does | |------|--------------| | `#showtooltip [conditions] Value` | First line of a macro. Sets what the button shows. Bare `#showtooltip` follows the first `/cast` or `/use` line instead. `#show` is the same form. | -| `[conditions]` and `@unit` | Accepted by 38 commands. The slash-command list below names them. | +| `[conditions]` and `@unit` | Accepted by 42 commands. The slash-command list below names them. | | `!Name` | Starts an ability but never turns it off. Use it for auto-repeat shots and for the self-buffs (stance, aspect, seal, form, tracking). | | A line that starts with `#` | A comment. The line never reaches chat. | | `/cast ` | For a spell you know, `/cast 5019` casts it by ID. The macro slot also tags correctly for an action-bar addon. | @@ -160,17 +160,19 @@ details.
-Slash commands — [conditions] on 38 commands +Slash commands — [conditions] on 42 commands The bundled addon registers these commands. Each one takes the same `[conditions]` and `@unit` syntax as `/cast`. Each client language has its own command names next to the English ones. See [More commands with `[conditions]`](docs/API.md#more-commands-with-conditions) -for what each command does. +for what each command does, and +[`/castsequence`](docs/API.md#castsequence) and +[`/castrandom`](docs/API.md#castrandom-and-userandom) for the list forms. | Group | Commands | |-------|----------| -| Casting | `/cast`, `/use`, `/stopcasting`, `/cancelaura`, `/cancelform`, `/dismount` | +| Casting | `/cast`, `/use`, `/castsequence`, `/castrandom`, `/userandom`, `/stopcasting`, `/stopmacro`, `/cancelaura`, `/cancelform`, `/dismount` | | Targeting | `/target`, `/targetexact`, `/cleartarget`, `/targetlasttarget`, `/targetlastenemy`, `/targetenemy`, `/targetfriend`, `/targetenemyplayer`, `/targetfriendplayer`, `/targetparty`, `/targetraid`, `/assist`, `/follow`, `/focus`, `/clearfocus`, `/startattack`, `/stopattack` | | Equipment | `/equip`, `/equipslot`, `/equipset` | | Action bars | `/changeactionbar`, `/swapactionbar`, `/click` | diff --git a/docs/API.md b/docs/API.md index afb65e8b..2f546dda 100644 --- a/docs/API.md +++ b/docs/API.md @@ -462,10 +462,13 @@ build instructions. - [Macros](#macros) - [`/cast` and `/use`](#cast-and-use) + - [`/castsequence`](#castsequence) + - [`/castrandom` and `/userandom`](#castrandom-and-userandom) - [More commands with `[conditions]`](#more-commands-with-conditions) - [`#showtooltip` and `#show`](#showtooltip-and-show) - [Numeric spellIDs in `/cast` and `CastSpellByName`](#numeric-spellids-in-cast-and-castspellbyname) - [`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) + - [`StopMacro()`](#stopmacro) - [`GetMacroSpell(macroSlot)`](#getmacrospellmacroslot) - [`GetMacroItem(macroSlot)`](#getmacroitemmacroslot) - [`GetMacroIcons` / `GetMacroItemIcons` / `GetLooseMacroIcons` / `GetLooseMacroItemIcons`](#getmacroicons--getmacroitemicons--getloosemacroicons--getloosemacroitemicons) @@ -11200,6 +11203,76 @@ If SuperCleveRoidMacros is loaded, it handles `/cast` lines that contain conditions and all `/use` lines. Plain `/cast Name` lines still go through ClassicAPI. +### `/castsequence` + +Casts one action from a list, and moves to the next one each time a cast +succeeds. The list is separated by commas and takes the same +`[conditions]` and `@unit` syntax as `/cast`. + +``` +/castsequence Insect Swarm, Moonfire, Wrath +/castsequence [@focus] Insect Swarm, Moonfire, Wrath +/castsequence reset=combat Immolate, Corruption, Shadow Bolt +``` + +Each step is read the same way a `/cast` value is, so a step can name a +spell, an item you carry, a `bag slot`, or an inventory slot. A step that +names an item you can equip, and are not wearing, equips it instead of +using it. + +The sequence moves on only when a cast succeeds. A cast that fails or is +interrupted leaves the sequence where it is, so the next press tries the +same step again. A step that names nothing castable is stepped past. + +`reset=` restarts the sequence. It takes one or more of these, joined by +`/`: + +| Value | Restarts when | +|---|---| +| `target` | Your target changes. | +| `combat` | You leave combat. | +| `shift`, `ctrl`, `alt` | You press the button with that key held. | +| A number | That many seconds pass without a press. | + +``` +/castsequence reset=target/3 Rend, Thunder Clap +``` + +The sequence is keyed by its text. Two macros with the same list share one +position and advance together, and the same list in one macro on two action +bars is one sequence. + +With [`#showtooltip`](#showtooltip-and-show), the action button follows the +step the sequence is on. + +### `/castrandom` and `/userandom` + +Casts one action picked at random from a comma-separated list. Both names +are the same command, the way `/use` is `/cast` under a second name, so +either one casts a spell or uses an item. + +``` +/castrandom Moonfire, Starfire, Wrath +/userandom [@player] Healing Potion, Rejuvenation Potion +``` + +The pick is held until a cast succeeds. A cast that fails or is interrupted +keeps the same pick, so the next press tries that action again rather than +picking another one. + +A list names no single action, so these commands give the action button +nothing to show. The button has no tooltip, no cooldown and no usable state +from the list. Name a value on the +[`#showtooltip`](#showtooltip-and-show) line to give it one: + +``` +#showtooltip Moonfire +/castrandom Moonfire, Starfire, Wrath +``` + +A `/castrandom` line above a `/cast` line also takes the icon from it. Put +the `/cast` line first, or name the value on the `#showtooltip` line. + ### More commands with `[conditions]` These commands take the same `[conditions]` and `@unit` syntax as `/cast`. @@ -11240,6 +11313,7 @@ The stepping commands treat their value as a reverse flag, so | Command | Does | |---|---| | `/stopcasting` | Stops the current cast. | +| `/stopmacro` | Stops the rest of the macro. | | `/cancelaura` | Removes one of your buffs by name. | | `/cancelform` | Leaves your current shapeshift form. | | `/dismount` | Dismounts you. | @@ -11250,6 +11324,16 @@ The stepping commands treat their value as a reverse flag, so /stopcasting [mod:alt] ``` +`/stopmacro` stops the macro that is running it. The lines after it do not +run. A line that runs a second macro is not affected: a `/stopmacro` in that +second macro stops the second one, and the first one goes on. + +``` +/cast Moonfire +/stopmacro [mod:shift] +/cast Wrath +``` + **Equipment.** `/equip` takes an item name, and `/equipslot` takes an inventory slot number from 1 to 19 followed by an item name. @@ -11432,6 +11516,21 @@ Macro tagging happens at macro edit/save time. Existing macros need to be opened in the Macro UI and re-saved once after dropping in the new DLL to pick up the new parser behavior. +### `StopMacro()` + +Stops the macro body that is running right now. The lines after the call do +not run. This is what [`/stopmacro`](#more-commands-with-conditions) calls +once its conditions pass. + +```lua +StopMacro() +``` + +The call applies to the macro that is running it. If a macro line runs a +second macro, a `StopMacro` in that second macro stops the second one only, +and the first one goes on. A call made while no macro is running does +nothing, and leaves nothing behind for the next macro you press. + ### `GetMacroSpell(macroSlot)` Returns `(name, rank, spellID)` for the spell that a macro shows. When the