benilla-octo/crates/benilla-ui/src/script/cast_events.rs

//! ClassicAPI's `UNIT_SPELLCAST_*` events (`docs/ADDON_COMPAT.md`): the **per-token** half of the
//! per-GUID cast windows `benilla-app`'s `ui_cast_events.rs` folds.
//!
//! A cast belongs to a unit; these events are addressed to a *token*. That mismatch is the whole
//! content of this file. One cast routinely has to reach several tokens at once — a mob can be
//! `"target"` and `"nameplate3"` and `"focus"` in the same instant, and each of those drives a
//! different frame in pfUI — so the fan-out is "once per live token", never "once per cast".
//! [`Model::tokens_for_guid`](super::Model::tokens_for_guid) is that set; its singular sibling
//! `token_for_guid` answers only one token and would silently drop the other bars.
//!
//! **The argument shape comes from the consumers, not from memory.** pfUI's cast bar states it in
//! as many words (`modules/castbar.lua:354`, "Args: arg1=unit, arg2=castGUID, arg3=spellID,
//! arg4=name, arg5=rank") and reads `arg5` as the rank it labels the bar with (`:357` →
//! `RefreshBar(this, arg5)` → `:102-107`) and `arg3` as the spell id it counts crafts by (`:370`).
//! pfUI's nameplate module reads `arg1` alone, behind a `strfind(arg1, "^nameplate")` guard
//! (`modules/nameplates.lua:646-671`). Nothing in the corpus reads `arg2`.
//!
//! Two details that are only visible from the consumer side:
//!
//! - **All five arguments are always pushed, `nil` included** — a rankless spell fires five with
//!   the fifth nil, not four. Two things turn on it. The handler also receives
//!   `(self, event, arg1..argN)` positionally (`script/event.rs:260-266`), so a short push is a
//!   *shorter event* to anything reading `...`/`select("#", ...)`, and arity is the one part of a
//!   positional contract a caller cannot work around. And `invoke_with_globals` saves and restores
//!   exactly the `argN` it sets (`:246-258`, `:271-274`), as the reference does — which makes a
//!   short push leave `arg5` holding whatever the *enclosing* dispatch put there, so a fire nested
//!   inside another event's handler would hand pfUI that event's fifth argument as this spell's
//!   rank (`modules/castbar.lua:357` passes `arg5` straight into the bar's label, and `:102-105`
//!   *prefers* it over a fresh `GetSpellSubtext` lookup). Five slots, every time.
//! - **`arg2` is nil, not a GUID.** 1.12 carries no per-cast identifier anywhere on the wire —
//!   the same reason `C_Spell.UnitCastingInfo`'s 7th return (`castID`) is nil
//!   (`compat/classic_api/spell.rs`). The two have to agree: an addon that keyed a table on the
//!   event's `castID` and looked it up from the getter's would find nothing either way, which is
//!   honest; one nil and one invented string would be worse.
//!
//! Name and rank come from [`spell_display`](super::spellbook::spell_display) — the player's book
//! first, then the host's `Spell.dbc` probe — which is the *same* body behind
//! `C_Spell.GetSpellName`/`GetSpellSubtext`. That is load-bearing rather than tidy: pfUI prefers
//! the event's `arg5` and falls back to `C_Spell.GetSpellSubtext(spellID)` only when it has no
//! event in hand (`modules/castbar.lua:102-107`), so a bar stamped from an event and the same bar
//! stamped from the retarget re-poll would print two different ranks if these came from two
//! sources.

use super::{spellbook::spell_display, ScriptValue, UiScript};

impl UiScript {
    /// Fire one `UNIT_SPELLCAST_*` event for a cast by `caster`, once per unit token that
    /// currently names that caster, and answer the tokens it fired under.
    ///
    /// `event` is the full event name, passed in by the app: the app owns the edge → event mapping
    /// because the app owns the wire edges (`ui_cast_events.rs`'s `CastEdge`), and keeping the
    /// mapping beside the window fold is what lets one read of the brief check that the two agree.
    /// This side owns everything that is a question about tokens or about naming a spell.
    ///
    /// A caster no token names fires nothing at all, and that is the right answer rather than a
    /// gap: with no token, there is no `arg1` a handler could act on, and every consumer's first
    /// move is to resolve `arg1` back to a unit. The cast is still in the windows, so the moment a
    /// token *does* name the caster — the player targets it, a nameplate spawns on it — the
    /// consumer's own re-poll finds it (`modules/castbar.lua:340` on `PLAYER_TARGET_CHANGED`,
    /// `modules/nameplates.lua:602` on `NAME_PLATE_UNIT_ADDED`). Firing a synthetic start on token
    /// *acquisition* would duplicate those two re-polls, and would be an event with no wire edge
    /// behind it — the one thing this family must not invent.
    pub fn fire_unit_spellcast(&mut self, event: &str, caster: u64, spell_id: u32) -> Vec<String> {
        // One borrow of the model for both questions, released before the first handler runs: a
        // handler re-enters the VM and will take its own.
        let (tokens, name, rank) = {
            let model = self.model_ref();
            let tokens: Vec<String> = model
                .tokens_for_guid(caster)
                .into_iter()
                .map(str::to_string)
                .collect();
            let display = spell_display(&model, spell_id);
            let name = display.as_ref().map(|d| d.name.clone());
            let rank = display.and_then(|d| d.rank);
            (tokens, name, rank)
        };
        let named = |s: Option<String>| s.map_or(ScriptValue::Nil, ScriptValue::Str);
        for token in &tokens {
            self.fire_event(
                event,
                vec![
                    ScriptValue::Str(token.clone()),
                    // arg2 `castGUID`: see this module's header — 1.12 has no such identifier.
                    ScriptValue::Nil,
                    ScriptValue::Int(i64::from(spell_id)),
                    named(name.clone()),
                    named(rank.clone()),
                ],
            );
        }
        tokens
    }
}