From e26f8fb49e3359c9d208da0aadbb441108c62443 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Wed, 28 Oct 2026 15:07:29 -0500
Subject: [PATCH] feat: ConsoleAddMessage, CursorHasMacro, GetMacroBody
GetMacroBody shares the index-or-name macro argument with SetMacroSpell /
SetMacroItem through the new Macro::Arg::Slot.
---
README.md | 6 ++--
docs/API.md | 26 +++++++++++++++++
src/console/Shell.cpp | 23 +++++++++++++++
src/cursor/Info.cpp | 16 +++++++++++
src/macro/Arg.cpp | 38 +++++++++++++++++++++++++
src/macro/Arg.h | 24 ++++++++++++++++
src/macro/Body.cpp | 65 +++++++++++++++++++++++++++++++++++++++++++
src/macro/Display.cpp | 20 ++-----------
8 files changed, 197 insertions(+), 21 deletions(-)
create mode 100644 src/macro/Arg.cpp
create mode 100644 src/macro/Arg.h
create mode 100644 src/macro/Body.cpp
diff --git a/README.md b/README.md
index 6da455a7..0e26c222 100644
--- a/README.md
+++ b/README.md
@@ -64,9 +64,9 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th
| [ColorUtil](docs/API.md#colorutil) | `C_ColorUtil.ConvertRGBToHSV`, `C_ColorUtil.ConvertHSVToRGB`, `C_ColorUtil.ConvertHSVToHSL`, `C_ColorUtil.ConvertHSLToHSV`, `C_ColorUtil.ConvertHSLToRGB`, `C_ColorUtil.GenerateTextColorCode`, `C_ColorUtil.WrapTextInColor`, `C_ColorUtil.WrapTextInColorCode` |
| [Combat](docs/API.md#combat) | `InCombatLockdown`, `StartAttack`, `StopAttack` |
| [CombatLog](docs/API.md#combatlog) | `CombatLogGetCurrentEventInfo`, `COMBATLOG_OBJECT_*` (constants) |
-| [Console](docs/API.md#console) | `CalculateStringEditDistance`, `ConsoleEcho`, `ConsoleExec`, `ConsoleGetAllCommands`, `ConsoleGetColorFromType`, `ConsoleGetFontHeight`, `ConsoleIsActive`, `ConsolePrintAllMatchingCommands`, `SetConsoleKey` |
+| [Console](docs/API.md#console) | `CalculateStringEditDistance`, `ConsoleAddMessage`, `ConsoleEcho`, `ConsoleExec`, `ConsoleGetAllCommands`, `ConsoleGetColorFromType`, `ConsoleGetFontHeight`, `ConsoleIsActive`, `ConsolePrintAllMatchingCommands`, `SetConsoleKey` |
| [CVar](docs/API.md#cvar) | `C_CVar.AreCVarsLoaded`, `C_CVar.DoesCVarExist`, `C_CVar.GetCVarBitfield`, `C_CVar.GetCVarBool`, `C_CVar.GetCVarInfo`, `C_CVar.RemoveTempCVar`, `C_CVar.SetCVar`, `C_CVar.SetCVarBitfield`, `C_CVar.SetTempCVar`, `GetCVar`, `GetCVarDefault` |
-| [Cursor](docs/API.md#cursor) | `GetCursorInfo` |
+| [Cursor](docs/API.md#cursor) | `CursorHasMacro`, `GetCursorInfo` |
| [Container](docs/API.md#container) | `C_Container.AutoStoreItem`, `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemInfo`, `C_Container.GetContainerItemEquipmentSetInfo`, `C_Container.GetContainerItemQuestInfo`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerFreeSlots`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetBackpackAutosortDisabled`, `C_Container.GetBankAutosortDisabled`, `C_Container.GetItemCooldown`, `C_Container.GetSortBagsRightToLeft`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SetBackpackAutosortDisabled`, `C_Container.SetBagPortraitTexture`, `C_Container.SetBankAutosortDisabled`, `C_Container.SetSortBagsRightToLeft`, `C_Container.SortBags`, `C_Container.SortBankBags`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown`, `SetBagPortraitTexture` |
| [Creature](docs/API.md#creature) | `C_CreatureInfo.GetCreatureID`, `C_CreatureInfo.GetCreatureInfoByID`, `C_CreatureInfo.RequestLoadCreatureByID`, `C_CreatureInfo.GetRaceInfo`, `C_CreatureInfo.GetClassInfo`, `C_CreatureInfo.GetCreatureFamilyInfo`, `C_CreatureInfo.GetCreatureFamilyIDs`, `C_CreatureInfo.GetFactionInfo`, `C_CreatureInfo.GetCreatureTypeInfo`, `C_CreatureInfo.GetCreatureTypeIDs` |
| [Currency](docs/API.md#currency) | `GetCoinText`, `C_CurrencyInfo.GetCoinText`, `GetCoinTextureString`, `C_CurrencyInfo.GetCoinTextureString` |
@@ -103,7 +103,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th
| [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`, `C_LossOfControl.GetSchoolLockout` |
| [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`, `strcmputf8i`, `strconcat`, `string.concat`, `string.gmatch`, `string.gsub` (table replacement), `string.join`, `string.match`, `string.reverse`, `string.split`, `string.trim`, `strjoin`, `strlenutf8`, `strmatch`, `strreplace`, `strrev`, `strsplit`, `strsplittable`, `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`, `DeleteMacro` / `EditMacro` / `GetMacroInfo` / `PickupMacro` by name, `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItem`, `GetMacroItemIcons`, `GetMacroSpell`, `GetRunningMacro`, `GetRunningMacroButton`, `RunMacroText`, `SetMacroItem`, `SetMacroSpell`, `StopMacro` |
+| [Macros](docs/API.md#macros) | `C_Macro.CreateMacro`, `C_Macro.EditMacro`, `C_Macro.SetMacroDisplay`, `DeleteMacro` / `EditMacro` / `GetMacroInfo` / `PickupMacro` by name, `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroBody`, `GetMacroIcons`, `GetMacroItem`, `GetMacroItemIcons`, `GetMacroSpell`, `GetRunningMacro`, `GetRunningMacroButton`, `RunMacroText`, `SetMacroItem`, `SetMacroSpell`, `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.GetExploredAreaIDsAtPosition`, `C_MapExplorationInfo.GetExploredMapTextures`, `C_MapExplorationInfo.GetUnexploredMapTextures` |
diff --git a/docs/API.md b/docs/API.md
index 5b0d43aa..2f38d079 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -102,6 +102,7 @@ build instructions.
- [Console](#console)
- [`ConsoleExec(command)`](#consoleexeccommand)
+ - [`ConsoleAddMessage(message)`](#consoleaddmessagemessage)
- [`ConsoleEcho(message [, colorType])`](#consoleechomessage--colortype)
- [`ConsolePrintAllMatchingCommands(prefix)`](#consoleprintallmatchingcommandsprefix)
- [`ConsoleIsActive()`](#consoleisactive)
@@ -173,6 +174,7 @@ build instructions.
- [Cursor](#cursor)
- [`GetCursorInfo()`](#getcursorinfo)
+ - [`CursorHasMacro()`](#cursorhasmacro)
- [EquipmentSet](#equipmentset)
- [Overview & file format](#overview--file-format)
@@ -623,6 +625,7 @@ build instructions.
- [`GetRunningMacro()`](#getrunningmacro)
- [`GetRunningMacroButton()`](#getrunningmacrobutton)
- [Macro names in `GetMacroInfo` / `EditMacro` / `PickupMacro` / `DeleteMacro`](#macro-names-in-getmacroinfo--editmacro--pickupmacro--deletemacro)
+ - [`GetMacroBody(macro)`](#getmacrobodymacro)
- [`GetMacroSpell(macroSlot)`](#getmacrospellmacroslot)
- [`GetMacroItem(macroSlot)`](#getmacroitemmacroslot)
- [`SetMacroSpell(macro, spell [, target])` / `SetMacroItem(macro, item [, target])`](#setmacrospellmacro-spell--target--setmacroitemmacro-item--target)
@@ -2502,6 +2505,15 @@ unless you specifically want the console's behaviour.
Works whether or not the console is open, and whether or not `-console` was
used.
+### `ConsoleAddMessage(message)`
+
+Writes a line of text to the console. An empty string writes nothing. An
+argument that is not a string raises an error.
+
+```lua
+ConsoleAddMessage("Hello from Lua")
+```
+
### `ConsoleEcho(message [, colorType])`
Writes one line to the console. `colorType` is 0 to 8 and picks the colour, as
@@ -4184,6 +4196,10 @@ Consumers can use `CursorHasItem`, `CursorHasSpell` and `CursorHasMoney`.
Changes to what the cursor holds are reported by the
[`CURSOR_CHANGED` event](#cursor_changed-event).
+### `CursorHasMacro()`
+
+Returns `true` if the cursor holds a macro, and `false` if it does not.
+
## EquipmentSet
`C_EquipmentSet.*` — named sets of gear you can save and equip again
@@ -14869,6 +14885,16 @@ PickupMacro("MyMacro")
Numbers and numeric strings (`"3"`) are still indexes.
+### `GetMacroBody(macro)`
+
+Returns the text of a macro. `macro` is the macro's index or its name.
+If no macro is there, the function returns nothing.
+
+```lua
+/dump GetMacroBody(1)
+/dump GetMacroBody("MyMacro")
+```
+
### `GetMacroSpell(macroSlot)`
Returns `(name, rank, spellID)` for the spell that a macro shows. When the
diff --git a/src/console/Shell.cpp b/src/console/Shell.cpp
index fdb35584..b2624c25 100644
--- a/src/console/Shell.cpp
+++ b/src/console/Shell.cpp
@@ -78,6 +78,27 @@ int __fastcall Script_ConsoleEcho(void *L) {
return 0;
}
+// `ConsoleAddMessage(message)` — 4.3.4's Script_ConsoleAddMessage
+// (0x008C38B0): a usage error for a non-string, else ConsolePrintf("%s")
+// unless the text is empty.
+int __fastcall Script_ConsoleAddMessage(void *L) {
+ if (!Game::Lua::IsString(L, 1)) {
+ Game::Lua::Error(L, "Usage: ConsoleAddMessage(string)");
+ return 0;
+ }
+ const char *text = Game::Lua::ToString(L, 1);
+ if (text != nullptr && *text != '\0')
+ Game::Console::Printf("%s", text);
+ return 0;
+}
+
+const Game::Doc::Field kConsoleAddMessageArgs[] = {
+ Game::Doc::Req("message", "string", "The text to write."),
+};
+const Game::Doc::Function kConsoleAddMessage{
+ "Writes a line of text to the console.",
+ kConsoleAddMessageArgs, {}, "ConsoleGlobals"};
+
// `ConsoleIsActive()` — whether the console is open right now.
//
// False when the client was started without `-console`, since the toggle key
@@ -208,6 +229,8 @@ int __fastcall Script_CalculateStringEditDistance(void *L) {
void Register() {
Game::Lua::RegisterGlobalFunction("ConsoleExec", &Script_ConsoleExec);
Game::Lua::RegisterGlobalFunction("ConsoleEcho", &Script_ConsoleEcho);
+ Game::Lua::RegisterGlobalFunction("ConsoleAddMessage", &Script_ConsoleAddMessage,
+ &kConsoleAddMessage);
Game::Lua::RegisterGlobalFunction("ConsoleIsActive", &Script_ConsoleIsActive);
Game::Lua::RegisterGlobalFunction("ConsoleGetColorFromType",
&Script_ConsoleGetColorFromType);
diff --git a/src/cursor/Info.cpp b/src/cursor/Info.cpp
index 11f78f5b..c101dbcf 100644
--- a/src/cursor/Info.cpp
+++ b/src/cursor/Info.cpp
@@ -282,8 +282,24 @@ int __fastcall Script_GetCursorInfo(void *L) {
}
}
+// `CursorHasMacro()` — 4.3.4's Script_CursorHasMacro (0x008C6F70) tests its
+// macro cursor type, 7; 1.12's macro type is 8.
+int __fastcall Script_CursorHasMacro(void *L) {
+ Game::Lua::PushBool(L, ReadVar(Offsets::VAR_CURSOR_TYPE) == TYPE_MACRO);
+ return 1;
+}
+
+const Game::Doc::Field kCursorHasMacroRets[] = {
+ Game::Doc::Req("hasMacro", "boolean", "True if the cursor holds a macro."),
+};
+const Game::Doc::Function kCursorHasMacro{
+ "Returns true if the cursor holds a macro.",
+ {}, kCursorHasMacroRets, "CursorGlobals"};
+
void RegisterLuaFunctions() {
Game::Lua::RegisterGlobalFunction("GetCursorInfo", &Script_GetCursorInfo);
+ Game::Lua::RegisterGlobalFunction("CursorHasMacro", &Script_CursorHasMacro,
+ &kCursorHasMacro);
}
const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
diff --git a/src/macro/Arg.cpp b/src/macro/Arg.cpp
new file mode 100644
index 00000000..0ea36162
--- /dev/null
+++ b/src/macro/Arg.cpp
@@ -0,0 +1,38 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under
+// the terms of the GNU General Public License as published by the Free Software
+// Foundation, either version 3 of the License, or (at your option) any later
+// version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+// A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+#include "macro/Arg.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include
+
+namespace Macro::Arg {
+
+int Slot(void *L) {
+ using NameToSlot_t = uint32_t(__fastcall *)(const char *name);
+ using SlotToEntry_t = const uint8_t *(__fastcall *)(uint32_t slot0);
+ uint32_t slot0 = 0xFFFFFFFFu;
+ if (Game::Lua::IsNumber(L, 1))
+ slot0 = static_cast(static_cast(Game::Lua::ToNumber(L, 1)) - 1);
+ else if (Game::Lua::IsString(L, 1))
+ slot0 = reinterpret_cast(Offsets::FUN_MACRO_NAME_TO_SLOT)(
+ Game::Lua::ToString(L, 1));
+ if (reinterpret_cast(Offsets::FUN_MACRO_SLOT_TO_ENTRY)(slot0) == nullptr)
+ return 0;
+ return static_cast(slot0) + 1;
+}
+
+} // namespace Macro::Arg
diff --git a/src/macro/Arg.h b/src/macro/Arg.h
new file mode 100644
index 00000000..cef6d7eb
--- /dev/null
+++ b/src/macro/Arg.h
@@ -0,0 +1,24 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under
+// the terms of the GNU General Public License as published by the Free Software
+// Foundation, either version 3 of the License, or (at your option) any later
+// version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+// A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+#pragma once
+
+namespace Macro::Arg {
+
+// The macro slot (1-based) that argument 1 names, as 4.3.4's GetMacroFromLua
+// reads it: a number, or a string that converts to one, is an index; any other
+// string is a name. 0 when no macro is there.
+int Slot(void *L);
+
+} // namespace Macro::Arg
diff --git a/src/macro/Body.cpp b/src/macro/Body.cpp
new file mode 100644
index 00000000..580017c4
--- /dev/null
+++ b/src/macro/Body.cpp
@@ -0,0 +1,65 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under
+// the terms of the GNU General Public License as published by the Free Software
+// Foundation, either version 3 of the License, or (at your option) any later
+// version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+// A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+// `GetMacroBody(macro)` — the body text of a macro, by index or name.
+//
+// 4.3.4's Script_GetMacroBody (0x009C56E0) resolves argument 1 through
+// GetMacroFromLua (Macro::Arg::Slot) and pushes the entry's body; no macro
+// there returns nothing, with no usage error. 1.12 keeps the body inline at
+// OFF_MACRO_BODY, the same field its GetMacroInfo (0x004F1760) pushes.
+
+#include "macro/Arg.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include
+
+namespace Macro::Body {
+
+namespace {
+
+using SlotToEntry_t = const uint8_t *(__fastcall *)(uint32_t slot0);
+
+int __fastcall Script_GetMacroBody(void *L) {
+ const int slot = Macro::Arg::Slot(L);
+ if (slot == 0)
+ return 0;
+ const uint8_t *entry = reinterpret_cast(Offsets::FUN_MACRO_SLOT_TO_ENTRY)(
+ static_cast(slot - 1));
+ Game::Lua::PushString(L, reinterpret_cast(entry + Offsets::OFF_MACRO_BODY));
+ return 1;
+}
+
+// --- Documentation ----------------------------------------------------------
+
+const Game::Doc::Field kArgs[] = {
+ Game::Doc::Req("macro", "string", "The macro's index or name."),
+};
+const Game::Doc::Field kRets[] = {
+ Game::Doc::Req("body", "string", "The macro's text."),
+};
+const Game::Doc::Function kGetMacroBody{
+ "Returns the text of a macro.",
+ kArgs, kRets, "MacroGlobals"};
+
+} // namespace
+
+static void RegisterLuaFunctions() {
+ Game::Lua::RegisterGlobalFunction("GetMacroBody", &Script_GetMacroBody, &kGetMacroBody);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Macro::Body
diff --git a/src/macro/Display.cpp b/src/macro/Display.cpp
index edf1be8f..c9b83c87 100644
--- a/src/macro/Display.cpp
+++ b/src/macro/Display.cpp
@@ -35,6 +35,7 @@
#include "Game.h"
#include "Offsets.h"
+#include "macro/Arg.h"
#include "macro/ShowTooltip.h"
#include
@@ -66,29 +67,12 @@ int __fastcall Script_C_Macro_SetMacroDisplay(void *L) {
return 1;
}
-// The macro slot (1-based) that argument 1 names, as 4.3.4's GetMacroFromLua
-// reads it: a number, or a string that converts to one, is an index; any other
-// string is a name. 0 when no macro is there.
-int MacroSlotArg(void *L) {
- using NameToSlot_t = uint32_t(__fastcall *)(const char *name);
- using SlotToEntry_t = const uint8_t *(__fastcall *)(uint32_t slot0);
- uint32_t slot0 = 0xFFFFFFFFu;
- if (Game::Lua::IsNumber(L, 1))
- slot0 = static_cast(static_cast(Game::Lua::ToNumber(L, 1)) - 1);
- else if (Game::Lua::IsString(L, 1))
- slot0 = reinterpret_cast(Offsets::FUN_MACRO_NAME_TO_SLOT)(
- Game::Lua::ToString(L, 1));
- if (reinterpret_cast(Offsets::FUN_MACRO_SLOT_TO_ENTRY)(slot0) == nullptr)
- return 0;
- return static_cast(slot0) + 1;
-}
-
int SetMacroValue(void *L, Macro::ShowTooltip::Accept accept, const char *usage) {
if (!Game::Lua::IsString(L, 2)) {
Game::Lua::Error(L, usage);
return 0;
}
- const int macroSlot = MacroSlotArg(L);
+ const int macroSlot = Macro::Arg::Slot(L);
if (macroSlot == 0)
return 0;
Macro::ShowTooltip::PublishOptions options;