benilla-octo/crates/benilla-ui/src/script/compat/classic_api/action.rs

//! ClassicAPI's `Action` namespace: `GetActionInfo`, a bare global. Over the same action table
//! the stock `GetActionTexture`/`GetActionCount`/`IsConsumableAction` already read
//! (`script/action.rs`'s `Model::actions`). Signature is from the upstream repo's own `docs/API.md`
//! (fetched 2026-10-05).
//!
//! Upstream reaches this by unpacking a `uint32` whose top nibble is a type tag, then
//! disambiguating its one ambiguous tag (`0x4`, macro-or-bag-item) by walking the macro-slot map.
//! benilla needs none of that: the host pushes `ActionSlot::kind` already separated into the three
//! `ACTION_KIND_*` bytes, so the tag is read rather than inferred, and the macro/bag-item
//! ambiguity upstream has to resolve does not exist here.
//!
//! The one thing upstream cannot do and this can: upstream returns `"item", nil` for a
//! bag-instance item reference, because extracting the item id from the bag-action hash "needs
//! more reversing than we've done". benilla's slot carries the resolved id for every kind, so the
//! id is always real here.

use mlua::{Lua, MultiValue, Value};

use crate::script::action::{ACTION_KIND_ITEM, ACTION_KIND_MACRO, ACTION_KIND_SPELL};
use crate::script::Model;

pub(super) fn install(lua: &Lua) -> mlua::Result<()> {
    // GetActionInfo(slot) → `actionType, id, subType`, nothing for an empty slot. `subType` is
    // only ever `"spell"`, and only for a spell action, as upstream documents (its engine helper
    // hardcodes the pet flag to 0 on this table; pet-bar actions live in their own table, which
    // the stock pet-action verbs read).
    lua.globals().set(
        "GetActionInfo",
        lua.create_function(|lua, slot: Option<u32>| {
            let model = lua.app_data_ref::<Model>().expect("model app_data");
            let Some(action) = slot.and_then(|s| model.actions.get(&s)) else {
                return Ok(MultiValue::new());
            };
            // The kind byte's top nibble, the same mask `script/action.rs` tests the macro kind
            // with: a slot carries its kind in the high bits and flags in the low ones.
            let kind = match action.kind & 0xf0 {
                ACTION_KIND_SPELL => "spell",
                ACTION_KIND_MACRO => "macro",
                ACTION_KIND_ITEM => "item",
                // A kind byte this crate does not know is not an action it can describe; nothing
                // is the loop terminator every caller already handles.
                _ => return Ok(MultiValue::new()),
            };
            let mut out = vec![
                Value::String(lua.create_string(kind)?),
                Value::Integer(i64::from(action.action)),
            ];
            if kind == "spell" {
                out.push(Value::String(lua.create_string("spell")?));
            }
            Ok(MultiValue::from_vec(out))
        })?,
    )
}

#[cfg(test)]
mod tests {
    use crate::script::{ActionSlot, UiScript};

    fn slot(kind: u8, action: u32) -> ActionSlot {
        ActionSlot {
            kind,
            action,
            ..Default::default()
        }
    }

    #[test]
    fn get_action_info_reads_the_kind_byte_and_only_a_spell_carries_a_subtype() {
        use crate::script::action::{ACTION_KIND_ITEM, ACTION_KIND_MACRO, ACTION_KIND_SPELL};

        let mut s = UiScript::new().unwrap();
        s.set_action(1, Some(slot(ACTION_KIND_SPELL, 133)));
        s.set_action(2, Some(slot(ACTION_KIND_MACRO, 7)));
        s.set_action(3, Some(slot(ACTION_KIND_ITEM, 6948)));

        assert_eq!(
            s.eval::<(String, i64, String)>("return GetActionInfo(1)")
                .unwrap(),
            ("spell".to_string(), 133, "spell".to_string())
        );
        assert_eq!(
            s.arity("GetActionInfo(1)").unwrap(),
            3,
            "a spell carries the subType"
        );

        assert_eq!(
            s.eval::<(String, i64)>("return GetActionInfo(2)").unwrap(),
            ("macro".to_string(), 7)
        );
        assert_eq!(
            s.arity("GetActionInfo(2)").unwrap(),
            2,
            "a macro has no subType"
        );

        // Upstream returns `"item", nil` for a bag-instance reference; benilla's slot carries the
        // resolved id, so the id is real here.
        assert_eq!(
            s.eval::<(String, i64)>("return GetActionInfo(3)").unwrap(),
            ("item".to_string(), 6948)
        );

        // An empty slot and a missing argument are both nothing, not a row of nils.
        assert_eq!(s.arity("GetActionInfo(9)").unwrap(), 0);
        assert_eq!(s.arity("GetActionInfo()").unwrap(), 0);
    }
}