diff --git a/README.md b/README.md
index 36c41d71..99fa599e 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th
| Namespace | Calls |
|-----------|-------|
-| [Action](docs/API.md#action) | `GetActionInfo`, `IsItemAction`, `HasBonusActionBar` |
+| [Action](docs/API.md#action) | `GetActionInfo`, `IsItemAction`, `HasBonusActionBar`, `C_ActionBar.EnableActionRangeCheck` |
| [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnInterfaceVersion`, `C_AddOns.GetAddOnLocalTable`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnOptionalDependencies`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable`, `C_AddOns.IsAddOnLoaded`, `C_AddOns.LoadAddOn` |
| [APIDocumentation](docs/API.md#apidocumentation) | `/classicapi` in-game browser, `C_APIDocumentation.GetSystem`, `C_APIDocumentation.GetSystems` |
| [Animation](docs/API.md#animation) | `region:CreateAnimationGroup`, `region:GetAnimationGroups`, `region:StopAnimating`, `SetMaxAnimFramerate`, `GetMaxAnimFramerate`, `AnimationGroup` and `Animation` / `Alpha` / `Translation` / `Scale` / `Rotation` / `Path` / `ControlPoint` methods |
@@ -280,6 +280,8 @@ when launching with `-console`), not as Lua functions. See the
| Event | Payload |
|-------|---------|
+| `ACTION_RANGE_CHECK_UPDATE` | `slot, isInRange, checksRange` (slots with `C_ActionBar.EnableActionRangeCheck` on) |
+| `ACTION_USABLE_CHANGED` | `changes` (a `{ slot, usable, noMana }` table for each slot that changed) |
| `BAG_NEW_ITEMS_UPDATED` | *(none)* |
| `BAG_UPDATE_DELAYED` | *(none)* |
| `CHAT_MSG_*` | adds `lineID, guid` as `arg11, arg12` after the existing ten ([details](docs/API.md#chat_msg_-arguments-lineid-arg11-and-guid-arg12)) |
diff --git a/docs/API.md b/docs/API.md
index f363db23..2ed05573 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -14,6 +14,9 @@ build instructions.
- [`IsItemAction(slot)`](#isitemactionslot)
- [`HasBonusActionBar()`](#hasbonusactionbar)
- [`C_ActionBar.ShouldShowKeyring()`](#c_actionbarshouldshowkeyring)
+ - [`C_ActionBar.EnableActionRangeCheck(slot, enable)`](#c_actionbarenableactionrangecheckslot-enable)
+ - [`ACTION_RANGE_CHECK_UPDATE` event](#action_range_check_update-event)
+ - [`ACTION_USABLE_CHANGED` event](#action_usable_changed-event)
- [AddOns](#addons)
- [`C_AddOns.GetAddOnName(indexOrName)`](#c_addonsgetaddonnameindexorname)
@@ -1310,6 +1313,96 @@ if C_ActionBar.ShouldShowKeyring() then
end
```
+### `C_ActionBar.EnableActionRangeCheck(slot, enable)`
+
+Starts or stops the range check of a 1-based action-bar slot for
+[`ACTION_RANGE_CHECK_UPDATE`](#action_range_check_update-event). A slot
+that is not in the range 1 to 120 is ignored.
+
+The client counts the calls for each slot. Each call with `enable` set to
+`true` adds one. Each call with `enable` set to `false` removes one. The
+client checks the slot while its count is more than zero. Thus, if two
+buttons show the same slot, each button can enable and disable the slot
+for itself.
+
+After each call with `enable` set to `true`, the next check of the slot
+fires the event, also if the state did not change. This gives a new
+button the current state of its slot. You do not have to call
+`IsActionInRange` when you show a button.
+
+A `/reload` sets the count of all slots to zero.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("ACTION_RANGE_CHECK_UPDATE")
+f:SetScript("OnEvent", function()
+ print("Slot", arg1, arg3 and (arg2 and "in range" or "out of range") or "no range check")
+end)
+C_ActionBar.EnableActionRangeCheck(1, true)
+```
+
+### `ACTION_RANGE_CHECK_UPDATE` event
+
+Fires when an action-bar slot that has
+[`EnableActionRangeCheck`](#c_actionbarenableactionrangecheckslot-enable)
+on goes into or out of range of its target.
+
+```
+ACTION_RANGE_CHECK_UPDATE: slot, isInRange, checksRange
+```
+
+- **`slot`** (number) — the 1-based action-bar slot.
+- **`isInRange`** (boolean) — `true` when the target is in range. Do not
+ use this value when `checksRange` is `false`.
+- **`checksRange`** (boolean) — `false` when the client did not do a range
+ check. For example, the slot is empty, its action has no range, or there
+ is no target.
+
+The values are the values that `IsActionInRange(slot)` gives: `1` is
+`isInRange = true`, `0` is `isInRange = false`, and `nil` is
+`checksRange = false`. A macro that is aimed at a unit (for example
+`[@focus]`) uses that unit as its target.
+
+The client checks the enabled slots on each frame, but only while a frame
+is registered for the event. The event fires only when the state of a
+slot changes, and after each enable call. When the action in a slot
+changes, the client checks the new action. The event fires if its state
+is different.
+
+### `ACTION_USABLE_CHANGED` event
+
+Fires when the usable state of one or more action-bar slots changes. The
+payload gives only the slots that changed. Thus, a handler does not have
+to read `IsUsableAction` for each button.
+
+```
+ACTION_USABLE_CHANGED: changes
+```
+
+- **`changes`** (table) — a list with one table for each slot that
+ changed:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `slot` | number | The 1-based action-bar slot. |
+| `usable` | boolean | The new first return value of `IsUsableAction(slot)`, as a boolean. |
+| `noMana` | boolean | The new second return value of `IsUsableAction(slot)`, as a boolean. |
+
+The event fires immediately after `ACTIONBAR_UPDATE_USABLE`, which does
+not change. When the action in a slot changes, the client fires
+`ACTIONBAR_SLOT_CHANGED` for that slot, not this event. Thus, read
+`IsUsableAction` for a slot on `ACTIONBAR_SLOT_CHANGED`.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("ACTION_USABLE_CHANGED")
+f:SetScript("OnEvent", function()
+ for _, change in ipairs(arg1) do
+ print("Slot", change.slot, change.usable, change.noMana)
+ end
+end)
+```
+
## AddOns
`C_AddOns.*` getters that splat the
diff --git a/src/Offsets.h b/src/Offsets.h
index 88895fc6..e1c416c7 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -7024,6 +7024,19 @@ enum Offsets {
// ACTIONBAR_UPDATE_USABLE (0xD7, via FUN_FIRE_EVENT_NO_ARGS) when one did.
// Disassembled; it is 4.3.4's `CGActionBar::UpdateUsable` line for line.
FUN_ACTION_UPDATE_USABLE = 0x004E5C00,
+ // The uint[120] caches FUN_ACTION_UPDATE_USABLE compares and stores:
+ // FUN_ACTION_SLOT_USABLE's return at `0x004E5C1A` / `0x004E5C2F`, its
+ // `*outNoMana` at `0x004E5C26` / `0x004E5C36`. `IsUsableAction` reads them.
+ VAR_ACTION_USABLE = 0x00BC6B60,
+ VAR_ACTION_NO_MANA = 0x00BC67A0,
+ // FUN_ACTION_UPDATE_USABLE's per-slot `call FUN_ACTION_SLOT_USABLE` (ecx
+ // slot0, edx &noMana), compared against the caches above before they are
+ // stored. E8 call, disassembled.
+ CALL_UPDATE_USABLE_SLOT_USABLE = 0x004E5C15,
+ // FUN_ACTION_UPDATE_USABLE's `mov ecx, 0xD7; call FUN_FIRE_EVENT_NO_ARGS`
+ // (ACTIONBAR_UPDATE_USABLE), reached only when a slot changed. E8 call,
+ // disassembled.
+ CALL_UPDATE_USABLE_FIRE = 0x004E5C53,
// Drop the cursor onto a slot — `__fastcall(uint slot0)`. Sole entry
// for `PlaceAction`, and the tail of both FUN_ACTION_PICKUP and
// nampower's detoured `CGActionBar_UseAction` (`0x004E5EE0`) when the
diff --git a/src/action/Range.cpp b/src/action/Range.cpp
index c0fbba84..a6c4d5ff 100644
--- a/src/action/Range.cpp
+++ b/src/action/Range.cpp
@@ -28,6 +28,8 @@
// The function's one caller, Script_IsActionInRange, is redirected rather than
// the function hooked.
+#include "action/Range.h"
+
#include "Common.h"
#include "Game.h"
#include "Offsets.h"
@@ -107,4 +109,6 @@ const Game::ModuleAutoRegister _autoreg{&Register};
} // namespace
+int Answer(int slot0, int *inRange) { return SlotRange_h(slot0, inRange); }
+
} // namespace Action::Range
diff --git a/src/action/Range.h b/src/action/Range.h
new file mode 100644
index 00000000..109c2f63
--- /dev/null
+++ b/src/action/Range.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 Action::Range {
+
+// IsActionInRange's answer for a slot (0-based, 0..119): 0 when it has none
+// (IsActionInRange's nil), else 1 with `*inRange` 0 or 1. A macro aimed at a
+// unit is checked against that unit.
+int Answer(int slot0, int *inRange);
+
+} // namespace Action::Range
diff --git a/src/action/RangeCheck.cpp b/src/action/RangeCheck.cpp
new file mode 100644
index 00000000..22254bfc
--- /dev/null
+++ b/src/action/RangeCheck.cpp
@@ -0,0 +1,144 @@
+// 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 .
+
+// `C_ActionBar.EnableActionRangeCheck(slot, enable)` and
+// `ACTION_RANGE_CHECK_UPDATE(slot, isInRange, checksRange)`.
+//
+// Nothing in the client reacts to a distance (see Unit::InRangeEvent), so the
+// enabled slots are checked every world tick, while a frame is registered for
+// the event, and a slot fires when its answer changes. The answer is
+// IsActionInRange's (Action::Range::Answer), macro unit included, so a slot
+// whose action changes fires when the new action's answer differs.
+//
+// Enabling is counted per slot, as retail's ActionBarButtonRangeCheckFrame
+// expects: it enables once for each button on a slot and disables once as
+// each button leaves. Retail's buttons never call IsActionInRange; they take
+// their first state from this event. So each enable makes the slot's next
+// check fire, changed or not. A new Lua state (`/reload`) starts with no slot
+// enabled.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "action/Range.h"
+#include "event/Custom.h"
+#include "tick/WorldTick.h"
+
+#include
+
+namespace Action::RangeCheck {
+
+namespace {
+
+enum class State : uint8_t { NoCheck, OutOfRange, InRange };
+
+struct Slot {
+ int refs = 0;
+ bool pending = false; // fire on the next check, changed or not
+ State last = State::NoCheck;
+};
+
+Slot g_slots[Offsets::ACTION_TABLE_MAX_SLOTS];
+
+const Game::Doc::Field kPayload[] = {
+ Game::Doc::Req("slot", "luaIndex"),
+ Game::Doc::Req("isInRange", "bool",
+ "Whether the action's target is in range. Should not be used if checksRange "
+ "is false."),
+ Game::Doc::Req("checksRange", "bool",
+ "False when no range check was made, for example when there is no target."),
+};
+const Game::Doc::Event kDoc{
+ "ActionBar",
+ "Fires when an action that has EnableActionRangeCheck on goes in or out of range of its "
+ "target.",
+ kPayload};
+const Event::Custom::AutoReserve kEvent{"ACTION_RANGE_CHECK_UPDATE", &kDoc};
+
+State Evaluate(int slot0) {
+ int inRange = 0;
+ if (Action::Range::Answer(slot0, &inRange) == 0)
+ return State::NoCheck;
+ return inRange != 0 ? State::InRange : State::OutOfRange;
+}
+
+void OnWorldTick() {
+ const int event = kEvent.Slot();
+ if (!Event::Custom::HasListeners(event))
+ return;
+ void *L = Game::Lua::State();
+ if (L == nullptr)
+ return;
+ const int top = Game::Lua::GetTop(L);
+ for (int slot0 = 0; slot0 < Offsets::ACTION_TABLE_MAX_SLOTS; ++slot0) {
+ Slot &slot = g_slots[slot0];
+ if (slot.refs == 0)
+ continue;
+ const State state = Evaluate(slot0);
+ if (!slot.pending && state == slot.last)
+ continue;
+ slot.pending = false;
+ slot.last = state;
+ Game::Lua::PushNumber(L, static_cast(slot0 + 1));
+ Game::Lua::PushBool(L, state == State::InRange);
+ Game::Lua::PushBool(L, state != State::NoCheck);
+ Event::Custom::FireValues(event, L, top + 1, 3);
+ Game::Lua::SetTop(L, top);
+ }
+}
+
+const Tick::WorldTick::AutoSubscribe _tick{&OnWorldTick};
+
+// --- C_ActionBar.EnableActionRangeCheck(slot, enable) -----------------------
+
+int __fastcall Script_EnableActionRangeCheck(void *L) {
+ if (!Game::Lua::IsNumber(L, 1)) {
+ Game::Lua::Error(L, "Usage: C_ActionBar.EnableActionRangeCheck(slot, enable)");
+ return 0;
+ }
+ const int slot0 = static_cast(Game::Lua::ToNumber(L, 1)) - 1;
+ if (slot0 < 0 || slot0 >= Offsets::ACTION_TABLE_MAX_SLOTS)
+ return 0;
+ Slot &slot = g_slots[slot0];
+ if (Game::Lua::ToBoolean(L, 2) != 0) {
+ ++slot.refs;
+ slot.pending = true;
+ } else if (slot.refs > 0) {
+ --slot.refs;
+ }
+ return 0;
+}
+
+const Game::Doc::Field kEnableArgs[] = {
+ Game::Doc::Req("slot", "luaIndex"),
+ Game::Doc::Req("enable", "bool",
+ "True if changes in range for the action should dispatch "
+ "ACTION_RANGE_CHECK_UPDATE. False if the action no longer needs the event."),
+};
+const Game::Doc::Function kEnableDoc{
+ "Used with ACTION_RANGE_CHECK_UPDATE to be informed when an action goes in or out of range "
+ "of its target.",
+ kEnableArgs};
+
+void RegisterLuaFunctions() {
+ for (Slot &slot : g_slots)
+ slot = Slot{};
+ Game::Lua::RegisterTableFunction("C_ActionBar", "EnableActionRangeCheck",
+ &Script_EnableActionRangeCheck, &kEnableDoc);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Action::RangeCheck
diff --git a/src/action/UsableChanged.cpp b/src/action/UsableChanged.cpp
new file mode 100644
index 00000000..2000b85a
--- /dev/null
+++ b/src/action/UsableChanged.cpp
@@ -0,0 +1,125 @@
+// 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 .
+
+// `ACTION_USABLE_CHANGED(changes)` — the slots whose usable / noMana pair
+// changed, as `{ slot, usable, noMana }` entries.
+//
+// The engine's bulk refresh FUN_ACTION_UPDATE_USABLE already finds them: it
+// computes each slot with FUN_ACTION_SLOT_USABLE, compares the pair against
+// the caches IsUsableAction reads, stores a changed pair, and signals the
+// argument-less ACTIONBAR_UPDATE_USABLE once when any changed. Two of its
+// calls are redirected. The per-slot call records the slots whose pair differs
+// from the caches, the same compare the engine makes next. The signal sends
+// ACTIONBAR_UPDATE_USABLE unchanged, then this event with the recorded slots.
+//
+// The per-slot refresh in FUN_ACTION_SLOT_CHANGED_NOTIFY stores its pair
+// without this event; it signals ACTIONBAR_SLOT_CHANGED for the slot instead.
+
+#include "Common.h"
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+
+#include
+#include
+
+namespace Action::UsableChanged {
+
+namespace {
+
+using SlotUsable_t = uint32_t(__fastcall *)(uint32_t slot0, uint32_t *outNoMana);
+using FireEvent_t = void(__fastcall *)(int eventID);
+
+struct Change {
+ uint32_t slot0;
+ bool usable;
+ bool noMana;
+};
+
+// This refresh's changes. The loop runs slots 0..119 in order, so slot 0
+// starts a new list.
+Change g_changes[Offsets::ACTION_TABLE_MAX_SLOTS];
+int g_count = 0;
+
+const Game::Doc::Field kStateFields[] = {
+ Game::Doc::Req("slot", "luaIndex"),
+ Game::Doc::Req("usable", "bool"),
+ Game::Doc::Req("noMana", "bool"),
+};
+const Game::Doc::Structure kState{"ActionUsableState", "ActionBar", kStateFields};
+
+const Game::Doc::Field kPayload[] = {
+ Game::Doc::Req("changes", "table", "An ActionUsableState for each slot that changed."),
+};
+const Game::Doc::Event kDoc{
+ "ActionBar", "Fires when the usable or noMana state of one or more action slots changes.",
+ kPayload};
+const Event::Custom::AutoReserve kEvent{"ACTION_USABLE_CHANGED", &kDoc};
+
+uint32_t __fastcall SlotUsable_h(uint32_t slot0, uint32_t *outNoMana) {
+ const uint32_t usable =
+ reinterpret_cast(Offsets::FUN_ACTION_SLOT_USABLE)(slot0, outNoMana);
+ if (slot0 == 0)
+ g_count = 0;
+ const auto *usableCache =
+ reinterpret_cast(static_cast(Offsets::VAR_ACTION_USABLE));
+ const auto *noManaCache =
+ reinterpret_cast(static_cast(Offsets::VAR_ACTION_NO_MANA));
+ if (slot0 < static_cast(Offsets::ACTION_TABLE_MAX_SLOTS) &&
+ g_count < Offsets::ACTION_TABLE_MAX_SLOTS &&
+ (usable != usableCache[slot0] || *outNoMana != noManaCache[slot0]))
+ g_changes[g_count++] = {slot0, usable != 0, *outNoMana != 0};
+ return usable;
+}
+
+void __fastcall FireUsable_h(int eventID) {
+ // Copied first: the handlers below can run another refresh.
+ Change changes[Offsets::ACTION_TABLE_MAX_SLOTS];
+ const int count = g_count;
+ std::memcpy(changes, g_changes, sizeof(Change) * count);
+ g_count = 0;
+
+ reinterpret_cast(Offsets::FUN_FIRE_EVENT_NO_ARGS)(eventID);
+
+ const int event = kEvent.Slot();
+ void *L = Game::Lua::State();
+ if (count == 0 || !Event::Custom::HasListeners(event) || L == nullptr)
+ return;
+ const int top = Game::Lua::GetTop(L);
+ Game::Lua::NewTable(L);
+ for (int i = 0; i < count; ++i) {
+ Game::Lua::PushNumber(L, static_cast(i + 1));
+ Game::Lua::NewTable(L);
+ Game::Lua::SetFieldNumber(L, "slot", static_cast(changes[i].slot0 + 1));
+ Game::Lua::SetFieldBool(L, "usable", changes[i].usable);
+ Game::Lua::SetFieldBool(L, "noMana", changes[i].noMana);
+ Game::Lua::RawSet(L, -3);
+ }
+ Game::Lua::SetN(L, -1, count);
+ Event::Custom::FireValues(event, L, top + 1, 1);
+ Game::Lua::SetTop(L, top);
+}
+
+void Register() {
+ Common::RedirectCall(Offsets::CALL_UPDATE_USABLE_SLOT_USABLE, Offsets::FUN_ACTION_SLOT_USABLE,
+ reinterpret_cast(&SlotUsable_h));
+ Common::RedirectCall(Offsets::CALL_UPDATE_USABLE_FIRE, Offsets::FUN_FIRE_EVENT_NO_ARGS,
+ reinterpret_cast(&FireUsable_h));
+}
+
+const Game::ModuleAutoRegister _autoreg{&Register};
+
+} // namespace
+
+} // namespace Action::UsableChanged