feat(macro): SetMacroDisplay range unit

C_Macro.SetMacroDisplay(macroSlot, value [, unit]) takes the unit the
button's range check uses, so a publisher's [@unit] reaches the range
check as SetMacroSpell's target does. The token stays a token: each
lookup resolves it again, so the range follows a new mouseover, focus or
target with no republish. A token that names no unit leaves the target
in charge.

The engine's resolver vets the unit at publish and raises its "Unknown
unit name" error for anything else, as UnitExists does. It tells a
token's family from its spelling alone, so a token that passes once
never raises at a later lookup. The unit is ignored for false and for an
empty value, and a publish that changes only the unit updates it.
This commit is contained in:
Brues
2026-10-28 23:19:36 -05:00
parent a46d823b01
commit e0e24bab34
4 changed files with 76 additions and 15 deletions
+34 -8
View File
@@ -644,7 +644,7 @@ build instructions.
- [`GetMacroIcons` / `GetMacroItemIcons` / `GetLooseMacroIcons` / `GetLooseMacroItemIcons`](#getmacroicons--getmacroitemicons--getloosemacroicons--getloosemacroitemicons)
- [`C_Macro.CreateMacro` / `C_Macro.EditMacro`](#c_macrocreatemacro--c_macroeditmacro)
- [`C_Macro.GetMacroIcon(macroSlot)`](#c_macrogetmacroiconmacroslot)
- [`C_Macro.SetMacroDisplay(macroSlot, value)`](#c_macrosetmacrodisplaymacroslot-value)
- [`C_Macro.SetMacroDisplay(macroSlot, value [, unit])`](#c_macrosetmacrodisplaymacroslot-value--unit)
- [Mail](#mail)
- [`GetSendMailItemLink([attachmentIndex])`](#getsendmailitemlinkattachmentindex)
@@ -14968,7 +14968,7 @@ to.
If SuperCleveRoidMacros is loaded, it controls macro display, and ClassicAPI
does not evaluate `#showtooltip`. A build that hands its own results over
through
[`C_Macro.SetMacroDisplay`](#c_macrosetmacrodisplaymacroslot-value) keeps
[`C_Macro.SetMacroDisplay`](#c_macrosetmacrodisplaymacroslot-value--unit) keeps
`#showtooltip` working for the macros it does not claim.
A macro that names a condition
@@ -15342,7 +15342,7 @@ mark, and the macro's own icon otherwise.
selector edits. Use this function when you want the icon a macro shows, and
`GetMacroInfo` when you want the one the player picked.
### `C_Macro.SetMacroDisplay(macroSlot, value)`
### `C_Macro.SetMacroDisplay(macroSlot, value [, unit])`
Tells the client what a macro is about, so the action button shows it. For
an addon that parses macros itself and wants the button to follow, instead
@@ -15350,9 +15350,10 @@ of replacing `GetActionTexture`, `GetActionCooldown`, `IsUsableAction` and
the rest in Lua.
```lua
C_Macro.SetMacroDisplay(1, "Frostbolt") -- show this
C_Macro.SetMacroDisplay(1, false) -- mine, nothing matched, show ?
C_Macro.SetMacroDisplay(1, nil) -- released, `#showtooltip` resumes
C_Macro.SetMacroDisplay(1, "Frostbolt") -- show this
C_Macro.SetMacroDisplay(1, "Flash Heal", "mouseover") -- show this, range to the mouseover
C_Macro.SetMacroDisplay(1, false) -- mine, nothing matched, show ?
C_Macro.SetMacroDisplay(1, nil) -- released, `#showtooltip` resumes
```
`macroSlot` is the macro index, the same one
@@ -15366,6 +15367,31 @@ it, the same as a directive that names its own value.
Returns `true` when the value named a spell or an item.
**The range unit.** `unit` is optional. It names the unit that the button's
range check uses in place of your target. Usually it is the `[@unit]` of the
clause that your parser matched. It takes any unit token or GUID string that
`UnitExists` takes, for example `"mouseover"`, `"focus"` or
`"party2target"`. If you give no `unit`, or `nil`, the range check uses your
target.
The client finds the unit again each time it checks the button's range. So
if `"mouseover"` moves to a different unit, the range follows it with no new
call. The same is true for `"focus"`, `"target"` and every other token. This
is different from the `target` of
[`SetMacroSpell`](#setmacrospellmacro-spell--target--setmacroitemmacro-item--target),
which is found once, when you call it.
If the token points at no unit at that time, for example `"mouseover"` with
nothing under the cursor, the range check uses your target. If the unit is
too far away for the client to see it, for example a party member in another
zone, the button has no range state.
The function ignores `unit` when `value` is `false`, `nil` or an empty
string, because the macro then aims at nothing. A call with the same `value`
and a different `unit` changes the unit. If `unit` is not a unit token, the
function raises the error `Unknown unit name: <unit>`, the same error that
`UnitExists` gives. Then it publishes nothing.
**What the button picks up.** The spell is written where the client keeps
each macro's spell, which is the field its own buttons read. So cooldown,
range, usable, out-of-mana greying, the current-cast highlight and
@@ -15379,8 +15405,8 @@ button, on the cursor while you drag the macro, and in the macro window.
The icon replaces the macro's own only when that is the question mark, which
is the same rule `#showtooltip` follows. A macro with a chosen icon keeps it.
**Call it whenever your answer changes.** Nothing is re-evaluated for you.
The value stands until you publish another, and it survives the client
**Call it whenever your answer changes.** Nothing is re-evaluated for you,
except the unit that a `unit` token points at. The value stands until you publish another, and it survives the client
re-reading the macro, so an edit elsewhere cannot quietly replace it.
Publishing takes the macro over: `#showtooltip` is not parsed for it while
+20 -3
View File
@@ -11,7 +11,7 @@
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
// `C_Macro.SetMacroDisplay(macroSlot, value)` — the Lua door onto
// `C_Macro.SetMacroDisplay(macroSlot, value [, unit])` — the Lua door onto
// `Macro::ShowTooltip::Publish`, for an addon that has its own macro parser
// and wants the display done properly rather than by replacing the action
// globals. See the ShowTooltip header for what publishing buys.
@@ -27,6 +27,12 @@
// item-before-spell precedence, `item:N`, links, inventory slots and
// `bag slot` for free.
//
// `unit` is the `[@unit]` the publisher's clause matched: the unit the
// button's range check uses. Unlike `SetMacroSpell`'s target it stays a
// token, resolved at every lookup (`PublishOptions::liveUnit`), so a
// publisher whose clause still matches need not republish when the
// mouseover, focus or target moves.
//
// `SetMacroSpell(macro, spell [, target])` and `SetMacroItem(macro, item
// [, target])` are 4.3.4's narrower doors onto the same publish: a spellbook
// spell only, or an item only, aimed at `target` (the unit the button's range
@@ -37,6 +43,7 @@
#include "Offsets.h"
#include "macro/Arg.h"
#include "macro/ShowTooltip.h"
#include "unit/Identity.h"
#include <cstdint>
@@ -46,7 +53,7 @@ namespace {
int __fastcall Script_C_Macro_SetMacroDisplay(void *L) {
if (!Game::Lua::IsNumber(L, 1)) {
Game::Lua::Error(L, "Usage: C_Macro.SetMacroDisplay(macroSlot, value)");
Game::Lua::Error(L, "Usage: C_Macro.SetMacroDisplay(macroSlot, value [, unit])");
return 0;
}
const int macroSlot = static_cast<int>(Game::Lua::ToNumber(L, 1));
@@ -63,7 +70,17 @@ int __fastcall Script_C_Macro_SetMacroDisplay(void *L) {
}
const char *value = Game::Lua::IsString(L, 2) ? Game::Lua::ToString(L, 2) : nullptr;
Game::Lua::PushBoolean(L, Macro::ShowTooltip::Publish(macroSlot, value) ? 1 : 0);
Macro::ShowTooltip::PublishOptions options;
// A value that names nothing aims at nothing, so its unit is not read.
if (value != nullptr && value[0] != '\0' && Game::Lua::IsString(L, 3)) {
options.unit = Game::Lua::ToString(L, 3);
options.liveUnit = true;
// The engine's resolver vets the token: anything that is not one
// raises its "Unknown unit name" error, exactly as UnitExists does,
// before anything is published.
Unit::Identity::GuidForToken(options.unit);
}
Game::Lua::PushBoolean(L, Macro::ShowTooltip::Publish(macroSlot, value, options) ? 1 : 0);
return 1;
}
+12 -2
View File
@@ -160,6 +160,9 @@ struct Entry {
uint32_t isPet = 0;
int itemID = 0;
uint64_t unit = 0; // Info::unit
// A published `PublishOptions::liveUnit` token, resolved afresh by every
// lookup in place of `unit`. Empty for none.
char unitToken[kOptionsMax] = {};
uint32_t lastEvalMs = 0;
};
@@ -1233,7 +1236,8 @@ bool LookupEntries(uint32_t macroID, Info *out) {
out->spellID = e.spellID;
out->isPet = e.isPet;
out->itemID = e.itemID;
out->unit = e.unit;
out->unit = e.unitToken[0] != '\0' ? ::Unit::Identity::GuidForToken(e.unitToken)
: e.unit;
// A publisher re-publishes the moment its answer changes, so a claimed
// macro never needs the polling refresh a condition of ours does.
out->conditional = false;
@@ -1327,7 +1331,13 @@ bool Publish(int macroSlot, const char *value, const PublishOptions &options) {
ResolveValue(value, &r, /*explicitValue=*/true,
/*itemOnly=*/options.accept == Accept::Item);
}
r.unit = UnitGuid(options.unit);
// Set on every publish, so one that changes only the unit still lands:
// `ApplyResolution` stores the unit before its unchanged-value early out.
if (options.liveUnit && options.unit != nullptr)
std::snprintf(e.unitToken, sizeof(e.unitToken), "%s", options.unit);
else
e.unitToken[0] = '\0';
r.unit = options.liveUnit ? 0 : UnitGuid(options.unit);
BusyScope busy;
ApplyResolution(L, e, r, matched);
+10 -2
View File
@@ -72,8 +72,10 @@ struct Info {
// from it has to keep re-reading while the cursor rests on the button.
bool conditional;
// The unit the macro's spell is aimed at, 4.3.4's MACRONODE::m_target: the
// `[@unit]` of the clause that matched, or the target a `SetMacroSpell` /
// `SetMacroItem` named. 0 means the current target, as for any action.
// `[@unit]` of the clause that matched, the target a `SetMacroSpell` /
// `SetMacroItem` named, or whoever the token a `SetMacroDisplay` named
// points at as of this lookup. 0 means the current target, as for any
// action.
uint64_t unit;
};
@@ -86,6 +88,12 @@ struct PublishOptions {
Accept accept = Accept::Any;
// A unit token or a name the spell is aimed at; null for the current target.
const char *unit = nullptr;
// Resolve `unit` at every lookup rather than once, here, so the macro
// keeps following whoever the token names (a new mouseover, focus or
// target) with no republish. `unit` must then be a token the engine's
// resolver accepts: one that resolves once never raises later, since the
// resolver tells a token's family from its spelling alone.
bool liveUnit = false;
// The claim ends when the macro's body is edited, as 4.3.4's SetMacroSpell
// and SetMacroItem last only until the macro is parsed again. Otherwise it
// lasts until `Release` or a reload.