spell: backport UNIT_SPELLCAST_* events for the local player

Adds the TBC+ cast/channel events (START, STOP, DELAYED, SUCCEEDED,
INTERRUPTED, FAILED, SENT, CHANNEL_START, CHANNEL_UPDATE, CHANNEL_STOP)
for the player, so cast-bar / rotation addons written against the modern
signature work on 1.12. Each carries (unit, castGUID, spellID, spellName,
rank) -- SENT inserts `target` at arg2 -- with a synthesized modern-shape
castGUID (Cast-3-0-0-0-<spellID>-<castUID>) shared across all of a cast's
events so START pairs with STOP. arg1 is always "player" (player-only phase).

The events are derived, not independently tracked: Spell::Cast already
hooks every cast/channel path for UnitCastingInfo/UnitChannelInfo, so
Spell::CastEvents reuses that state.
  - START/STOP/DELAYED/CHANNEL_START/STOP: polled from Cast's OnWorldTick
    against the previous snapshot.
  - SUCCEEDED: fired from the SMSG_SPELL_GO hook (covers instants too).
    Deferred for channels so it lands after CHANNEL_START (modern order).
  - INTERRUPTED/FAILED: split by result code in a Spell_C_SpellFailed
    co-hook -- a started cast that aborts (kick/move/LoS) fires INTERRUPTED
    (repeated per retry, reusing the cast guid); a pre-cast rejection fires
    FAILED.
  - SENT: minted from the CMSG_CAST_SPELL send, threading its castGUID
    forward so all of a cast's events share one guid.
  - CHANNEL_UPDATE: from a new MSG_CHANNEL_UPDATE co-hook, which also
    re-anchors g_channel.endMs to the server's remaining time so channel
    pushback (which shortens vanilla channels) shows in UnitChannelInfo.

Every fire is gated on Event::Custom::HasListeners (new), so the system
costs one pointer-compare per transition when no addon registers.

Supporting changes:
  - Net::SendObserver: shared co-hook on the NetClient send funnel with an
    AutoSubscribe list, so CastEvents (SENT) and ComboDuration (combo-point
    capture) both watch outgoing packets without owning the hook. Extracted
    from ComboDuration's private hook.
  - Cast.cpp: player channel now self-expires at its computed endMs in the
    poll (was cleared only by the ~1s-lagged +0x228 field, so CHANNEL_STOP
    trailed the real end by ~1s); wrap-safe delta compare so a long-uptime
    ms tick past 2^31 can't misfire it.

Player-only; remote-unit fan-out, FAILED_QUIET, and empowered casts are
not implemented.

Author: brues-code

README.md

@@ -155,6 +155,16 @@ when launching with `-console`), not as Lua functions. See the
 | `QUEST_DATA_LOAD_RESULT` | `questID, success` |
 | `QUEST_REMOVED` | `questID` |
 | `QUEST_TURNED_IN` | `questID, xpReward, moneyReward` |
+| `UNIT_SPELLCAST_SENT` | `"player", target, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_START` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_STOP` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_DELAYED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_SUCCEEDED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_INTERRUPTED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_FAILED` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_START` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_UPDATE` | `"player", castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_CHANNEL_STOP` | `"player", castGUID, spellID, spellName, rank` |
 | `UPDATE_INVENTORY_DURABILITY` | *(none)* |
 | `UPDATE_SHAPESHIFT_FORM` | *(none)* |
 | `VOICE_CHAT_TTS_PLAYBACK_STARTED` | `numConsumers, utteranceID, durationMS, destination` |

docs/API.md

@@ -441,6 +441,7 @@ build instructions.
   - [`C_Spell.CancelSpellByID(spellID)` / `CancelSpellByName(name)`](#c_spellcancelspellbyidspellid--cancelspellbynamename)
   - [`C_Spell.UnitCastingInfo(unit)` / `C_Spell.CastingInfo()`](#c_spellunitcastinginfounit--c_spellcastinginfo)
   - [`C_Spell.UnitChannelInfo(unit)` / `C_Spell.ChannelInfo()`](#c_spellunitchannelinfounit--c_spellchannelinfo)
+  - [`UNIT_SPELLCAST_*` events (player)](#unit_spellcast_-events-player)
   - [`C_Spell.GetSpellLevelInfo(spellID)`](#c_spellgetspelllevelinfospellid)
   - [`GetSpellRequiredTargetLevel(spellID)`](#getspellrequiredtargetlevelspellid)
 
@@ -10829,6 +10830,84 @@ otherwise it falls back to `name`/`displayName`/`textureID`/`spellID` with
 **`nil` times**. The player path is unchanged (full timing). Same
 placeholder fields as `C_Spell.UnitCastingInfo`.
 
+### `UNIT_SPELLCAST_*` events (player)
+
+Backport of the TBC+ cast/channel events to 1.12 for the **local player**.
+Ported cast-bar / rotation addons (anything written against the modern
+signature) register these instead of vanilla's arg-less `SPELLCAST_*`
+events and read `unit, castGUID, spellID` directly. Ten events are
+provided:
+
+| Event | Fires when | Args |
+|-------|-----------|------|
+| `UNIT_SPELLCAST_SENT` | `CMSG_CAST_SPELL` leaves the client (earliest point) | `unit, target, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_START` | a cast-time spell begins | `unit, castGUID, spellID, spellName, rank` |
+| `UNIT_SPELLCAST_STOP` | a cast-time spell ends (any reason) | same |
+| `UNIT_SPELLCAST_DELAYED` | pushback extends the cast | same |
+| `UNIT_SPELLCAST_SUCCEEDED` | the spell goes off (`SMSG_SPELL_GO`) — incl. instants | same |
+| `UNIT_SPELLCAST_INTERRUPTED` | a started cast is interrupted (kick, movement, LoS) | same |
+| `UNIT_SPELLCAST_FAILED` | a cast is rejected before it starts (range, mana, cooldown) | same |
+| `UNIT_SPELLCAST_CHANNEL_START` | a channel begins | same |
+| `UNIT_SPELLCAST_CHANNEL_UPDATE` | pushback shortens a channel | same |
+| `UNIT_SPELLCAST_CHANNEL_STOP` | a channel ends | same |
+
+`unit` (arg1) is always `"player"` — this is the player-only phase; other
+units aren't fanned out yet. `spellName` / `rank` are ClassicAPI tail
+extensions (modern stops at `spellID`); addons reading only the first three
+positional args are unaffected.
+
+**castGUID.** A synthesized string in the modern shape
+`Cast-<type>-<serverID>-<instanceID>-<zoneUID>-<spellID>-<castUID>`. Vanilla
+can't know server / instance / zone, so those three fields are `0`; the
+load-bearing parts are the `spellID` (field 6, which addons `strsplit("-")`
+out) and a unique-per-cast `castUID` (field 7). **Every event of one cast
+carries the same castGUID**, so `SENT` → `START`/`CHANNEL_START` →
+`SUCCEEDED` → `STOP`/`CHANNEL_STOP` all pair up — a chained same-spell
+recast gets its own castUID.
+
+**Ordering** matches modern:
+
+- Cast-time spell: `SENT → START → SUCCEEDED → STOP`.
+- Channel: `SENT → CHANNEL_START → SUCCEEDED → CHANNEL_STOP` (CHANNEL_START
+  before SUCCEEDED, as on retail).
+- Instant: `SENT → SUCCEEDED`.
+
+**INTERRUPTED vs FAILED** follow modern's split: a spell that never started
+(out of range, not enough mana, on cooldown, LoS to a target) fires
+`FAILED`; a spell that was *already casting* and gets stopped (an enemy
+kick, moving to cancel, breaking LoS mid-cast) fires `INTERRUPTED`. Holding
+the cast key while running fires `INTERRUPTED` repeatedly (once per retry),
+each reusing the interrupted cast's castGUID — matching retail.
+
+**Channel pushback.** Taking damage while channeling shortens the channel in
+vanilla; `CHANNEL_UPDATE` fires on each hit and
+[`C_Spell.UnitChannelInfo`](#c_spellunitchannelinfounit--c_spellchannelinfo)'s
+`endTimeMs` re-anchors to the server's new remaining time, so cast bars
+shrink correctly. (The event carries no time — like retail it's a "re-read
+now" trigger; timing is read back from `UnitChannelInfo`.)
+
+Every fire is gated on whether any frame is registered for that event, so
+the whole system costs one pointer-compare per state transition when no
+addon uses it (no arg synthesis, no DBC lookups).
+
+```lua
+local f = CreateFrame("Frame")
+for _, e in ipairs({
+    "UNIT_SPELLCAST_START", "UNIT_SPELLCAST_STOP",
+    "UNIT_SPELLCAST_SUCCEEDED", "UNIT_SPELLCAST_CHANNEL_START",
+}) do f:RegisterEvent(e) end
+f:SetScript("OnEvent", function()
+    -- vanilla passes event/arg1/... as globals, not function params
+    if arg1 == "player" then print(event, arg3) end  -- arg3 = spellID
+end)
+```
+
+> **Player-only, and additive to the vanilla `SPELLCAST_*` events.** The
+> engine's own arg-less `SPELLCAST_START` / `SPELLCAST_CHANNEL_UPDATE` / …
+> still fire as before; these `UNIT_`-prefixed events are the modern layer
+> on top. Other units, `UNIT_SPELLCAST_FAILED_QUIET`, and the empowered-cast
+> events are not implemented.
+
 ### `C_Spell.GetSpellLevelInfo(spellID)`
 
 Returns the raw `Spell.dbc` level fields for a spell:

src/Offsets.h

@@ -1216,6 +1216,20 @@ enum Offsets {
     // collision, per-channel-start frequency).
     FUN_SPELL_CHANNEL_START = 0x006E7550,
 
+    // `MSG_CHANNEL_UPDATE` handler (`FUN_006e75f0`) — same `int __stdcall(
+    // uint32_t *opCode, CDataStore *packet)` shape. Body: a single u32 =
+    // the channel's new REMAINING time (ms). Sent to the caster on damage
+    // pushback (which shortens a vanilla channel) and once more at the
+    // channel's end (remaining == 0). Verified at 0x006e75f0: reads the u32,
+    // then fires vanilla's `SPELLCAST_CHANNEL_UPDATE(remaining)` (event
+    // 0x157) on pushback or `SPELLCAST_CHANNEL_STOP` (0x158) at end — but
+    // stores the new end NOWHERE, so `Spell::Cast`'s g_channel.endMs
+    // (computed once at start) never reflects pushback. Co-hooked to
+    // re-anchor endMs (and fire UNIT_SPELLCAST_CHANNEL_UPDATE). nampower
+    // hooks it too (SpellChannelUpdateHandlerHook — accepted co-hook, per-
+    // pushback frequency, same as the START sibling).
+    FUN_SPELL_CHANNEL_UPDATE = 0x006E75F0,
+
     // `SMSG_SPELL_FAILED_OTHER` handler — `int __stdcall(uint32_t *opCode,
     // CDataStore *packet)`, same shape as FUN_SPELL_DELAYED. Body:
     // `casterGuid(u64, plain), spellId(u32)`. In (v)mangos cores this is
@@ -1245,6 +1259,21 @@ enum Offsets {
     // hook it.
     FUN_SPELL_FAILURE = 0x006E8D80,
 
+    // `Spell_C_SpellFailed` — the CLIENT-side cast-failure entry, distinct
+    // from the two SMSG_SPELL_FAILURE/_OTHER packet handlers above. Fires
+    // for the local player's own cast rejections (out of range, no mana,
+    // "spell not ready", LoS, interrupted, …). `__fastcall(uint32_t
+    // spellId, uint8_t spellResult /*edx*/, int unk1, int unk2, bool
+    // failedByServer)` — signature per nampower's Spell_C_SpellFailedT.
+    // Backs `UNIT_SPELLCAST_FAILED` (`Spell::CastEvents`). Not hooked
+    // elsewhere in this project (we hook the packet handlers, not this).
+    FUN_SPELL_C_SPELL_FAILED = 0x006E1A00,
+
+    // `Spell_C_SpellFailed` result code for a fake/suppressed failure
+    // (Unleashed Potential and similar) — the engine's SPELL_FAILED_DONT_
+    // REPORT. nampower filters it out of its failure event; so do we.
+    SPELL_FAILED_DONT_REPORT = 23,
+
     // `CGUnit_C::ClearCastingSpell` — `__thiscall void(CGUnit *unit,
     // int spellID, char notify, char cleanup)` (nampower names the offset
     // but never hooks it). THE engine choke point for "this unit stopped

src/aura/ComboDuration.cpp

@@ -21,6 +21,7 @@
 #include "Offsets.h"
 #include "dbc/Lookup.h"
 #include "net/PacketReader.h"
+#include "net/SendObserver.h"
 #include "spell/Mod.h"
 #include "unit/Identity.h"
 
@@ -86,28 +87,17 @@ int ConsumeCapturedCP(uint32_t spellId) {
 // re-entry, but still build and send CMSG_CAST_SPELL through the engine).
 // Snapshot the combo points at the moment the cast request leaves: the
 // server consumes them before SMSG_SPELL_GO arrives, so reading at
-// SpellGo time is too late.
-using NetSend_t = void(__fastcall *)(void *conn, void *edx,
-                                     CDataStore *packet);
-NetSend_t g_origNetSend = nullptr;
-
-void __fastcall NetSend_h(void *conn, void *edx, CDataStore *packet) {
-    if (packet != nullptr) {
-        const uint32_t saved = packet->m_read;
-        const uint32_t opcode = Net::Read<uint32_t>(packet);
-        if (opcode == Offsets::OP_CMSG_CAST_SPELL) {
-            const uint32_t spellId = Net::Read<uint32_t>(packet);
-            if (spellId != 0)
-                g_capture = {spellId, CurrentComboPoints(), NowMs()};
-        }
-        packet->m_read = saved;
-    }
-    g_origNetSend(conn, edx, packet);
+// SpellGo time is too late. We watch sends through the shared
+// `Net::SendObserver` rather than owning the funnel hook ourselves.
+void OnSend(uint32_t opcode, Net::CDataStore *packet) {
+    if (opcode != Offsets::OP_CMSG_CAST_SPELL)
+        return;
+    const uint32_t spellId = Net::Read<uint32_t>(packet);
+    if (spellId != 0)
+        g_capture = {spellId, CurrentComboPoints(), NowMs()};
 }
 
-const Game::HookAutoRegister _sendHook{
-    Offsets::FUN_NET_SEND, reinterpret_cast<void *>(&NetSend_h),
-    reinterpret_cast<void **>(&g_origNetSend)};
+const Net::SendObserver::AutoSubscribe _sendSub{&OnSend};
 
 // ---- Duration data (SpellDuration.dbc + Lua overrides) --------------------
 

src/aura/Source.cpp

@@ -21,6 +21,7 @@
 #include "Offsets.h"
 #include "net/PacketReader.h"
 #include "player/StatSignal.h"
+#include "spell/CastEvents.h"
 #include "spell/Lookup.h"
 #include "tick/WorldTick.h"
 #include "totem/Tracker.h"
@@ -581,10 +582,14 @@ void __fastcall SpellGo_h(uint64_t *itemGUID, uint64_t *casterGUID,
     if (caster == 0 || spellId == 0)
         return;
 
-    // Feed the totem tracker BEFORE the aura gate below — a totem summon
-    // applies no aura, so it would otherwise be dropped. Player casts only.
-    if (caster == Unit::Identity::PlayerGuid())
+    // Feed the totem tracker + fire UNIT_SPELLCAST_SUCCEEDED BEFORE the aura
+    // gate below — a totem summon (and any non-aura spell) applies no aura,
+    // so it would otherwise be dropped. SPELL_GO is "the spell went off", so
+    // this is the succeeded signal for instants too. Player casts only.
+    if (caster == Unit::Identity::PlayerGuid()) {
         Totem::Tracker::OnPlayerSpellGo(spellId);
+        Spell::CastEvents::OnPlayerSucceeded(static_cast<int>(spellId));
+    }
 
     // Mirror server-side duration edits the client is never told about
     // (Conflagrate -3s Immolate, Molten Blast refresh Flame Shock, …). Runs

src/event/Custom.cpp

@@ -282,6 +282,22 @@ int LookupByName(const char *name) {
     return -1;
 }
 
+bool HasListeners(int slot) {
+    if (slot < 0)
+        return false;
+    auto *base = *reinterpret_cast<uint8_t **>(Offsets::VAR_EVENT_TABLE_BASE_PTR);
+    const int count = *reinterpret_cast<int *>(Offsets::VAR_EVENT_TABLE_COUNT);
+    if (base == nullptr || slot >= count)
+        return false;
+    // The entry's chain head (`+0x0C`): a populated subscriber chain is a
+    // non-zero pointer with the low bit clear; `0` or an odd (tagged)
+    // value is the empty self-sentinel — same test the grow-safety scan
+    // uses. So this is true iff at least one frame registered for the event.
+    const uint32_t head = *reinterpret_cast<const uint32_t *>(
+        base + slot * Offsets::EVENT_ENTRY_STRIDE + Offsets::OFF_EVENT_ENTRY_HEAD);
+    return head != 0 && (head & 1) == 0;
+}
+
 void RetryClaims() {
     // Grow the table first if the low gap pool is short (dormant valve).
     // Runs at most once per table build; on the first call every chain is

src/event/Custom.h

@@ -64,6 +64,15 @@ int Lookup(const char *name);
 // fire ourselves (e.g., polyfilling missing event dispatches).
 int LookupByName(const char *name);
 
+// True iff at least one frame is currently registered for the event in
+// `slot` (its subscriber chain is non-empty). Reads the entry's chain
+// head at `+0x0C` — a couple of pointer derefs, no allocation. Use this
+// to gate expensive per-fire work (arg synthesis, DBC lookups) so an
+// event nobody listens to costs almost nothing: `if (HasListeners(slot))
+// { …build args…; Fire(slot, …); }`. `false` for `slot < 0` or a slot
+// past the live table.
+bool HasListeners(int slot);
+
 // Dispatches a custom event via the engine's printf-style event
 // dispatcher at `FUN_FIRE_EVENT` (`0x00703F50`). `format` is a
 // concatenation of `%d` (int), `%u` (uint), `%f` (double), `%s`

src/net/SendObserver.cpp

@@ -0,0 +1,56 @@
+// 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 <https://www.gnu.org/licenses/>.
+
+#include "SendObserver.h"
+
+#include "Game.h"
+#include "Offsets.h"
+
+namespace Net::SendObserver {
+
+namespace {
+
+AutoSubscribe *g_head = nullptr;
+
+// `FUN_NET_SEND` — `__thiscall(conn, CDataStore*)`, rendered here as
+// `__fastcall(conn /*ecx*/, edx, packet)`. The leading u32 of the buffer is
+// the opcode.
+using NetSend_t = void(__fastcall *)(void *conn, void *edx, CDataStore *packet);
+NetSend_t g_origNetSend = nullptr;
+
+void __fastcall NetSend_h(void *conn, void *edx, CDataStore *packet) {
+    if (packet != nullptr && g_head != nullptr) {
+        const uint32_t saved = packet->m_read;
+        const uint32_t opcode = Net::Read<uint32_t>(packet);
+        const uint32_t afterOpcode = packet->m_read;
+        for (auto *node = g_head; node != nullptr; node = node->next) {
+            packet->m_read = afterOpcode; // each subscriber reads independently
+            node->cb(opcode, packet);
+        }
+        packet->m_read = saved; // hand the engine an untouched cursor
+    }
+    g_origNetSend(conn, edx, packet);
+}
+
+} // namespace
+
+AutoSubscribe::AutoSubscribe(Callback cb) : cb(cb), next(g_head) {
+    g_head = this;
+}
+
+static const Game::HookAutoRegister _hook{
+    Offsets::FUN_NET_SEND,
+    reinterpret_cast<void *>(&NetSend_h),
+    reinterpret_cast<void **>(&g_origNetSend)};
+
+} // namespace Net::SendObserver

src/net/SendObserver.h

@@ -0,0 +1,44 @@
+// 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.
+
+#pragma once
+
+#include "net/PacketReader.h"
+
+#include <cstdint>
+
+// Shared observer for outgoing packets. The engine's NetClient send funnel
+// (`FUN_NET_SEND`) is a general chokepoint every dispatched CMSG passes
+// through — not something a single feature should own. MinHook permits one
+// hook per target, so any module that wants to watch sent packets subscribes
+// here instead of hooking the funnel itself.
+//
+// Mirrors `Tick::WorldTick`: declare a file-scope
+// `static const Net::SendObserver::AutoSubscribe _sub{&callback};`. The
+// constructor chains onto the internal list at static-init time.
+//
+// Each subscriber's callback receives the leading `opcode` (u32) already
+// read, and the `CDataStore` positioned **right after the opcode** so it can
+// read the message body directly. The observer resets that cursor before
+// every subscriber (so they read independently) and restores the original
+// `m_read` before handing the packet to the engine. Callbacks must only
+// READ — never mutate the packet.
+
+namespace Net::SendObserver {
+
+using Callback = void (*)(uint32_t opcode, CDataStore *packet);
+
+struct AutoSubscribe {
+    explicit AutoSubscribe(Callback cb);
+    Callback cb;
+    AutoSubscribe *next;
+};
+
+} // namespace Net::SendObserver