wowlab_engine_ports/

encounter.rs

//! Data-resolved encounter proof consumed by combat construction.

use wowlab_engine_gamedata::ResolvedGameData;
use wowlab_types::sim::{
    EncounterDefinition, EnemyDefinition, EnemyHealthInput, EnemyIdentityInput, EnemyIdx,
    EnemyRole, GroupId, SpatialTransform,
};

use crate::EncounterConstructionError;

const SOURCE_RELATIVE_TOLERANCE: f64 = 1.0e-6;

/// Resolver-backed identity metadata for one enemy.
#[derive(Clone, Debug, Eq, PartialEq)]
// #t(rust_similar_structs) validated encounter-port identity is distinct from application inspection output
pub struct ResolvedEnemyIdentityMetadata {
    display_name: String,
    npc_id: Option<u32>,
    classification: Option<i32>,
    creature_type: Option<i32>,
}

impl ResolvedEnemyIdentityMetadata {
    /// Validates resolved identity metadata for an enemy.
    /// # Errors
    /// Returns an error when the display name is empty.
    pub fn new(
        enemy: EnemyIdx,
        display_name: String,
        npc_id: Option<u32>,
        classification: Option<i32>,
        creature_type: Option<i32>,
    ) -> Result<Self, EncounterConstructionError> {
        if display_name.is_empty() {
            return Err(EncounterConstructionError::empty_resolved_display_name(
                enemy,
            ));
        }

        Ok(Self {
            display_name,
            npc_id,
            classification,
            creature_type,
        })
    }
}

/// Resolver-backed combat stats required to construct one enemy actor.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ResolvedEnemyCombatStats {
    max_health: f64,
    armor: f64,
    armor_constant: f64,
    auto_attack_dps: Option<f64>,
    spell_damage: Option<f64>,
}

impl ResolvedEnemyCombatStats {
    /// Validates resolver-backed combat statistics for an enemy.
    /// # Errors
    /// Returns an error when a required statistic is non-finite or outside its valid range.
    pub fn new(
        enemy: EnemyIdx,
        max_health: f64,
        armor: f64,
        armor_constant: f64,
        auto_attack_dps: Option<f64>,
        spell_damage: Option<f64>,
    ) -> Result<Self, EncounterConstructionError> {
        validate_resolved_stat(enemy, "max health", max_health, true)?;
        validate_resolved_stat(enemy, "armor", armor, false)?;
        validate_resolved_stat(enemy, "armor constant", armor_constant, true)?;

        if let Some(value) = auto_attack_dps {
            validate_resolved_stat(enemy, "auto-attack DPS", value, false)?;
        }

        if let Some(value) = spell_damage {
            validate_resolved_stat(enemy, "spell damage", value, false)?;
        }

        Ok(Self {
            max_health,
            armor,
            armor_constant,
            auto_attack_dps,
            spell_damage,
        })
    }
}

/// Resolver-backed static stats and authored runtime metadata for one enemy.
#[derive(Clone, Debug, PartialEq)]
pub struct ResolvedEnemyEncounter {
    enemy: EnemyIdx,
    display_name: String,
    npc_id: Option<u32>,
    classification: Option<i32>,
    creature_type: Option<i32>,
    level: u16,
    health: EnemyHealthInput,
    max_health: f64,
    armor: f64,
    armor_constant: f64,
    auto_attack_dps: Option<f64>,
    spell_damage: Option<f64>,
    creature_aoe_avoidance_pct: f64,
    initial_transform: SpatialTransform,
    group_id: GroupId,
    enemy_tags: Vec<Box<str>>,
    group_tags: Vec<Box<str>>,
    role: EnemyRole,
    spawn_at_s: f64,
}

impl ResolvedEnemyEncounter {
    /// Assemble one enemy from an authored definition and resolver-produced values.
    /// # Errors
    /// Returns an error when resolved metadata disagrees with the authored enemy.
    pub fn new(
        authored: &EnemyDefinition,
        group_tags: &[String],
        resolved_level: u16,
        identity: ResolvedEnemyIdentityMetadata,
        stats: ResolvedEnemyCombatStats,
    ) -> Result<Self, EncounterConstructionError> {
        if authored.level != resolved_level {
            return Err(EncounterConstructionError::resolved_enemy_level_mismatch(
                authored.id,
                authored.level,
                resolved_level,
            ));
        }

        let authored_max_health = match authored.health {
            EnemyHealthInput::Auto => None,
            EnemyHealthInput::Fixed { max_health } => Some(max_health),
            EnemyHealthInput::ScriptedLinear {
                display_max_health, ..
            } => Some(display_max_health),
        };

        if let Some(expected) = authored_max_health {
            if expected.total_cmp(&stats.max_health) != std::cmp::Ordering::Equal {
                return Err(EncounterConstructionError::resolved_health_model_mismatch(
                    authored.id,
                    expected,
                    stats.max_health,
                ));
            }
        }

        Ok(Self {
            enemy: authored.id,
            display_name: identity.display_name,
            npc_id: identity.npc_id,
            classification: identity.classification,
            creature_type: identity.creature_type,
            level: authored.level,
            health: authored.health.clone(),
            max_health: stats.max_health,
            armor: stats.armor,
            armor_constant: stats.armor_constant,
            auto_attack_dps: stats.auto_attack_dps,
            spell_damage: stats.spell_damage,
            creature_aoe_avoidance_pct: authored.creature_aoe_avoidance_pct,
            initial_transform: authored.initial_transform,
            group_id: authored.group_id,
            enemy_tags: authored
                .tags
                .iter()
                .cloned()
                .map(String::into_boxed_str)
                .collect(),
            group_tags: group_tags
                .iter()
                .cloned()
                .map(String::into_boxed_str)
                .collect(),
            role: authored.role,
            spawn_at_s: authored.spawn_at_s,
        })
    }

    #[must_use]
    pub const fn enemy(&self) -> EnemyIdx {
        self.enemy
    }

    #[must_use]
    pub fn display_name(&self) -> &str {
        &self.display_name
    }

    #[must_use]
    pub const fn npc_id(&self) -> Option<u32> {
        self.npc_id
    }

    #[must_use]
    pub const fn classification(&self) -> Option<i32> {
        self.classification
    }

    #[must_use]
    pub const fn creature_type(&self) -> Option<i32> {
        self.creature_type
    }

    #[must_use]
    pub const fn level(&self) -> u16 {
        self.level
    }

    #[must_use]
    pub const fn health(&self) -> &EnemyHealthInput {
        &self.health
    }

    #[must_use]
    pub const fn max_health(&self) -> f64 {
        self.max_health
    }

    #[must_use]
    pub const fn creature_armor(&self) -> f64 {
        self.armor
    }

    #[must_use]
    pub const fn armor_constant(&self) -> f64 {
        self.armor_constant
    }

    #[must_use]
    pub const fn auto_attack_dps(&self) -> Option<f64> {
        self.auto_attack_dps
    }

    #[must_use]
    pub const fn spell_damage(&self) -> Option<f64> {
        self.spell_damage
    }

    #[must_use]
    pub const fn creature_aoe_avoidance_pct(&self) -> f64 {
        self.creature_aoe_avoidance_pct
    }

    #[must_use]
    pub const fn initial_transform(&self) -> SpatialTransform {
        self.initial_transform
    }

    #[must_use]
    pub const fn group_id(&self) -> GroupId {
        self.group_id
    }

    #[must_use]
    pub fn enemy_tags(&self) -> &[Box<str>] {
        &self.enemy_tags
    }

    #[must_use]
    pub fn group_tags(&self) -> &[Box<str>] {
        &self.group_tags
    }

    #[must_use]
    pub const fn role(&self) -> EnemyRole {
        self.role
    }

    #[must_use]
    pub const fn spawn_at_s(&self) -> f64 {
        self.spawn_at_s
    }
}

/// Validated, resolver-backed encounter accepted by the combat runtime.
#[derive(Clone, Debug)]
pub struct ResolvedEncounter {
    definition: EncounterDefinition,
    enemies: Vec<ResolvedEnemyEncounter>,
}

impl ResolvedEncounter {
    /// Validate and assemble a complete combat-ready encounter in immutable [`EnemyIdx`] order.
    /// # Errors
    /// Returns an error when the definition is invalid or resolved enemies do not correspond to it.
    pub fn new(
        definition: EncounterDefinition,
        enemies: Vec<ResolvedEnemyEncounter>,
    ) -> Result<Self, EncounterConstructionError> {
        definition.validate()?;

        if enemies.len() != definition.enemies.len() {
            return Err(EncounterConstructionError::resolved_enemy_count_mismatch(
                definition.enemies.len(),
                enemies.len(),
            ));
        }

        for (index, (authored, resolved)) in definition.enemies.iter().zip(&enemies).enumerate() {
            validate_resolved_enemy(&definition, index, authored, resolved)?;
        }

        Ok(Self {
            definition,
            enemies,
        })
    }

    #[must_use]
    pub const fn definition(&self) -> &EncounterDefinition {
        &self.definition
    }

    #[must_use]
    pub fn enemies(&self) -> &[ResolvedEnemyEncounter] {
        &self.enemies
    }

    #[must_use]
    pub fn enemy(&self, enemy: EnemyIdx) -> Option<&ResolvedEnemyEncounter> {
        self.enemies
            .get(enemy.as_usize())
            .filter(|resolved| resolved.enemy == enemy)
    }

    /// Returns the validated primary enemy.
    ///
    /// # Panics
    ///
    /// Panics only if this value was constructed in violation of [`Self::new`]'s invariants.
    #[must_use]
    pub fn primary_enemy(&self) -> &ResolvedEnemyEncounter {
        self.enemy(EnemyIdx::PRIMARY)
            .expect("resolved encounters always contain their validated primary enemy")
    }

    #[must_use]
    pub fn fight_duration_secs(&self) -> f64 {
        self.definition
            .fixed_duration_s
            .unwrap_or_else(|| wowlab_types::sim::SimTime::MAX.as_secs_f64())
    }

    pub(crate) fn validate_game_data(
        &self,
        game_data: &ResolvedGameData,
    ) -> Result<(), EncounterConstructionError> {
        let primary = self.primary_enemy();
        let enemy = primary.enemy();
        let expected_armor = primary.creature_armor();
        let combat_armor = game_data.creature_armor();

        if combat_armor.total_cmp(&expected_armor) != std::cmp::Ordering::Equal {
            return Err(EncounterConstructionError::combat_creature_armor_mismatch(
                enemy,
                expected_armor,
                combat_armor,
            ));
        }

        let armor_constant = game_data.armor_constant();

        if !armor_constant.is_finite() || armor_constant <= 0.0 {
            return Err(EncounterConstructionError::invalid_combat_armor_constant(
                enemy,
                armor_constant,
            ));
        }

        let armor_constant_mod = game_data.armor_constant_mod();

        if !armor_constant_mod.is_finite() || armor_constant_mod <= 0.0 {
            return Err(
                EncounterConstructionError::invalid_combat_armor_constant_mod(
                    enemy,
                    armor_constant_mod,
                ),
            );
        }

        let expected_k = primary.armor_constant();
        let combat_k = game_data.armor_k();

        if !combat_k.is_finite() || !relative_eq(combat_k, expected_k, SOURCE_RELATIVE_TOLERANCE) {
            return Err(
                EncounterConstructionError::combat_effective_armor_constant_mismatch(
                    enemy,
                    expected_k,
                    combat_k,
                    armor_constant,
                    armor_constant_mod,
                ),
            );
        }

        Ok(())
    }
}

fn validate_resolved_enemy(
    definition: &EncounterDefinition,
    index: usize,
    authored: &EnemyDefinition,
    resolved: &ResolvedEnemyEncounter,
) -> Result<(), EncounterConstructionError> {
    let expected_id = EnemyIdx(u16::try_from(index).map_err(|source| {
        EncounterConstructionError::resolved_enemy_index_out_of_range(index, source)
    })?);

    if authored.id != expected_id || resolved.enemy != expected_id {
        return Err(
            EncounterConstructionError::resolved_enemy_identity_mismatch(
                index,
                authored.id,
                resolved.enemy,
            ),
        );
    }

    if authored.level != resolved.level {
        return Err(EncounterConstructionError::resolved_enemy_level_mismatch(
            expected_id,
            authored.level,
            resolved.level,
        ));
    }

    validate_resolved_identity(authored, resolved)?;

    validate_resolved_metadata(definition, authored, resolved)
}

fn validate_resolved_identity(
    authored: &EnemyDefinition,
    resolved: &ResolvedEnemyEncounter,
) -> Result<(), EncounterConstructionError> {
    let matches = match &authored.identity {
        EnemyIdentityInput::Anonymous { display_name } => {
            resolved.npc_id.is_none() && resolved.display_name == *display_name
        }
        EnemyIdentityInput::Npc { npc_id } => resolved.npc_id == Some(*npc_id),
    };

    if matches {
        Ok(())
    } else {
        Err(EncounterConstructionError::resolved_enemy_identity_metadata_mismatch(authored.id))
    }
}

fn validate_resolved_metadata(
    definition: &EncounterDefinition,
    authored: &EnemyDefinition,
    resolved: &ResolvedEnemyEncounter,
) -> Result<(), EncounterConstructionError> {
    let spawn_matches =
        authored.spawn_at_s.total_cmp(&resolved.spawn_at_s) == std::cmp::Ordering::Equal;
    let metadata_matches = authored.health == resolved.health
        && authored.initial_transform == resolved.initial_transform
        && authored.group_id == resolved.group_id
        && authored
            .tags
            .iter()
            .map(String::as_str)
            .eq(resolved.enemy_tags.iter().map(Box::as_ref))
        && authored.role == resolved.role
        && spawn_matches;
    let group_matches = definition
        .groups
        .get(authored.group_id.0 as usize)
        .is_some_and(|group| {
            group
                .tags
                .iter()
                .map(String::as_str)
                .eq(resolved.group_tags.iter().map(Box::as_ref))
        });

    if metadata_matches && group_matches {
        Ok(())
    } else {
        Err(EncounterConstructionError::resolved_enemy_metadata_mismatch(authored.id))
    }
}

fn validate_resolved_stat(
    enemy: EnemyIdx,
    field: &'static str,
    value: f64,
    strictly_positive: bool,
) -> Result<(), EncounterConstructionError> {
    let valid = value.is_finite()
        && if strictly_positive {
            value > 0.0
        } else {
            value >= 0.0
        };

    if valid {
        Ok(())
    } else {
        Err(EncounterConstructionError::invalid_resolved_enemy_stat(
            enemy, field, value,
        ))
    }
}

fn relative_eq(found: f64, expected: f64, tolerance: f64) -> bool {
    (found - expected).abs() <= tolerance * found.abs().max(expected.abs())
}