wowlab_engine_domain/targeting/

plan.rs

//! Compilation of DBC TargetA/TargetB into an ordered, compositional target program.

use super::{TargetPlanOverlay, registered_target_plan_overlay};
use crate::dbc::{
    ImplicitTargetCheck, ImplicitTargetDirection, ImplicitTargetObject, ImplicitTargetReference,
    ImplicitTargetSelection, SpellEffectTargetSemantic, implicit_target_semantic,
    spell_effect_target_semantic,
};

const TARGET_OPERATION_SLOTS: usize = 2;

/// One selector with `TrinityCore`'s five axes kept independent.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TargetSelector {
    pub raw: Option<i32>,
    pub object: ImplicitTargetObject,
    pub reference: ImplicitTargetReference,
    pub algorithm: ImplicitTargetSelection,
    pub check: ImplicitTargetCheck,
    pub direction: ImplicitTargetDirection,
}

impl TargetSelector {
    #[must_use]
    pub const fn custom(
        object: ImplicitTargetObject,
        reference: ImplicitTargetReference,
        algorithm: ImplicitTargetSelection,
        check: ImplicitTargetCheck,
        direction: ImplicitTargetDirection,
    ) -> Self {
        Self {
            raw: None,
            object,
            reference,
            algorithm,
            check,
            direction,
        }
    }
}

/// Ordered operation emitted by one implicit-target selector.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum TargetPlanOperation {
    AssignSource(TargetSelector),
    AssignDestination(TargetSelector),
    Select(TargetSelector),
    SelectAndAssignDestination(TargetSelector),
}

/// TargetA/TargetB operations in authored order without allocation.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct TargetPlanOperations {
    first: Option<TargetPlanOperation>,
    second: Option<TargetPlanOperation>,
}

impl TargetPlanOperations {
    /// Creates an empty target-operation sequence.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            first: None,
            second: None,
        }
    }

    #[must_use]
    pub const fn one(operation: TargetPlanOperation) -> Self {
        Self {
            first: Some(operation),
            second: None,
        }
    }

    #[must_use]
    pub const fn two(first: TargetPlanOperation, second: TargetPlanOperation) -> Self {
        Self {
            first: Some(first),
            second: Some(second),
        }
    }

    #[must_use]
    pub const fn into_array(self) -> [Option<TargetPlanOperation>; TARGET_OPERATION_SLOTS] {
        [self.first, self.second]
    }

    fn push(&mut self, operation: TargetPlanOperation) -> Result<(), TargetPlanError> {
        if self.first.is_none() {
            self.first = Some(operation);

            return Ok(());
        }

        if self.second.is_none() {
            self.second = Some(operation);

            return Ok(());
        }

        Err(TargetPlanError::too_many_operations())
    }
}

/// Origin of the final program used by both runtime behavior and Forge conformance.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum TargetPlanProvenance {
    Dbc {
        target_a: i32,
        target_b: i32,
    },
    Overlay {
        name: &'static str,
        reason: &'static str,
    },
}

/// Ordered target program plus the effect-kind fallback Trinity applies when it selects nothing.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TargetPlan {
    pub operations: TargetPlanOperations,
    pub fallback: SpellEffectTargetSemantic,
    pub provenance: TargetPlanProvenance,
}

/// Spell-effect coordinate and its DBC inputs.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TargetPlanInput {
    pub spell_id: u32,
    pub effect_index: u8,
    pub effect_type: i32,
    pub target_a: i32,
    pub target_b: i32,
}

wowlab_engine_macros::define_error! {
/// Failure to compile canonical data or find one unambiguous content overlay.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TargetPlanError {
    kind: TargetPlanErrorKind,
}

#[derive(Clone, Copy, Debug, thiserror::Error, Eq, PartialEq)]
enum TargetPlanErrorKind {
    #[error("implicit target selector {selector} is outside the canonical TrinityCore table")]
    UnknownSelector { selector: i32 },
    #[error("spell effect kind {effect_type} is outside the canonical TrinityCore table")]
    UnknownEffectType { effect_type: i32 },
    #[error("target plan contains more operations than TargetA and TargetB can encode")]
    TooManyOperations,
    #[error("spell {spell_id} effect {effect_index} has multiple target-plan overlays")]
    DuplicateOverlay { spell_id: u32, effect_index: u8 },
    #[error("spell {spell_id} effect {effect_index} has multiple target-geometry overlays")]
    DuplicateGeometryOverlay { spell_id: u32, effect_index: u8 },
}
}

impl TargetPlanError {
    const fn new(kind: TargetPlanErrorKind) -> Self {
        Self { kind }
    }

    const fn unknown_selector(selector: i32) -> Self {
        Self::new(TargetPlanErrorKind::UnknownSelector { selector })
    }

    const fn unknown_effect_type(effect_type: i32) -> Self {
        Self::new(TargetPlanErrorKind::UnknownEffectType { effect_type })
    }

    const fn too_many_operations() -> Self {
        Self::new(TargetPlanErrorKind::TooManyOperations)
    }

    pub(super) const fn duplicate_overlay(spell_id: u32, effect_index: u8) -> Self {
        Self::new(TargetPlanErrorKind::DuplicateOverlay {
            spell_id,
            effect_index,
        })
    }

    pub(super) const fn duplicate_geometry_overlay(spell_id: u32, effect_index: u8) -> Self {
        Self::new(TargetPlanErrorKind::DuplicateGeometryOverlay {
            spell_id,
            effect_index,
        })
    }
}

/// Compile DBC selectors, applying the unique content overlay registered for this effect.
///
/// # Errors
///
/// Returns an error for duplicate overlays or unsupported DBC target semantics.
pub fn compile_target_plan(input: TargetPlanInput) -> Result<TargetPlan, TargetPlanError> {
    let overlay = registered_target_plan_overlay(input.spell_id, input.effect_index)?;

    compile_target_plan_with_overlay(input, overlay)
}

fn compile_target_plan_with_overlay(
    input: TargetPlanInput,
    overlay: Option<&TargetPlanOverlay>,
) -> Result<TargetPlan, TargetPlanError> {
    let fallback = spell_effect_target_semantic(input.effect_type)
        .ok_or_else(|| TargetPlanError::unknown_effect_type(input.effect_type))?;

    if let Some(overlay) = overlay {
        return Ok(TargetPlan {
            operations: overlay.operations,
            fallback,
            provenance: TargetPlanProvenance::Overlay {
                name: overlay.name,
                reason: overlay.reason,
            },
        });
    }

    compile_dbc_target_plan(input.effect_type, input.target_a, input.target_b)
}

/// Translate TargetA/TargetB into operations without deciding which axes the runtime supports.
///
/// # Errors
///
/// Returns an error when an effect type or implicit target selector is unknown.
pub fn compile_dbc_target_plan(
    effect_type: i32,
    target_a: i32,
    target_b: i32,
) -> Result<TargetPlan, TargetPlanError> {
    let fallback = spell_effect_target_semantic(effect_type)
        .ok_or_else(|| TargetPlanError::unknown_effect_type(effect_type))?;
    let mut operations = TargetPlanOperations::default();

    for raw in [target_a, target_b] {
        if raw == 0 {
            continue;
        }

        let semantic =
            implicit_target_semantic(raw).ok_or_else(|| TargetPlanError::unknown_selector(raw))?;
        let selector = TargetSelector {
            raw: Some(raw),
            object: semantic.object,
            reference: semantic.reference,
            algorithm: semantic.selection,
            check: semantic.check,
            direction: semantic.direction,
        };

        operations.push(operation_for(selector))?;
    }

    Ok(TargetPlan {
        operations,
        fallback,
        provenance: TargetPlanProvenance::Dbc { target_a, target_b },
    })
}

const fn operation_for(selector: TargetSelector) -> TargetPlanOperation {
    match selector.object {
        ImplicitTargetObject::Source => TargetPlanOperation::AssignSource(selector),
        ImplicitTargetObject::Destination => TargetPlanOperation::AssignDestination(selector),
        ImplicitTargetObject::UnitAndDestination => {
            TargetPlanOperation::SelectAndAssignDestination(selector)
        }
        _ => TargetPlanOperation::Select(selector),
    }
}

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

    use super::*;

    fn operations(plan: TargetPlan) -> Vec<TargetPlanOperation> {
        plan.operations.into_array().into_iter().flatten().collect()
    }

    const fn selector(operation: TargetPlanOperation) -> TargetSelector {
        match operation {
            TargetPlanOperation::AssignSource(selector)
            | TargetPlanOperation::AssignDestination(selector)
            | TargetPlanOperation::Select(selector)
            | TargetPlanOperation::SelectAndAssignDestination(selector) => selector,
        }
    }

    #[gtest]
    #[rstest]
    #[case::blade_flurry(
        18,
        16,
        ImplicitTargetReference::Caster,
        ImplicitTargetReference::Destination
    )]
    #[case::blade_rush(
        53,
        16,
        ImplicitTargetReference::Target,
        ImplicitTargetReference::Destination
    )]
    fn ordered_location_assignment_and_selection_remain_separate(
        #[case] target_a: i32,
        #[case] target_b: i32,
        #[case] assignment_reference: ImplicitTargetReference,
        #[case] selection_reference: ImplicitTargetReference,
    ) {
        let plan = compile_dbc_target_plan(2, target_a, target_b).expect("known DBC program");
        let operations = operations(plan);

        expect_that!(
            matches!(
                operations[0],
                TargetPlanOperation::AssignDestination(selector)
                    if selector.reference == assignment_reference
            ),
            is_true()
        );
        expect_that!(
            matches!(
                operations[1],
                TargetPlanOperation::Select(selector)
                    if selector.reference == selection_reference
                        && selector.algorithm == ImplicitTargetSelection::Area
                        && selector.check == ImplicitTargetCheck::Enemy
            ),
            is_true()
        );
    }

    #[gtest]
    #[rstest]
    #[case::raid_target(57, ImplicitTargetCheck::Raid)]
    #[case::line_target(134, ImplicitTargetCheck::Enemy)]
    #[case::trajectory_target(89, ImplicitTargetCheck::Default)]
    fn unsupported_axes_are_preserved_instead_of_rejected_during_compilation(
        #[case] raw: i32,
        #[case] check: ImplicitTargetCheck,
    ) {
        let plan = compile_dbc_target_plan(2, raw, 0).expect("known selector compiles to IR");
        let selector = selector(operations(plan)[0]);

        expect_that!(selector.raw, eq(Some(raw)));
        expect_that!(selector.check, eq(check));
    }

    #[gtest]
    fn overlay_replaces_operations_without_erasing_effect_fallback() {
        let selector = TargetSelector::custom(
            ImplicitTargetObject::Unit,
            ImplicitTargetReference::Caster,
            ImplicitTargetSelection::Area,
            ImplicitTargetCheck::Enemy,
            ImplicitTargetDirection::None,
        );
        let overlay = TargetPlanOverlay::new(
            crate::targeting::TargetEffectCoordinate {
                spell_id: 77,
                effect_index: 1,
            },
            crate::targeting::TargetOverlayMetadata {
                name: "custom path",
                reason: "the server spell omits its impact selection",
            },
            TargetPlanOperations::one(TargetPlanOperation::Select(selector)),
        );
        let plan = compile_target_plan_with_overlay(overlay.input(2, 134, 0), Some(&overlay))
            .expect("overlay provides complete operations");

        expect_that!(plan.operations, eq(overlay.operations));
        expect_that!(plan.fallback, eq(spell_effect_target_semantic(2).unwrap()));
        expect_that!(
            matches!(
                plan.provenance,
                TargetPlanProvenance::Overlay {
                    name: "custom path",
                    ..
                }
            ),
            is_true()
        );
    }
}