wowlab_engine_domain/dbc/semantics/

spell_cast_target_flags.rs

//! Explicit spell cast-target payload and validation flags.

use super::SemanticSupport;

bitflags::bitflags! {
    /// TrinityCore `SpellCastTargetFlags`, sourced from `SpellDefines.h`.
    #[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq)]
    pub struct SpellCastTargetFlags: u32 {
        const UNUSED_0 = 1 << 0;
        const UNIT = 1 << 1;
        const UNIT_RAID = 1 << 2;
        const UNIT_PARTY = 1 << 3;
        const ITEM = 1 << 4;
        const SOURCE_LOCATION = 1 << 5;
        const DEST_LOCATION = 1 << 6;
        const UNIT_ENEMY = 1 << 7;
        const UNIT_ALLY = 1 << 8;
        const CORPSE_ENEMY = 1 << 9;
        const UNIT_DEAD = 1 << 10;
        const GAMEOBJECT = 1 << 11;
        const TRADE_ITEM = 1 << 12;
        const STRING = 1 << 13;
        const GAMEOBJECT_ITEM = 1 << 14;
        const CORPSE_ALLY = 1 << 15;
        const UNIT_MINIPET = 1 << 16;
        const GLYPH_SLOT = 1 << 17;
        const DEST_TARGET = 1 << 18;
        const EXTRA_TARGETS = 1 << 19;
        const UNIT_PASSENGER = 1 << 20;
        const UNKNOWN_22 = 1 << 22;
        const UNKNOWN_24 = 1 << 24;
        const UNKNOWN_26 = 1 << 26;
        const UNKNOWN_28 = 1 << 28;
        const UNKNOWN_30 = 1 << 30;

        const UNIT_MASK = Self::UNIT.bits()
            | Self::UNIT_RAID.bits()
            | Self::UNIT_PARTY.bits()
            | Self::UNIT_ENEMY.bits()
            | Self::UNIT_ALLY.bits()
            | Self::UNIT_DEAD.bits()
            | Self::UNIT_MINIPET.bits()
            | Self::UNIT_PASSENGER.bits();
        const GAMEOBJECT_MASK = Self::GAMEOBJECT.bits() | Self::GAMEOBJECT_ITEM.bits();
        const CORPSE_MASK = Self::CORPSE_ALLY.bits() | Self::CORPSE_ENEMY.bits();
        const ITEM_MASK = Self::TRADE_ITEM.bits() | Self::ITEM.bits() | Self::GAMEOBJECT_ITEM.bits();
    }
}

impl SpellCastTargetFlags {
    /// Preserve every authored DBC bit, including currently unknown bits.
    #[must_use]
    pub const fn from_dbc(raw: i32) -> Self {
        Self::from_bits_retain(u32::from_ne_bytes(raw.to_ne_bytes()))
    }

    /// Whether the cast requires an explicitly selected hostile unit.
    #[must_use]
    pub const fn requires_hostile_unit(self) -> bool {
        self.intersects(Self::from_bits_retain(
            Self::UNIT.bits() | Self::UNIT_ENEMY.bits(),
        ))
    }
}

/// Engine coverage for one authored or derived cast-target flag.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SpellCastTargetFlagSemantic {
    pub flag: SpellCastTargetFlags,
    pub name: &'static str,
    pub support: SemanticSupport,
    pub handler: &'static str,
}

const fn target_flag(
    flag: SpellCastTargetFlags,
    name: &'static str,
    support: SemanticSupport,
    handler: &'static str,
) -> SpellCastTargetFlagSemantic {
    SpellCastTargetFlagSemantic {
        flag,
        name,
        support,
        handler,
    }
}

use SemanticSupport::{Generic, Ignored, Partial, Unsupported};

/// Canonical coverage registry for `TrinityCore` cast-target flags.
pub const SPELL_CAST_TARGET_FLAG_SEMANTICS: &[SpellCastTargetFlagSemantic] = &[
    target_flag(
        SpellCastTargetFlags::UNUSED_0,
        "Unused 0",
        Ignored,
        "unused protocol bit",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT,
        "Unit",
        Generic,
        "shared explicit-unit cast and range resolution",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_RAID,
        "Raid Unit",
        Unsupported,
        "friendly raid actor selection",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_PARTY,
        "Party Unit",
        Unsupported,
        "friendly party actor selection",
    ),
    target_flag(
        SpellCastTargetFlags::ITEM,
        "Item",
        Unsupported,
        "inventory item cast targets",
    ),
    target_flag(
        SpellCastTargetFlags::SOURCE_LOCATION,
        "Source Location",
        Generic,
        "cast requests snapshot and carry the explicit source position into target execution",
    ),
    target_flag(
        SpellCastTargetFlags::DEST_LOCATION,
        "Destination Location",
        Generic,
        "cast requests snapshot and carry authored destination positions into target execution",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_ENEMY,
        "Enemy Unit",
        Generic,
        "shared hostile-unit cast, range, and line-of-sight resolution",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_ALLY,
        "Ally Unit",
        Unsupported,
        "explicit friendly actor selection",
    ),
    target_flag(
        SpellCastTargetFlags::CORPSE_ENEMY,
        "Enemy Corpse",
        Unsupported,
        "corpse actor selection",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_DEAD,
        "Dead Unit",
        Unsupported,
        "dead-unit selection",
    ),
    target_flag(
        SpellCastTargetFlags::GAMEOBJECT,
        "Game Object",
        Unsupported,
        "game-object selection",
    ),
    target_flag(
        SpellCastTargetFlags::TRADE_ITEM,
        "Trade Item",
        Unsupported,
        "trade item targets",
    ),
    target_flag(
        SpellCastTargetFlags::STRING,
        "String",
        Unsupported,
        "string cast-target payloads",
    ),
    target_flag(
        SpellCastTargetFlags::GAMEOBJECT_ITEM,
        "Game Object or Item",
        Unsupported,
        "game-object and item selection",
    ),
    target_flag(
        SpellCastTargetFlags::CORPSE_ALLY,
        "Ally Corpse",
        Unsupported,
        "friendly corpse selection",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_MINIPET,
        "Minipet",
        Unsupported,
        "minipet actor selection",
    ),
    target_flag(
        SpellCastTargetFlags::GLYPH_SLOT,
        "Glyph Slot",
        Unsupported,
        "glyph-slot payloads",
    ),
    target_flag(
        SpellCastTargetFlags::DEST_TARGET,
        "Destination Target",
        Partial,
        "implicit target-derived destinations",
    ),
    target_flag(
        SpellCastTargetFlags::EXTRA_TARGETS,
        "Extra Targets",
        Unsupported,
        "explicit extra-target payloads",
    ),
    target_flag(
        SpellCastTargetFlags::UNIT_PASSENGER,
        "Passenger Unit",
        Unsupported,
        "vehicle passenger selection",
    ),
    target_flag(
        SpellCastTargetFlags::UNKNOWN_22,
        "Unknown 22",
        Unsupported,
        "unknown TrinityCore target flag",
    ),
    target_flag(
        SpellCastTargetFlags::UNKNOWN_24,
        "Unknown 24",
        Unsupported,
        "unknown TrinityCore target flag",
    ),
    target_flag(
        SpellCastTargetFlags::UNKNOWN_26,
        "Unknown 26",
        Unsupported,
        "unknown TrinityCore target flag",
    ),
    target_flag(
        SpellCastTargetFlags::UNKNOWN_28,
        "Unknown 28",
        Unsupported,
        "unknown TrinityCore target flag",
    ),
    target_flag(
        SpellCastTargetFlags::UNKNOWN_30,
        "Unknown 30",
        Unsupported,
        "unknown TrinityCore target flag",
    ),
];

/// Lookup one single-bit cast-target flag in the canonical coverage registry.
#[must_use]
pub fn spell_cast_target_flag_semantic(
    flag: SpellCastTargetFlags,
) -> Option<&'static SpellCastTargetFlagSemantic> {
    SPELL_CAST_TARGET_FLAG_SEMANTICS
        .iter()
        .find(|semantic| semantic.flag == flag)
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;

    use super::*;

    #[gtest]
    fn retains_unknown_bits_and_exposes_trinity_composites() {
        let raw = i32::from_ne_bytes(((1_u32 << 30) | (1 << 22) | (1 << 7)).to_ne_bytes());
        let mask = SpellCastTargetFlags::from_dbc(raw);

        expect_that!(mask.contains(SpellCastTargetFlags::UNIT_ENEMY), is_true());
        expect_that!(mask.contains(SpellCastTargetFlags::UNKNOWN_22), is_true());
        expect_that!(mask.contains(SpellCastTargetFlags::UNKNOWN_30), is_true());
        expect_that!(
            SpellCastTargetFlags::UNIT_MASK.contains(SpellCastTargetFlags::UNIT_ENEMY),
            is_true()
        );
    }

    #[gtest]
    fn every_declared_single_bit_flag_has_coverage() {
        for bit in 0..u32::BITS {
            let flag = SpellCastTargetFlags::from_bits_retain(1 << bit);

            if SpellCastTargetFlags::all().contains(flag) {
                expect_that!(spell_cast_target_flag_semantic(flag).is_some(), is_true());
            }
        }
    }
}