wowlab_types/types/sim/

idx.rs

use derive_more::{Debug, Display, From, Into};
use nohash_hasher::BuildNoHashHasher;
use serde::{Deserialize, Serialize};

use super::encounter::ActorId;

pub type IntMap<K, V> = std::collections::HashMap<K, V, BuildNoHashHasher<K>>;

pub type IntSet<K> = std::collections::HashSet<K, BuildNoHashHasher<K>>;

/// Fast deterministic hasher for trusted in-process keys.
#[derive(Clone, Default)]
pub struct FastBuildHasher(foldhash::fast::FixedState);

impl FastBuildHasher {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
}

impl std::fmt::Debug for FastBuildHasher {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("FastBuildHasher")
    }
}

impl std::hash::BuildHasher for FastBuildHasher {
    type Hasher = <foldhash::fast::FixedState as std::hash::BuildHasher>::Hasher;

    fn build_hasher(&self) -> Self::Hasher {
        self.0.build_hasher()
    }
}

/// Marker for keys compatible with the integer identity hasher.
pub trait IsEnabled: nohash_hasher::IsEnabled {}

impl<T> IsEnabled for T where T: nohash_hasher::IsEnabled {}

pub type FastMap<K, V> = std::collections::HashMap<K, V, FastBuildHasher>;

pub type FastSet<K> = std::collections::HashSet<K, FastBuildHasher>;

macro_rules! define_u32_idx {
    (
        $(#[doc = $doc:literal])*
        $name:ident, debug_prefix = $debug_prefix:literal
    ) => {
        $(#[doc = $doc])*
        #[expect(
            clippy::unsafe_derive_deserialize,
            reason = "transparent integer newtypes accept every underlying bit pattern"
        )]
        #[derive(
            Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash,
            Serialize, Deserialize, Display, From, Into,
        )]
        #[display("{_0}")]
        #[serde(transparent)]
        #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
        #[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
        #[repr(transparent)]
        pub struct $name(pub u32);

        impl $name {
            #[doc = concat!(stringify!($name), " is `#[repr(transparent)]` over `u32`.")]
            #[inline]
            pub fn cast_slice(slice: &[u32]) -> &[Self] {
                // SAFETY: repr(transparent) over u32
                unsafe { &*(std::ptr::from_ref(slice) as *const [Self]) }
            }

            #[inline]
            pub fn cast_slice_mut(slice: &mut [u32]) -> &mut [Self] {
                // SAFETY: repr(transparent) over u32
                unsafe { &mut *(std::ptr::from_mut(slice) as *mut [Self]) }
            }

            #[inline]
            pub const fn from_raw(id: u32) -> Self {
                Self(id)
            }

            #[inline]
            pub fn try_from_usize(idx: usize) -> Option<Self> {
                u32::try_from(idx).ok().map(Self)
            }

            #[inline]
            pub const fn as_usize(self) -> usize {
                self.0 as usize
            }

            #[inline]
            pub const fn as_u32(self) -> u32 {
                self.0
            }
        }

        impl std::fmt::Debug for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                write!(f, concat!(stringify!($name), "({})"), self.0)
            }
        }

        impl nohash_hasher::IsEnabled for $name {}

        impl From<$name> for u64 {
            #[inline]
            fn from(idx: $name) -> u64 {
                u64::from(idx.0)
            }
        }
    };
}

macro_rules! define_u16_idx {
    (
        $(#[doc = $doc:literal])*
        $name:ident, max = $max:expr
    ) => {
        $(#[doc = $doc])*
        #[expect(
            clippy::unsafe_derive_deserialize,
            // #t(rust_duplicate_strings) Rust attributes require a literal reason at the declaration they govern.
            reason = "transparent integer newtypes accept every underlying bit pattern"
        )]
        #[derive(
            Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash,
            Serialize, Deserialize, Display, From, Into,
        )]
        #[display("{_0}")]
        #[serde(transparent)]
        #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
        #[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
        #[repr(transparent)]
        pub struct $name(pub u16);

        impl $name {
            pub const MAX: usize = $max;

            #[doc = concat!(stringify!($name), " is `#[repr(transparent)]` over `u16`.")]
            #[inline]
            pub fn cast_slice(slice: &[u16]) -> &[Self] {
                // SAFETY: repr(transparent) over u16
                unsafe { &*(std::ptr::from_ref(slice) as *const [Self]) }
            }

            #[inline]
            pub fn cast_slice_mut(slice: &mut [u16]) -> &mut [Self] {
                // SAFETY: repr(transparent) over u16
                unsafe { &mut *(std::ptr::from_mut(slice) as *mut [Self]) }
            }

            #[inline]
            pub const fn from_raw(idx: u16) -> Self {
                Self(idx)
            }

            #[inline]
            pub fn try_from_usize(idx: usize) -> Option<Self> {
                (idx < Self::MAX)
                    .then(|| u16::try_from(idx).ok())
                    .flatten()
                    .map(Self)
            }

            #[inline]
            pub const fn as_usize(self) -> usize {
                self.0 as usize
            }

            #[inline]
            pub const fn as_u16(self) -> u16 {
                self.0
            }

            pub fn iter(count: usize) -> impl Iterator<Item = $name> {
                (0..count.min(Self::MAX)).filter_map($name::try_from_usize)
            }
        }
    };
}

macro_rules! define_u8_idx {
    (
        $(#[doc = $doc:literal])*
        $name:ident, max = $max:expr
    ) => {
        $(#[doc = $doc])*
        #[expect(
            clippy::unsafe_derive_deserialize,
            // #t(rust_duplicate_strings) Rust attributes require a literal reason at the declaration they govern.
            reason = "transparent integer newtypes accept every underlying bit pattern"
        )]
        #[derive(
            Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash,
            Serialize, Deserialize, Debug, Display, From, Into,
        )]
        #[debug("{}({_0})", stringify!($name))]
        #[display("{_0}")]
        #[serde(transparent)]
        #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
        #[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
        #[repr(transparent)]
        pub struct $name(pub u8);

        impl $name {
            pub const MAX: usize = $max;

            #[doc = concat!(stringify!($name), " is `#[repr(transparent)]` over `u8`.")]
            #[inline]
            pub fn cast_slice(slice: &[u8]) -> &[Self] {
                // SAFETY: repr(transparent) over u8
                unsafe { &*(std::ptr::from_ref(slice) as *const [Self]) }
            }

            #[inline]
            pub fn cast_slice_mut(slice: &mut [u8]) -> &mut [Self] {
                // SAFETY: repr(transparent) over u8
                unsafe { &mut *(std::ptr::from_mut(slice) as *mut [Self]) }
            }

            #[inline]
            pub const fn from_raw(idx: u8) -> Self {
                Self(idx)
            }

            #[inline]
            pub fn try_from_usize(idx: usize) -> Option<Self> {
                (idx < Self::MAX)
                    .then(|| u8::try_from(idx).ok())
                    .flatten()
                    .map(Self)
            }

            #[inline]
            pub const fn as_usize(self) -> usize {
                self.0 as usize
            }

            #[inline]
            pub const fn as_u8(self) -> u8 {
                self.0
            }
        }
    };
}

define_u32_idx! {
    /// A type-safe spell identifier (`WoW` spell ID).
    SpellIdx, debug_prefix = "SpellIdx({_0})"
}

impl SpellIdx {
    #[inline]
    #[must_use]
    pub const fn is_valid(self) -> bool {
        self.0 != 0
    }
}

define_u32_idx! {
    /// A type-safe aura identifier (`WoW` spell ID for auras).
    AuraIdx, debug_prefix = "AuraIdx({_0})"
}

impl AuraIdx {
    #[inline]
    #[must_use]
    pub const fn is_valid(self) -> bool {
        self.0 != 0
    }
}

define_u32_idx! {
    ProcIdx, debug_prefix = "ProcIdx({_0})"
}

define_u16_idx! {
    /// A type-safe unit index: 0 player, 1..N pets, N+1.. enemies.
    UnitIdx, max = u16::MAX as usize
}

impl UnitIdx {
    pub const PLAYER: UnitIdx = UnitIdx(0);

    #[inline]
    #[must_use]
    pub fn from_usize_saturating(idx: usize) -> Self {
        Self(u16::try_from(idx.min(Self::MAX)).unwrap_or(u16::MAX))
    }

    #[inline]
    #[must_use]
    pub const fn is_player(self) -> bool {
        self.0 == 0
    }
}

impl std::fmt::Debug for UnitIdx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.0 == 0 {
            write!(f, "UnitIdx(PLAYER)")
        } else {
            write!(f, "UnitIdx({})", self.0)
        }
    }
}

define_u16_idx! {
    TargetIdx, max = u16::MAX as usize
}

impl TargetIdx {
    pub const PRIMARY: TargetIdx = TargetIdx(0);

    #[inline]
    #[must_use]
    pub fn from_usize_saturating(idx: usize) -> Self {
        Self(u16::try_from(idx.min(Self::MAX)).unwrap_or(u16::MAX))
    }

    #[inline]
    #[must_use]
    pub const fn is_primary(self) -> bool {
        self.0 == 0
    }
}

impl std::fmt::Debug for TargetIdx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.0 == 0 {
            write!(f, "TargetIdx(PRIMARY)")
        } else {
            write!(f, "TargetIdx({})", self.0)
        }
    }
}

define_u16_idx! {
    PetIdx, max = 256
}

impl PetIdx {
    pub const PRIMARY: PetIdx = PetIdx(0);

    /// Maps a guardian arena slot after the reserved persistent-primary-pet identity.
    #[inline]
    #[must_use]
    pub fn from_guardian_slot(slot: usize) -> Option<Self> {
        slot.checked_add(Self::PRIMARY.as_usize() + 1)
            .and_then(Self::try_from_usize)
    }

    #[inline]
    #[must_use]
    pub const fn is_primary(self) -> bool {
        self.0 == 0
    }

    #[inline]
    #[must_use]
    pub const fn to_unit_idx(&self) -> UnitIdx {
        UnitIdx(self.0 + 1)
    }
}

impl std::fmt::Debug for PetIdx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.0 == 0 {
            write!(f, "PetIdx(PRIMARY)")
        } else {
            write!(f, "PetIdx({})", self.0)
        }
    }
}

define_u16_idx! {
    EnemyIdx, max = 256
}

impl EnemyIdx {
    pub const PRIMARY: EnemyIdx = EnemyIdx(0);

    #[inline]
    #[must_use]
    pub const fn is_primary(self) -> bool {
        self.0 == 0
    }

    #[inline]
    #[must_use]
    pub const fn to_target_idx(&self) -> TargetIdx {
        TargetIdx(self.0)
    }
}

impl std::fmt::Debug for EnemyIdx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.0 == 0 {
            write!(f, "EnemyIdx(PRIMARY)")
        } else {
            write!(f, "EnemyIdx({})", self.0)
        }
    }
}

define_u16_idx! {
    /// Stable identifier for an encounter enemy group.
    GroupId, max = u16::MAX as usize
}

impl std::fmt::Debug for GroupId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "GroupId({})", self.0)
    }
}

define_u16_idx! {
    /// Stable identifier for an encounter activation wave.
    WaveId, max = u16::MAX as usize
}

impl std::fmt::Debug for WaveId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "WaveId({})", self.0)
    }
}

define_u16_idx! {
    /// Stable identifier for an encounter pull.
    PullId, max = u16::MAX as usize
}

impl std::fmt::Debug for PullId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "PullId({})", self.0)
    }
}

define_u32_idx! {
    SnapshotIdx, debug_prefix = "SnapshotIdx({_0})"
}

impl SnapshotIdx {
    pub const INVALID: SnapshotIdx = SnapshotIdx(0);

    #[inline]
    #[must_use]
    pub const fn is_valid(self) -> bool {
        self.0 != 0
    }

    #[inline]
    #[must_use]
    pub const fn next(self) -> Self {
        Self(self.0.wrapping_add(1))
    }
}

define_u8_idx! {
    ResourceIdx, max = 32
}

impl ResourceIdx {
    pub const MANA: ResourceIdx = ResourceIdx(0);
    pub const RAGE: ResourceIdx = ResourceIdx(1);
    pub const FOCUS: ResourceIdx = ResourceIdx(2);
    pub const ENERGY: ResourceIdx = ResourceIdx(3);
    pub const COMBO_POINTS: ResourceIdx = ResourceIdx(4);
    pub const RUNES: ResourceIdx = ResourceIdx(5);
    pub const RUNIC_POWER: ResourceIdx = ResourceIdx(6);
    pub const SOUL_SHARDS: ResourceIdx = ResourceIdx(7);
    pub const ASTRAL_POWER: ResourceIdx = ResourceIdx(8);
    pub const HOLY_POWER: ResourceIdx = ResourceIdx(9);
    pub const MAELSTROM: ResourceIdx = ResourceIdx(10);
    pub const CHI: ResourceIdx = ResourceIdx(11);
    pub const INSANITY: ResourceIdx = ResourceIdx(12);
    pub const FURY: ResourceIdx = ResourceIdx(13);
    pub const PAIN: ResourceIdx = ResourceIdx(14);
    pub const ESSENCE: ResourceIdx = ResourceIdx(15);
}

#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
// #t(rust_non_exhaustive_on_public) WoW aura targets are a fixed set (Player, Target, Pet)
pub enum AuraOn {
    #[default]
    Player,
    Target,
    Pet,
}

impl std::fmt::Display for AuraOn {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Player => f.write_str("player"),
            Self::Target => f.write_str("target"),
            Self::Pet => f.write_str("pet"),
        }
    }
}

/// Collision-free identity for one aura instance.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct AuraKey {
    aura: AuraIdx,
    source: ActorId,
    affected: ActorId,
    on: AuraOn,
}

/// Dense-buffer identity for an APL aura category projection.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct AuraProjectionKey {
    aura: AuraIdx,
    on: AuraOn,
}

impl AuraProjectionKey {
    #[inline]
    #[must_use]
    pub const fn new(aura: AuraIdx, on: AuraOn) -> Self {
        Self { aura, on }
    }

    #[inline]
    #[must_use]
    pub const fn aura(self) -> AuraIdx {
        self.aura
    }

    #[inline]
    #[must_use]
    pub const fn on(self) -> AuraOn {
        self.on
    }
}

impl AuraKey {
    #[inline]
    // #t(fn: rust_ctor_param_count) the four fields are the irreducible exact aura identity
    #[must_use]
    pub const fn new(aura: AuraIdx, source: ActorId, affected: ActorId, on: AuraOn) -> Self {
        Self {
            aura,
            source,
            affected,
            on,
        }
    }

    #[inline]
    #[must_use]
    pub const fn aura(self) -> AuraIdx {
        self.aura
    }

    #[inline]
    #[must_use]
    pub const fn source(self) -> ActorId {
        self.source
    }

    #[inline]
    #[must_use]
    pub const fn affected(self) -> ActorId {
        self.affected
    }

    #[inline]
    #[must_use]
    pub const fn on(self) -> AuraOn {
        self.on
    }
}

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

    use super::*;

    #[gtest]
    #[rstest]
    #[case::spell_at_u32_max(u32::MAX as usize, Some(SpellIdx(u32::MAX)))]
    #[case::spell_over_u32_max(u32::MAX as usize + 1, None)]
    fn spell_try_from_usize(
        #[case] input: usize,
        #[case] expected: Option<SpellIdx>,
    ) -> Result<()> {
        verify_that!(SpellIdx::try_from_usize(input), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::unit_below_max(65534, Some(UnitIdx(65534)))]
    #[case::unit_at_max_rejected(65535, None)]
    fn unit_try_from_usize(#[case] input: usize, #[case] expected: Option<UnitIdx>) -> Result<()> {
        verify_that!(UnitIdx::try_from_usize(input), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::resource_below_max(31, Some(ResourceIdx(31)))]
    #[case::resource_at_max_rejected(32, None)]
    fn resource_try_from_usize(
        #[case] input: usize,
        #[case] expected: Option<ResourceIdx>,
    ) -> Result<()> {
        verify_that!(ResourceIdx::try_from_usize(input), eq(expected))
    }

    #[gtest]
    fn from_usize_saturating_clamps() -> Result<()> {
        verify_that!(UnitIdx::from_usize_saturating(10), eq(UnitIdx(10)))?;
        verify_that!(
            UnitIdx::from_usize_saturating(usize::MAX),
            eq(UnitIdx(u16::MAX))
        )?;
        verify_that!(TargetIdx::from_usize_saturating(10), eq(TargetIdx(10)))?;

        verify_that!(
            TargetIdx::from_usize_saturating(usize::MAX),
            eq(TargetIdx(u16::MAX))
        )
    }

    #[gtest]
    fn snapshot_next_wraps() -> Result<()> {
        verify_that!(SnapshotIdx(1).next(), eq(SnapshotIdx(2)))?;

        verify_that!(SnapshotIdx(u32::MAX).next(), eq(SnapshotIdx(0)))
    }

    #[gtest]
    fn validity_and_role_predicates() -> Result<()> {
        verify_that!(SpellIdx(0).is_valid(), eq(false))?;
        verify_that!(SpellIdx(1).is_valid(), eq(true))?;
        verify_that!(UnitIdx::PLAYER.is_player(), eq(true))?;
        verify_that!(UnitIdx(1).is_player(), eq(false))?;
        verify_that!(TargetIdx::PRIMARY.is_primary(), eq(true))?;
        verify_that!(TargetIdx(1).is_primary(), eq(false))?;
        verify_that!(PetIdx::PRIMARY.is_primary(), eq(true))?;
        verify_that!(PetIdx(1).is_primary(), eq(false))?;
        verify_that!(EnemyIdx::PRIMARY.is_primary(), eq(true))?;
        verify_that!(EnemyIdx(1).is_primary(), eq(false))?;
        verify_that!(SnapshotIdx::INVALID.is_valid(), eq(false))?;

        verify_that!(SnapshotIdx(1).is_valid(), eq(true))
    }

    #[gtest]
    fn pet_to_unit_idx_offset() -> Result<()> {
        verify_that!(PetIdx(0).to_unit_idx(), eq(UnitIdx(1)))?;

        verify_that!(PetIdx(3).to_unit_idx(), eq(UnitIdx(4)))
    }

    #[gtest]
    fn guardian_slots_follow_the_reserved_primary_pet_identity() -> Result<()> {
        verify_that!(PetIdx::from_guardian_slot(0), eq(Some(PetIdx(1))))?;
        verify_that!(PetIdx::from_guardian_slot(254), eq(Some(PetIdx(255))))?;

        verify_that!(PetIdx::from_guardian_slot(255), eq(None))
    }

    #[gtest]
    fn enemy_to_target_idx_identity() -> Result<()> {
        verify_that!(EnemyIdx(2).to_target_idx(), eq(TargetIdx(2)))?;

        verify_that!(EnemyIdx(0).to_target_idx(), eq(TargetIdx(0)))
    }

    #[gtest]
    #[rstest]
    #[case::unit_player(format!("{:?}", UnitIdx(0)), "UnitIdx(PLAYER)")]
    #[case::unit_other(format!("{:?}", UnitIdx(2)), "UnitIdx(2)")]
    #[case::target_primary(format!("{:?}", TargetIdx(0)), "TargetIdx(PRIMARY)")]
    #[case::target_other(format!("{:?}", TargetIdx(1)), "TargetIdx(1)")]
    #[case::pet_primary(format!("{:?}", PetIdx(0)), "PetIdx(PRIMARY)")]
    #[case::pet_other(format!("{:?}", PetIdx(5)), "PetIdx(5)")]
    #[case::enemy_primary(format!("{:?}", EnemyIdx(0)), "EnemyIdx(PRIMARY)")]
    #[case::enemy_other(format!("{:?}", EnemyIdx(3)), "EnemyIdx(3)")]
    fn custom_debug_strings(#[case] actual: String, #[case] expected: &str) -> Result<()> {
        verify_that!(actual, eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::player(AuraOn::Player, "player")]
    #[case::target(AuraOn::Target, "target")]
    #[case::pet(AuraOn::Pet, "pet")]
    fn aura_on_display(#[case] on: AuraOn, #[case] expected: &str) -> Result<()> {
        verify_that!(format!("{on}"), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::player(AuraOn::Player)]
    #[case::target(AuraOn::Target)]
    #[case::pet(AuraOn::Pet)]
    fn aura_key_roundtrip(#[case] on: AuraOn) -> Result<()> {
        let k = AuraProjectionKey::new(AuraIdx(4242), on);

        verify_that!(k.aura(), eq(AuraIdx(4242)))?;

        verify_that!(k.on(), eq(on))
    }

    #[gtest]
    #[rstest]
    #[case::aura_zero(AuraIdx(0), AuraOn::Player)]
    #[case::aura_max(AuraIdx(u32::MAX), AuraOn::Pet)]
    fn aura_key_bit_isolation(#[case] aura: AuraIdx, #[case] on: AuraOn) -> Result<()> {
        let k = AuraProjectionKey::new(aura, on);

        verify_that!(k.aura(), eq(aura))?;

        verify_that!(k.on(), eq(on))
    }

    #[gtest]
    fn category_projection_is_not_an_exact_primary_target_key() -> Result<()> {
        let aura = AuraIdx(4242);
        let projection = AuraProjectionKey::new(aura, AuraOn::Target);
        let exact = AuraKey::new(
            aura,
            ActorId::Player,
            ActorId::Enemy(EnemyIdx::PRIMARY),
            AuraOn::Target,
        );

        verify_that!(projection.aura(), eq(exact.aura()))?;

        verify_that!(projection.on(), eq(exact.on()))
    }
}