wowlab_engine_combat/state/program/

buffer_bindings.rs

//! Finalized combat identities bound to construction-validated buffer handles.

use wowlab_engine_domain::rotation::{
    AuraSlotHandle, BufferRequirements, ContextSchema, CooldownSlotHandle, HistorySlotHandle,
    ItemSlotHandle, ResourceSlotHandle, SpellSlotHandle, SwingSlotHandle, TalentSlotHandle,
    UnitSlotHandle, WeaponImbueSlotHandle,
};
use wowlab_types::{
    combat::ResourceType,
    sim::{ActorId, AuraKey, AuraOn, PetIdx, SpellIdx},
};

use crate::{
    builder::draft::DraftDefinitions,
    keys::UnitKey,
    state::{LocalAuraIdx, LocalSpellIdx},
};

#[derive(Debug, thiserror::Error)]
pub(crate) enum BufferBindingError {
    #[error("missing frozen {kind} binding for spell {spell_id}")]
    MissingSpell { kind: &'static str, spell_id: u32 },
    #[error("missing frozen swing binding at local index {index}")]
    MissingSwing { index: usize },
    #[error("missing frozen target-unit binding")]
    MissingTargetUnit,
    #[error("missing frozen resource binding for {resource}")]
    MissingResource { resource: ResourceType },
    #[error("missing frozen talent binding for {name}")]
    MissingTalent { name: Box<str> },
    #[error("missing frozen item binding for {key}")]
    MissingItem { key: Box<str> },
    #[error("missing frozen weapon-imbue binding for {key}")]
    MissingWeaponImbue { key: Box<str> },
    #[error("frozen aura {aura_id} ({on:?}) has no finalized local identity")]
    MissingAuraIdentity { aura_id: u32, on: AuraOn },
    #[error("finalized aura count {count} exceeds the local identity range")]
    AuraIdentityOverflow { count: usize },
    #[error("unsupported finalized concrete aura binding {key:?}")]
    UnsupportedAuraBinding { key: AuraKey },
    #[error("duplicate finalized concrete aura binding coordinate for {key:?}")]
    DuplicateAuraBinding { key: AuraKey },
}

/// One fully finalized concrete aura identity.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct ConcreteAuraBinding {
    pub(crate) local: LocalAuraIdx,
    pub(crate) key: AuraKey,
    pub(crate) handle: AuraSlotHandle,
    index: ConcreteAuraBindingIdx,
}

/// Stable finalized identity for one concrete aura binding.
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub(crate) struct ConcreteAuraBindingIdx(usize);

impl ConcreteAuraBindingIdx {
    #[expect(
        clippy::trivially_copy_pass_by_ref,
        reason = "C-CONV requires borrowed as_ receivers"
    )]
    pub(crate) const fn as_usize(&self) -> usize {
        self.0
    }
}

#[derive(Debug)]
pub(crate) struct BufferBindings {
    spells: Box<[SpellSlotHandle]>,
    cooldowns: Box<[CooldownSlotHandle]>,
    history: Box<[HistorySlotHandle]>,
    auras: Box<[ConcreteAuraBinding]>,
    aura_coordinates: Box<[Option<ConcreteAuraBinding>]>,
    aura_shape_len: usize,
    enemy_count: usize,
    aura_ons: Box<[AuraOn]>,
    resources: Box<[(ResourceType, ResourceSlotHandle)]>,
    talents: Box<[(Box<str>, TalentSlotHandle)]>,
    items: Box<[(Box<str>, ItemSlotHandle)]>,
    swings: Box<[SwingSlotHandle]>,
    weapon_imbues: Box<[(Box<str>, WeaponImbueSlotHandle)]>,
    target_unit: UnitSlotHandle,
}

impl BufferBindings {
    // #t(fn: rust_max_fn_lines) binding every frozen slot family is one construction-validated finalization transaction.
    // #t(fn: rust_cyclomatic_complexity) each branch binds one required frozen slot family and returns its precise construction error.
    pub(crate) fn build(
        schema: &ContextSchema,
        requirements: &BufferRequirements,
        definitions: &DraftDefinitions,
        talent_ranks: &[(String, u8)],
        initial_weapon_imbues: &[(&'static str, bool)],
    ) -> Result<Self, BufferBindingError> {
        let finalizer = schema.buffer_finalizer();
        let mut spells = Vec::with_capacity(definitions.spells.len());
        let mut cooldowns = Vec::with_capacity(definitions.spells.len());
        let mut history = Vec::with_capacity(definitions.spells.len());

        for spell in &definitions.spells {
            let key = SpellIdx::from_raw(spell.spell_id);

            let missing = |kind| BufferBindingError::MissingSpell {
                kind,
                spell_id: spell.spell_id,
            };

            spells.push(finalizer.bind_spell(key).ok_or_else(|| missing("spell"))?);
            cooldowns.push(
                finalizer
                    .bind_cooldown(key)
                    .ok_or_else(|| missing("cooldown"))?,
            );
            history.push(
                finalizer
                    .bind_history(key)
                    .ok_or_else(|| missing("history"))?,
            );
        }

        let aura_shape_len = aura_shape_len(definitions.enemies.len());
        let aura_ons: Box<[_]> = definitions.auras.iter().map(|aura| aura.on).collect();
        let mut auras = Vec::with_capacity(requirements.aura_keys().len());
        let mut aura_coordinates =
            vec![None; definitions.auras.len() * aura_shape_len * AURA_FAMILY_COUNT];

        for &key in requirements.aura_keys() {
            let handle = finalizer
                .bind_aura(key)
                .ok_or(BufferBindingError::UnsupportedAuraBinding { key })?;
            let raw = definitions
                .auras
                .iter()
                .position(|aura| aura.aura_id == key.aura().as_u32())
                .ok_or(BufferBindingError::MissingAuraIdentity {
                    aura_id: key.aura().as_u32(),
                    on: key.on(),
                })?;
            let Ok(raw) = u8::try_from(raw) else {
                return Err(BufferBindingError::AuraIdentityOverflow {
                    count: definitions.auras.len(),
                });
            };
            let local = LocalAuraIdx::new(raw);
            let definition_on = aura_ons.get(local.as_usize()).copied().ok_or(
                BufferBindingError::MissingAuraIdentity {
                    aura_id: key.aura().as_u32(),
                    on: key.on(),
                },
            )?;
            let binding = ConcreteAuraBinding {
                local,
                key,
                handle,
                index: ConcreteAuraBindingIdx(auras.len()),
            };
            let coordinate = aura_coordinate(
                local,
                key,
                definition_on,
                definitions.enemies.len(),
                aura_shape_len,
            )
            .ok_or(BufferBindingError::UnsupportedAuraBinding { key })?;
            let entry = aura_coordinates
                .get_mut(coordinate)
                .ok_or(BufferBindingError::UnsupportedAuraBinding { key })?;

            if entry.is_some() {
                return Err(BufferBindingError::DuplicateAuraBinding { key });
            }

            *entry = Some(binding);
            auras.push(binding);
        }

        let mut resources: Vec<_> = requirements
            .resource_keys()
            .iter()
            .map(|&resource| {
                finalizer
                    .bind_resource(resource)
                    .map(|handle| (resource, handle))
                    .ok_or(BufferBindingError::MissingResource { resource })
            })
            .collect::<Result<_, _>>()?;

        resources.sort_unstable_by_key(|(resource, _)| u8::from(*resource));
        let mut talents: Vec<_> = talent_ranks
            .iter()
            .map(|(name, _)| {
                finalizer
                    .bind_talent(name)
                    .map(|handle| (Box::<str>::from(name.as_str()), handle))
                    .ok_or_else(|| BufferBindingError::MissingTalent {
                        name: Box::from(name.as_str()),
                    })
            })
            .collect::<Result<_, _>>()?;

        talents.sort_unstable_by(|(left, _), (right, _)| left.cmp(right));
        let mut items: Vec<_> = definitions
            .item_use_spells
            .iter()
            .map(|(slot, _)| {
                let key = slot.slug();

                finalizer
                    .bind_item(key)
                    .map(|handle| (Box::<str>::from(key), handle))
                    .ok_or_else(|| BufferBindingError::MissingItem {
                        key: Box::from(key),
                    })
            })
            .collect::<Result<_, _>>()?;

        items.sort_unstable_by(|(left, _), (right, _)| left.cmp(right));
        let swings = (0..definitions.auto_attacks.len())
            .map(|index| {
                let key = crate::keys::auto_attack_key(index);

                finalizer
                    .bind_swing(&key)
                    .ok_or(BufferBindingError::MissingSwing { index })
            })
            .collect::<Result<Vec<_>, _>>()?;
        let mut weapon_imbues: Vec<_> = initial_weapon_imbues
            .iter()
            .map(|(key, _)| {
                finalizer
                    .bind_weapon_imbue(key)
                    .map(|handle| (Box::<str>::from(*key), handle))
                    .ok_or_else(|| BufferBindingError::MissingWeaponImbue {
                        key: Box::from(*key),
                    })
            })
            .collect::<Result<_, _>>()?;

        weapon_imbues.sort_unstable_by(|(left, _), (right, _)| left.cmp(right));
        let target_unit = finalizer
            .bind_unit(UnitKey::TARGET)
            .ok_or(BufferBindingError::MissingTargetUnit)?;

        Ok(Self {
            spells: spells.into_boxed_slice(),
            cooldowns: cooldowns.into_boxed_slice(),
            history: history.into_boxed_slice(),
            auras: auras.into_boxed_slice(),
            aura_coordinates: aura_coordinates.into_boxed_slice(),
            aura_shape_len,
            enemy_count: definitions.enemies.len(),
            aura_ons,
            resources: resources.into_boxed_slice(),
            talents: talents.into_boxed_slice(),
            items: items.into_boxed_slice(),
            swings: swings.into_boxed_slice(),
            weapon_imbues: weapon_imbues.into_boxed_slice(),
            target_unit,
        })
    }

    pub(crate) fn spell(&self, local: LocalSpellIdx) -> SpellSlotHandle {
        // BOUNDS: local spell indices are constructed from the definitions used to build this array.
        self.spells[local.as_usize()]
    }

    pub(crate) fn cooldown(&self, local: LocalSpellIdx) -> CooldownSlotHandle {
        // BOUNDS: local spell indices are constructed from the definitions used to build this array.
        self.cooldowns[local.as_usize()]
    }

    pub(crate) fn history(&self, local: LocalSpellIdx) -> HistorySlotHandle {
        // BOUNDS: local spell indices are constructed from the definitions used to build this array.
        self.history[local.as_usize()]
    }

    pub(crate) fn aura(&self, local: LocalAuraIdx, key: AuraKey) -> Option<ConcreteAuraBinding> {
        let on = *self.aura_ons.get(local.as_usize())?;
        let coordinate = aura_coordinate(local, key, on, self.enemy_count, self.aura_shape_len)?;
        let binding = self.aura_coordinates.get(coordinate).copied().flatten();

        #[cfg(not(feature = "rotation-optimizations"))]
        return binding.filter(|binding| binding.local == local && binding.key == key);

        #[cfg(feature = "rotation-optimizations")]
        binding
    }

    pub(crate) fn aura_bindings(&self) -> impl Iterator<Item = ConcreteAuraBinding> + '_ {
        self.auras.iter().copied()
    }

    pub(crate) const fn aura_binding_count(&self) -> usize {
        self.auras.len()
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) const fn aura_local_count(&self) -> usize {
        self.aura_ons.len()
    }

    pub(crate) fn resource(&self, key: ResourceType) -> Option<ResourceSlotHandle> {
        self.resources
            .binary_search_by_key(&u8::from(key), |(candidate, _)| u8::from(*candidate))
            .ok()
            // BOUNDS: successful binary search returns an index into this exact slice.
            .map(|index| self.resources[index].1)
    }

    pub(crate) fn talent(&self, key: &str) -> Option<TalentSlotHandle> {
        self.talents
            .binary_search_by(|(candidate, _)| candidate.as_ref().cmp(key))
            .ok()
            // BOUNDS: successful binary search returns an index into this exact slice.
            .map(|index| self.talents[index].1)
    }

    pub(crate) fn item(&self, key: &str) -> Option<ItemSlotHandle> {
        self.items
            .binary_search_by(|(candidate, _)| candidate.as_ref().cmp(key))
            .ok()
            // BOUNDS: successful binary search returns an index into this exact slice.
            .map(|index| self.items[index].1)
    }

    pub(crate) fn swing(&self, index: usize) -> Option<SwingSlotHandle> {
        self.swings.get(index).copied()
    }

    pub(crate) fn weapon_imbue(&self, key: &str) -> Option<WeaponImbueSlotHandle> {
        self.weapon_imbues
            .binary_search_by(|(candidate, _)| candidate.as_ref().cmp(key))
            .ok()
            // BOUNDS: successful binary search returns an index into this exact slice.
            .map(|index| self.weapon_imbues[index].1)
    }

    pub(crate) const fn target_unit(&self) -> UnitSlotHandle {
        self.target_unit
    }
}

#[cfg(test)]
#[path = "buffer_bindings/tests.rs"]
mod tests;

impl ConcreteAuraBinding {
    pub(crate) const fn index(self) -> ConcreteAuraBindingIdx {
        self.index
    }
}

const NON_PET_ACTOR_COUNT: usize = 2;
const PET_ACTOR_START: usize = NON_PET_ACTOR_COUNT;
const AURA_FAMILY_COUNT: usize = 3;
const PET_SOURCE_AFFECTED_COUNT: usize = 3;
const PLAYER_COORDINATE: usize = 0;
const EXTERNAL_COORDINATE: usize = 1;
const PRIMARY_PET_COORDINATE: usize = 1;
const SELF_PET_COORDINATE: usize = 2;
const PET_ENEMY_COORDINATE_START: usize = PET_SOURCE_AFFECTED_COUNT;
const DEFINITION_AURA_FAMILY: usize = 0;
const PLAYER_AURA_FAMILY: usize = 1;
const PET_AURA_FAMILY: usize = 2;

const fn aura_shape_len(enemy_count: usize) -> usize {
    let actor_count = NON_PET_ACTOR_COUNT + PetIdx::MAX + enemy_count;

    (NON_PET_ACTOR_COUNT + enemy_count) * actor_count
        + PetIdx::MAX * (PET_SOURCE_AFFECTED_COUNT + enemy_count)
}

fn actor_coordinate(actor: ActorId, enemy_count: usize) -> Option<usize> {
    match actor {
        ActorId::Player => Some(PLAYER_COORDINATE),
        ActorId::External => Some(EXTERNAL_COORDINATE),
        ActorId::Pet(pet) => {
            (pet.as_usize() < PetIdx::MAX).then_some(PET_ACTOR_START + pet.as_usize())
        }
        ActorId::Enemy(enemy) => (enemy.as_usize() < enemy_count)
            .then_some(PET_ACTOR_START + PetIdx::MAX + enemy.as_usize()),
    }
}

fn aura_shape_coordinate(key: AuraKey, enemy_count: usize) -> Option<usize> {
    let actor_count = NON_PET_ACTOR_COUNT + PetIdx::MAX + enemy_count;

    match key.source() {
        ActorId::Player => actor_coordinate(key.affected(), enemy_count),
        ActorId::External => {
            actor_coordinate(key.affected(), enemy_count).map(|index| actor_count + index)
        }
        ActorId::Enemy(enemy) if enemy.as_usize() < enemy_count => {
            actor_coordinate(key.affected(), enemy_count)
                .map(|index| (NON_PET_ACTOR_COUNT + enemy.as_usize()) * actor_count + index)
        }
        ActorId::Pet(pet) if pet.as_usize() < PetIdx::MAX => {
            let affected = match key.affected() {
                ActorId::Player => PLAYER_COORDINATE,
                ActorId::Pet(affected) if affected == PetIdx::PRIMARY => PRIMARY_PET_COORDINATE,
                ActorId::Pet(affected) if affected == pet => SELF_PET_COORDINATE,
                ActorId::Enemy(enemy) if enemy.as_usize() < enemy_count => {
                    PET_ENEMY_COORDINATE_START + enemy.as_usize()
                }
                ActorId::External | ActorId::Pet(_) | ActorId::Enemy(_) => return None,
            };
            let non_pet_len = (NON_PET_ACTOR_COUNT + enemy_count) * actor_count;

            Some(
                non_pet_len + pet.as_usize() * (PET_SOURCE_AFFECTED_COUNT + enemy_count) + affected,
            )
        }
        ActorId::Enemy(_) | ActorId::Pet(_) => None,
    }
}

fn aura_coordinate(
    local: LocalAuraIdx,
    key: AuraKey,
    definition_on: AuraOn,
    enemy_count: usize,
    shape_len: usize,
) -> Option<usize> {
    let family = if key.on() == definition_on {
        DEFINITION_AURA_FAMILY
    } else if key.on() == AuraOn::Player {
        PLAYER_AURA_FAMILY
    } else if key.on() == AuraOn::Pet && definition_on != AuraOn::Pet {
        PET_AURA_FAMILY
    } else {
        return None;
    };
    let shape = aura_shape_coordinate(key, enemy_count)?;

    Some((local.as_usize() * AURA_FAMILY_COUNT + family) * shape_len + shape)
}