wowlab_engine_domain/

targeting.rs

//! Resolved combat targeting vocabulary independent of encounter serialization.

use wowlab_types::sim::{EnemyIdx, GroupId, SpatialTransform};

mod overlay;
mod plan;
mod support;

pub use overlay::{
    TargetEffectCoordinate, TargetGeometryOverlay, TargetOverlayMetadata, TargetPlanOverlay,
    registered_target_geometry_overlay, registered_target_plan_overlay,
};
pub use plan::{
    TargetPlan, TargetPlanError, TargetPlanInput, TargetPlanOperation, TargetPlanOperations,
    TargetPlanProvenance, TargetSelector, compile_dbc_target_plan, compile_target_plan,
};
pub use support::{
    ExecutableCandidateDomain, ExecutableLocation, ExecutableLocationAlgorithm,
    ExecutableSelection, ExecutableTargetAlgorithm, ExecutableTargetDirection,
    ExecutableTargetFallback, ExecutableTargetOperation, ExecutableTargetOperations,
    ExecutableTargetPlan, ExecutableTargetReference, TargetPlanAxis, TargetPlanGap,
    lower_target_plan, target_plan_is_multi_target,
};

/// Shared deterministic single-target selectors.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) selector variants are the fixed Phase 6 contract
pub enum SingleTargetSelector {
    Current,
    Primary,
    Explicit(EnemyIdx),
    Nearest,
    Farthest,
    LowestHealth,
}

/// Spatial source used to choose every additional target after a chain's explicit first hit.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) chain origin variants are the exhaustive runtime algebra
pub enum ChainTargetOrigin {
    PreviousTarget,
    Source,
}

/// Eligibility filter applied before target-shape geometry.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct CandidateFilter {
    pub groups: Vec<GroupId>,
    pub tags: Vec<String>,
}

impl CandidateFilter {
    /// Match OR-group membership and every required tag against enemy and group tags.
    #[must_use]
    pub fn matches(
        &self,
        group: GroupId,
        enemy_tags: &[Box<str>],
        group_tags: &[Box<str>],
    ) -> bool {
        (self.groups.is_empty() || self.groups.contains(&group))
            && self.tags.iter().all(|required| {
                enemy_tags.iter().any(|tag| tag.as_ref() == required)
                    || group_tags.iter().any(|tag| tag.as_ref() == required)
            })
    }
}

/// Target shape after DBC/manifest semantics have been resolved.
#[derive(Clone, Debug, PartialEq)]
// #t(rust_non_exhaustive_on_public) shape variants are the fixed Phase 6 contract
pub enum ResolvedTargetShape {
    Single(SingleTargetSelector),
    RadiusFromSource {
        radius: f64,
    },
    RadiusFromTarget {
        anchor: SingleTargetSelector,
        radius: f64,
    },
    RadiusAtLocation {
        location: SpatialTransform,
        radius: f64,
    },
    Cone {
        range: f64,
        half_angle: f64,
        heading_offset: f64,
    },
    ConeFromTarget {
        anchor: SingleTargetSelector,
        range: f64,
        half_angle: f64,
        heading_offset: f64,
    },
    ConeAtLocation {
        location: SpatialTransform,
        range: f64,
        half_angle: f64,
        heading_offset: f64,
    },
    ConeTowardTarget {
        anchor: SingleTargetSelector,
        range: f64,
        half_angle: f64,
        heading_offset: f64,
    },
    Line {
        range: f64,
        half_width: f64,
        heading_offset: f64,
    },
    LineTowardTarget {
        anchor: SingleTargetSelector,
        range: f64,
        half_width: f64,
        heading_offset: f64,
    },
    LineAtLocation {
        location: SpatialTransform,
        range: f64,
        half_width: f64,
        heading_offset: f64,
    },
    Chain {
        anchor: SingleTargetSelector,
        origin: ChainTargetOrigin,
        jump_radius: f64,
        max_hits: u8,
    },
    Explicit(ExplicitTargets),
}

/// Validated explicit target identities in deterministic first-occurrence order.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ExplicitTargets(Vec<EnemyIdx>);

impl ExplicitTargets {
    /// Borrow the validated identities in their authored order.
    #[must_use]
    pub fn as_slice(&self) -> &[EnemyIdx] {
        &self.0
    }

    fn validate(&self, enemy_count: usize) -> Result<(), TargetShapeError> {
        validate_explicit_targets(self.0.iter().copied(), enemy_count)
    }
}

wowlab_engine_macros::define_error! {
/// Invalid resolved target-shape construction.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TargetShapeError {
    #[source]
    kind: TargetShapeErrorKind,
}

#[derive(Clone, Copy, Debug, thiserror::Error, Eq, PartialEq)]
enum TargetShapeErrorKind {
    #[error("explicit target {enemy:?} does not exist")]
    MissingExplicitEnemy { enemy: EnemyIdx },
    #[error(transparent)]
    InvalidTargetPlan(#[from] TargetPlanError),
    #[error(transparent)]
    UnsupportedTargetPlan(#[from] TargetPlanGap),
    #[error("target selector {selector:?} does not resolve hostile enemy identities")]
    NonHostileSelection { selector: TargetSelector },
    #[error("target plan requires an authored cast destination")]
    MissingCastDestination,
    #[error("directional target plan requires a spatial position for its {reference:?} reference")]
    MissingReferencePosition {
        reference: ExecutableTargetReference,
    },
    #[error("random target direction requires the simulation RNG")]
    MissingDirectionRng,
}
}

impl TargetShapeError {
    /// Reports an explicit enemy outside the encounter.
    #[must_use]
    pub const fn missing_explicit_enemy(enemy: EnemyIdx) -> Self {
        Self {
            kind: TargetShapeErrorKind::MissingExplicitEnemy { enemy },
        }
    }

    /// Reports a selector that does not produce hostile enemies.
    #[must_use]
    pub const fn non_hostile_selection(selector: TargetSelector) -> Self {
        Self {
            kind: TargetShapeErrorKind::NonHostileSelection { selector },
        }
    }

    /// Reports an absent authored cast destination.
    #[must_use]
    pub const fn missing_cast_destination() -> Self {
        Self {
            kind: TargetShapeErrorKind::MissingCastDestination,
        }
    }

    /// Reports an absent spatial position for a directional reference.
    #[must_use]
    pub const fn missing_reference_position(reference: ExecutableTargetReference) -> Self {
        Self {
            kind: TargetShapeErrorKind::MissingReferencePosition { reference },
        }
    }

    /// Reports random direction resolution without an RNG.
    #[must_use]
    pub const fn missing_direction_rng() -> Self {
        Self {
            kind: TargetShapeErrorKind::MissingDirectionRng,
        }
    }
}

impl From<TargetPlanError> for TargetShapeError {
    fn from(error: TargetPlanError) -> Self {
        Self {
            kind: TargetShapeErrorKind::InvalidTargetPlan(error),
        }
    }
}

impl From<TargetPlanGap> for TargetShapeError {
    fn from(error: TargetPlanGap) -> Self {
        Self {
            kind: TargetShapeErrorKind::UnsupportedTargetPlan(error),
        }
    }
}

impl ResolvedTargetShape {
    /// Validate explicit identities and deduplicate while preserving the first occurrence.
    ///
    /// # Errors
    ///
    /// Returns an error when any target lies outside the encounter.
    pub fn explicit(
        targets: impl IntoIterator<Item = EnemyIdx>,
        enemy_count: usize,
    ) -> Result<Self, TargetShapeError> {
        let resolved = deduplicate_explicit_targets(targets, enemy_count)?;

        Ok(Self::Explicit(ExplicitTargets(resolved)))
    }

    /// Borrow explicit identities when this is an explicit shape.
    #[must_use]
    pub fn explicit_targets(&self) -> Option<&[EnemyIdx]> {
        match self {
            Self::Explicit(targets) => Some(targets.as_slice()),
            _ => None,
        }
    }

    /// Revalidate target identities against the encounter that will consume this shape.
    ///
    /// # Errors
    ///
    /// Returns an error when any referenced target lies outside the encounter.
    pub fn validate(&self, enemy_count: usize) -> Result<(), TargetShapeError> {
        match self {
            Self::Single(selector) => validate_selector(*selector, enemy_count),
            Self::RadiusFromTarget { anchor, .. }
            | Self::ConeFromTarget { anchor, .. }
            | Self::ConeTowardTarget { anchor, .. }
            | Self::LineTowardTarget { anchor, .. }
            | Self::Chain { anchor, .. } => validate_selector(*anchor, enemy_count),
            Self::Explicit(targets) => targets.validate(enemy_count),
            Self::RadiusFromSource { .. }
            | Self::RadiusAtLocation { .. }
            | Self::Cone { .. }
            | Self::ConeAtLocation { .. }
            | Self::Line { .. }
            | Self::LineAtLocation { .. } => Ok(()),
        }
    }
}

fn validate_selector(
    selector: SingleTargetSelector,
    enemy_count: usize,
) -> Result<(), TargetShapeError> {
    if let SingleTargetSelector::Explicit(enemy) = selector {
        validate_explicit_targets([enemy], enemy_count)?;
    }

    Ok(())
}

fn validate_explicit_targets(
    targets: impl IntoIterator<Item = EnemyIdx>,
    enemy_count: usize,
) -> Result<(), TargetShapeError> {
    for enemy in targets {
        if enemy.as_usize() >= enemy_count {
            return Err(TargetShapeError::missing_explicit_enemy(enemy));
        }
    }

    Ok(())
}

fn deduplicate_explicit_targets(
    targets: impl IntoIterator<Item = EnemyIdx>,
    enemy_count: usize,
) -> Result<Vec<EnemyIdx>, TargetShapeError> {
    let mut resolved = Vec::new();

    for enemy in targets {
        validate_explicit_targets([enemy], enemy_count)?;

        if !resolved.contains(&enemy) {
            resolved.push(enemy);
        }
    }

    Ok(resolved)
}

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

    use super::*;

    #[gtest]
    fn candidate_filter_uses_or_groups_and_all_tags_from_union() {
        let filter = CandidateFilter {
            groups: vec![GroupId(1), GroupId(3)],
            tags: vec!["caster".into(), "priority".into()],
        };

        expect_that!(
            filter.matches(GroupId(3), &["caster".into()], &["priority".into()]),
            is_true()
        );
        expect_that!(
            !filter.matches(GroupId(2), &["caster".into()], &["priority".into()]),
            is_true()
        );
        expect_that!(
            !filter.matches(GroupId(3), &["caster".into()], &[]),
            is_true()
        );
    }

    #[gtest]
    fn explicit_shape_deduplicates_in_first_occurrence_order() {
        let shape =
            ResolvedTargetShape::explicit([EnemyIdx(2), EnemyIdx(1), EnemyIdx(2), EnemyIdx(0)], 3)
                .expect("valid explicit identities");

        expect_that!(
            shape.explicit_targets(),
            eq(Some(&[EnemyIdx(2), EnemyIdx(1), EnemyIdx(0)][..]))
        );
        expect_that!(
            ResolvedTargetShape::explicit([EnemyIdx(3)], 3),
            eq(&Err(TargetShapeError {
                kind: TargetShapeErrorKind::MissingExplicitEnemy { enemy: EnemyIdx(3) }
            }))
        );
    }
}