overlord_event_system/behaviors/

fast_equip.rs

//! Native functions for the `ability_ids` category (`run_abilities_ids_script`).
//!
//! Both fns here answer the same question — "which of the things I own should
//! quick-equip put in my slots?" — and both answer it the same way: **rarity
//! first, then the system's own power metric inside a rarity band**, take the
//! top `Slots`. The metric itself is already native
//! ([`crate::mechanics::balance::ability_damage_from_id`] for abilities,
//! [`crate::mechanics::balance::character_attrs_power_raw`] for pets), so these
//! fns only handle the scoring / sort / take marshalling.
//!
//! Follows the [`super::power`] reference shape: a typed `*Ctx`, a `*Fn` alias, a
//! native impl, and a `register`.

use std::cmp::Ordering;

use configs::game_config::GameConfig;
use essences::abilities::Ability;
use uuid::Uuid;

use crate::game_config_helpers::GameConfigLookup;
use crate::mechanics::balance;
use crate::mechanics::content_lookups::ContentLookups;

/// `fast_equip_abilities_script` sees (`Abilities`, `Slots`) plus the config /
/// content lookups the `balance` module carries (needed by
/// `balance::ability_damage`).
///
/// `abilities` mirrors the `Abilities` const (the non-class abilities the
/// handler hands in); `slots` mirrors the `Slots` const (a `u64`, the script
/// uses `signed(Slots)`).
pub struct AbilityIdsCtx<'a> {
    pub abilities: &'a [Ability],
    pub slots: u64,
    pub config: &'a GameConfig,
    pub lookups: &'a ContentLookups,
}

/// Signature of an `ability_ids` native fn. Free `fn` (no captured state) so it
/// is `Copy` and trivially stored in the registry; runtime context arrives via
/// [`AbilityIdsCtx`].
pub type AbilityIdsFn = fn(&AbilityIdsCtx) -> anyhow::Result<Vec<Uuid>>;

/// The `order` of an ability's rarity, or `0` when the template or its rarity
/// is missing from config — an unknown ability ranks below every known one
/// rather than aborting the whole fast-equip.
fn ability_rarity_order(config: &GameConfig, ability: &Ability) -> u64 {
    let Some(rarity_id) = config
        .ability_template(ability.template_id)
        .map(|template| template.rarity_id)
    else {
        return 0;
    };
    config
        .ability_rarity(rarity_id)
        .map_or(0, |rarity| rarity.order)
}

/// Ranks the player's non-class abilities by **rarity first, then damage**, and
/// returns the `template_id`s of the top `min(len, Slots)`.
///
/// Rarity leads for the same reason it does in [`fast_equip_pets`]: it is the
/// axis the player pulled for and the one that sets the ability's ceiling, so a
/// heavily-levelled Common briefly out-damaging a fresh Legendary should not
/// make quick-equip bench the Legendary. Damage
/// ([`crate::mechanics::balance::ability_damage_from_id`]) orders abilities
/// inside one rarity band.
///
/// Within a band the damage comparator is the `floor(dmg_b - dmg_a)` ordering
/// inherited from the live `fast_equip_abilities_script`: differences in the
/// open interval `(-1, 1)` floor to `0` and count as **equal**, and the sort is
/// stable, so genuinely-tied abilities keep their input order. That quirk is
/// preserved deliberately.
///
/// A failed `balance::ability_damage` lookup surfaces here as `Err`.
pub fn fast_equip_abilities(ctx: &AbilityIdsCtx) -> anyhow::Result<Vec<Uuid>> {
    // `sort_by`'s comparator would call `ability_damage` for both sides on every
    // comparison; computing it up front is equivalent (the helper is pure) and
    // lets us fail fast on an unknown id.
    let mut scored: Vec<(u64, f64, &Ability)> = Vec::with_capacity(ctx.abilities.len());
    for ability in ctx.abilities {
        let dmg = balance::ability_damage_from_id(
            ctx.config,
            ctx.lookups,
            ability.template_id,
            ability.level,
        )
        .map_err(|err| anyhow::anyhow!("balance::ability_damage: {err}"))?;
        scored.push((ability_rarity_order(ctx.config, ability), dmg, ability));
    }

    // Stable sort: rarity descending, then the floored damage ordering.
    scored.sort_by(|&(rarity_a, dmg_a, _), &(rarity_b, dmg_b, _)| {
        rarity_b.cmp(&rarity_a).then_with(|| {
            // `floor(dmg_b - dmg_a)`: positive => b ranks first (descending).
            let cmp = (dmg_b - dmg_a).floor();
            if cmp < 0.0 {
                Ordering::Less
            } else if cmp > 0.0 {
                Ordering::Greater
            } else {
                Ordering::Equal
            }
        })
    });

    // `0..min(abilities.len, signed(Slots))` — clamp to available abilities.
    let take = std::cmp::min(scored.len(), ctx.slots as usize);
    let result: Vec<Uuid> = scored
        .iter()
        .take(take)
        .map(|&(_, _, ability)| ability.template_id)
        .collect();

    Ok(result)
}
// Native function(s) for the `item_ids` category — script slots that return a
// `Vec<Uuid>` of template ids (`run_item_ids_script`).
//
// The concrete, stable slot ported here is `fast_equip_pets_script`
// (`game_settings.fast_equip_pets_script`): given the player's `all_pets` and
// the available pet `Slots`, it picks the pets to auto-equip. The original
// script's inline pet literal carried no `template_id`, so the ability factor of
// `balance::character_power` could never resolve and the ranking never
// worked. This native port implements the *intended* ranking instead: the
// attribute power of a level-1 character carrying just the candidate pet
// ([`crate::mechanics::balance::character_attrs_power`] — see
// `pet_power` below for why dropping the ability factor is order-preserving),
// so this fn only handles the sort / selection / marshalling.
//
// NOTE (wiring): at runtime `fast_equip_pets_script` is dispatched through
// `run_abilities_ids_script` (see `pets.rs`), even though its output shape is
// `Vec<Uuid>` — the same shape `run_item_ids_script` produces. This fn is
// therefore wired at the pets-equip callsite (which has `Pets`/`Slots` in
// scope), not inside `run_item_ids_script` (whose scope is `CharacterState`
// and which evaluates arbitrary bundle-step scripts).

use essences::items::Item;
use essences::pets::Pet;

/// Inputs available to an `item_ids` native fn for the `fast_equip_pets_script`
/// / content lookups the `balance` module carries.
pub struct ItemIdsCtx<'a> {
    /// `Pets` const — the player's full pet roster (`all_pets`).
    pub pets: &'a [Pet],
    /// `Slots` const — number of available pet slots.
    pub slots: i64,
    /// The player's character level. A pet is scored as the marginal power it
    /// adds to THIS character, so the baseline has to be the real one.
    pub character_level: i64,
    /// The player's equipped gear, for the same reason: a pet's contribution to
    /// `DPS × EHP` depends on which side of that product the gear already fills.
    pub inventory: &'a [Item],
    pub config: &'a GameConfig,
    pub lookups: &'a ContentLookups,
}

/// Signature of an `item_ids` native fn. Free `fn` (no captured state) so it is
/// `Copy` and trivially stored in the registry; runtime context arrives via
/// [`ItemIdsCtx`].
pub type ItemIdsFn = fn(&ItemIdsCtx) -> anyhow::Result<Vec<Uuid>>;

/// `balance::character_power(1, [], abilities, [pet])` — i.e. score a pet by
/// the power of a level-1 character carrying just that pet.
///
/// level: 1 }] }` literal — but `balance::character_power` reads abilities by
/// **`template_id`**, which this inline map does **not** carry, so the ability
/// factor could never resolve and the intended ranking never ran (the original
/// script erred; a first byte-faithful port scored every pet
/// `floor(attrs_power * 0) == 0`, turning the fast-equip sort into roster
/// order). The ability literal is the same hard-coded constant for every pet,
/// so it cannot affect the *ordering* this fn exists to produce — we therefore
/// rank by [`balance::character_attrs_power`] (the `attrs_power` term alone)
/// and intentionally drop the constant ability multiplier.
///
/// Scored at the player's own level and gear, on the UNFLOORED power. Both
/// matter: at level 1 with no inventory `DPS × EHP / power_norm` is around
/// `0.01`, so the displayed-power integer floors every pet to `0`, every
/// comparison ties, and the stable sort below hands back roster order — the
/// exact failure this fn was written to fix, reached by a second route.
fn pet_power(ctx: &ItemIdsCtx, pet: &Pet) -> anyhow::Result<f64> {
    balance::character_attrs_power_raw(
        ctx.config,
        ctx.character_level,
        ctx.inventory,
        std::slice::from_ref(pet),
    )
    .map_err(|err| anyhow::anyhow!("balance::character_attrs_power_raw: {err}"))
}

/// Rank the roster by **rarity first, then power**, and return the
/// `template_id`s of the top `min(pets.len, Slots)`.
///
/// Rarity leads because that is what the player is picking for: a Legendary is
/// the pet they pulled for and the one whose stat ceiling and facet pool are
/// worth investing in, and a fully-levelled Common briefly out-scoring it is
/// not a reason for quick-equip to bench it. Power (the marginal contribution
/// this pet makes to THIS character — see [`pet_power`]) orders pets inside one
/// rarity band, where it is the honest comparison.
pub fn fast_equip_pets(ctx: &ItemIdsCtx) -> anyhow::Result<Vec<Uuid>> {
    let mut scored: Vec<(&Pet, u64, f64)> = Vec::with_capacity(ctx.pets.len());
    for pet in ctx.pets {
        let power = pet_power(ctx, pet)?;
        scored.push((pet, pet.rarity.order, power));
    }

    // Descending by (rarity, power). Stable, so pets of genuinely equal rank
    // keep roster order. `total_cmp` rather than `partial_cmp`: a NaN score
    // would otherwise make the comparator inconsistent and could panic the sort.
    scored.sort_by(|(_, ra, pa), (_, rb, pb)| rb.cmp(ra).then_with(|| pb.total_cmp(pa)));

    let take = std::cmp::min(scored.len(), ctx.slots.max(0) as usize);
    Ok(scored
        .into_iter()
        .take(take)
        .map(|(pet, _, _)| pet.template_id)
        .collect())
}

#[cfg(test)]
mod tests {
    use super::*;
    use essences::items::Attribute;
    use essences::pets::{PetComputedSecondaryStat, PetRarity};

    fn test_attr(id: Uuid, code: &str, db_code: u8) -> Attribute {
        Attribute {
            id,
            code: code.to_string(),
            db_code,
            ..Default::default()
        }
    }

    fn test_pet(template_id: Uuid, stats: &[(Uuid, i64)]) -> Pet {
        rare_pet(template_id, 0, stats)
    }

    fn rare_pet(template_id: Uuid, rarity_order: u64, stats: &[(Uuid, i64)]) -> Pet {
        Pet {
            template_id,
            name: Default::default(),
            icon_path: String::new(),
            rarity: PetRarity {
                order: rarity_order,
                ..PetRarity::default()
            },
            level: 1,
            shards_amount: 0,
            stats: stats
                .iter()
                .map(|(attribute_id, value)| PetComputedSecondaryStat {
                    attribute_id: *attribute_id,
                    value: *value,
                })
                .collect(),
        }
    }

    /// port multiplied every score by an unresolvable ability factor of 0, so
    /// every pet scored 0 and fast-equip returned roster order instead of the
    /// strongest pets.
    #[test]
    fn fast_equip_pets_picks_strongest_not_roster_order() {
        let mut config = configs::tests_game_config::generate_game_config_for_tests();

        // The shared test fixture has no `attack` / `speed` attribute codes,
        // and `power_from_attrs` multiplies by both — add them so pet power is
        // non-zero. `hp` already exists in the fixture.
        let hp_id = Uuid::parse_str("45eca0a7-7430-487b-bd65-b796c6d88c08").unwrap();
        let attack_id = Uuid::from_u128(0xA77AC4);
        let speed_id = Uuid::from_u128(0x59EED);
        config.attributes.push(test_attr(attack_id, "attack", 60));
        config.attributes.push(test_attr(speed_id, "speed", 61));

        let base_stats = [(attack_id, 600), (speed_id, 10000)];
        let with_hp = |hp: i64| {
            let mut stats = vec![(hp_id, hp)];
            stats.extend_from_slice(&base_stats);
            stats
        };
        let weak = test_pet(Uuid::from_u128(1), &with_hp(3_000));
        let strong = test_pet(Uuid::from_u128(2), &with_hp(12_000));
        let medium = test_pet(Uuid::from_u128(3), &with_hp(6_000));

        let pets = vec![weak, strong, medium];
        let lookups = ContentLookups::default();
        let ctx = ItemIdsCtx {
            pets: &pets,
            slots: 2,
            character_level: 1,
            inventory: &[],
            config: &config,
            lookups: &lookups,
        };

        // Every pet must get a strictly positive, stat-dependent score.
        let powers: Vec<f64> = pets
            .iter()
            .map(|pet| pet_power(&ctx, pet).unwrap())
            .collect();
        assert!(
            powers.iter().all(|p| *p > 0.0),
            "pet powers must be non-zero: {powers:?}"
        );
        assert!(
            powers[1] > powers[2] && powers[2] > powers[0],
            "pet powers must follow stats: {powers:?}"
        );

        // The two strongest pets win, not the first two in roster order.
        let ids = fast_equip_pets(&ctx).unwrap();
        assert_eq!(ids, vec![Uuid::from_u128(2), Uuid::from_u128(3)]);
    }

    /// Rarity outranks raw damage: a levelled low-rarity ability must not push a
    /// higher-rarity one out of a slot, and damage still orders abilities inside
    /// one rarity band.
    #[test]
    fn fast_equip_abilities_ranks_rarity_before_damage() {
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();

        // The rarities the fixture's abilities actually use, lowest and highest.
        let mut used: Vec<_> = config
            .ability_rarities
            .iter()
            .filter(|rarity| {
                config
                    .abilities
                    .iter()
                    .any(|template| template.rarity_id == rarity.id)
            })
            .collect();
        used.sort_by_key(|rarity| rarity.order);
        let (low, high) = (used[0], used[used.len() - 1]);
        assert!(
            low.order < high.order,
            "the fixture must carry abilities of at least two rarities"
        );

        let template_of = |rarity_id: Uuid| {
            config
                .abilities
                .iter()
                .find(|template| template.rarity_id == rarity_id)
                .expect("rarity was chosen from the templates themselves")
                .id
        };

        // The low-rarity ability is levelled far past the high-rarity one, so
        // it wins on damage and must still lose on rank.
        let levelled_low = Ability {
            template_id: template_of(low.id),
            level: 60,
            shards_amount: 0,
        };
        let fresh_high = Ability {
            template_id: template_of(high.id),
            level: 1,
            shards_amount: 0,
        };
        let abilities = vec![levelled_low.clone(), fresh_high.clone()];

        let damage = |ability: &Ability| {
            balance::ability_damage_from_id(&config, &lookups, ability.template_id, ability.level)
                .unwrap()
        };
        assert!(
            damage(&levelled_low) > damage(&fresh_high),
            "the fixture only proves anything while the low-rarity ability out-damages the high one"
        );

        let ctx = AbilityIdsCtx {
            abilities: &abilities,
            slots: 1,
            config: &config,
            lookups: &lookups,
        };
        assert_eq!(
            fast_equip_abilities(&ctx).unwrap(),
            vec![fresh_high.template_id],
            "the one slot went to the rarer ability, not the higher-damage one"
        );
    }

    /// Rarity outranks raw power: a heavily-statted Common must not push a
    /// Legendary out of a slot, and power still orders pets inside one band.
    #[test]
    fn fast_equip_pets_ranks_rarity_before_power() {
        let mut config = configs::tests_game_config::generate_game_config_for_tests();

        let hp_id = Uuid::parse_str("45eca0a7-7430-487b-bd65-b796c6d88c08").unwrap();
        let attack_id = Uuid::from_u128(0xA77AC4);
        let speed_id = Uuid::from_u128(0x59EED);
        config.attributes.push(test_attr(attack_id, "attack", 60));
        config.attributes.push(test_attr(speed_id, "speed", 61));

        let make = |id: u128, rarity_order: u64, hp: i64| {
            rare_pet(
                Uuid::from_u128(id),
                rarity_order,
                &[(hp_id, hp), (attack_id, 600), (speed_id, 10_000)],
            )
        };
        // The Common is by far the strongest pet on raw stats.
        let fat_common = make(1, 0, 90_000);
        let weak_legendary = make(2, 3, 3_000);
        let strong_legendary = make(3, 3, 6_000);

        let pets = vec![fat_common, weak_legendary, strong_legendary];
        let lookups = ContentLookups::default();
        let ctx = ItemIdsCtx {
            pets: &pets,
            slots: 2,
            character_level: 1,
            inventory: &[],
            config: &config,
            lookups: &lookups,
        };

        assert!(
            pet_power(&ctx, &pets[0]).unwrap() > pet_power(&ctx, &pets[2]).unwrap(),
            "the fixture only proves anything while the Common out-powers both Legendaries"
        );

        // Both Legendaries first, stronger one leading; the Common is benched.
        let ids = fast_equip_pets(&ctx).unwrap();
        assert_eq!(ids, vec![Uuid::from_u128(3), Uuid::from_u128(2)]);
    }

    /// The scores must be DISTINCT, not merely ordered. Ranking on the
    /// displayed-power integer made every real pet score `0` — the sort then
    /// tied on every comparison and, being stable, returned roster order. The
    /// previous test missed it because its synthetic stats are large enough to
    /// survive the floor; real pets carry small basis-point stats.
    #[test]
    fn pet_scores_separate_on_realistic_stats() {
        let mut config = configs::tests_game_config::generate_game_config_for_tests();

        let hp_id = Uuid::parse_str("45eca0a7-7430-487b-bd65-b796c6d88c08").unwrap();
        let attack_id = Uuid::from_u128(0xA77AC4);
        let speed_id = Uuid::from_u128(0x59EED);
        config.attributes.push(test_attr(attack_id, "attack", 60));
        config.attributes.push(test_attr(speed_id, "speed", 61));

        // Small, close-together stats: the kind that floor to a single value.
        let make = |id: u128, hp: i64| {
            test_pet(
                Uuid::from_u128(id),
                &[(hp_id, hp), (attack_id, 2), (speed_id, 10_000)],
            )
        };
        let pets = vec![make(1, 10), make(2, 12), make(3, 11)];

        let lookups = ContentLookups::default();
        let ctx = ItemIdsCtx {
            pets: &pets,
            slots: 2,
            character_level: 1,
            inventory: &[],
            config: &config,
            lookups: &lookups,
        };

        let powers: Vec<f64> = pets
            .iter()
            .map(|pet| pet_power(&ctx, pet).unwrap())
            .collect();
        assert!(
            powers[1] > powers[2] && powers[2] > powers[0],
            "small stat differences must still separate: {powers:?}"
        );
        assert!(
            powers.iter().all(|p| p.floor() as i64 == 0),
            "this fixture only proves anything while the INTEGER score is 0: {powers:?}"
        );

        // Strongest first, and specifically not roster order.
        let ids = fast_equip_pets(&ctx).unwrap();
        assert_eq!(ids, vec![Uuid::from_u128(2), Uuid::from_u128(3)]);
    }
}