overlord_event_system/behaviors/

fast_equip.rs

//! Native functions for the `ability_ids` category (`run_abilities_ids_script`)
//! `fast_equip_abilities_script` does (copy `Abilities`, sort by
//! `balance::ability_damage` descending with a `floor`ed comparator, take the
//! top `Slots`) and then call the already-native
//! [`crate::mechanics::balance::ability_damage_from_id`] for the core damage
//! formula, so this fn only handles the copy/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::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>>;

/// Native port of the live `fast_equip_abilities_script`:
///
///
/// Mirrored exactly:
/// - The comparator is `floor(dmg_b - dmg_a)` cast to an integer ordering, the
///   `Less`, `0` => `Equal`, `> 0` => `Greater`). Differences in the open
///   interval `(-1, 1)` floor to `0` and are treated as **equal** — this is a
///   quirk of the live script and is preserved deliberately.
///   abilities keep their input order.
/// - The slice is `min(len, Slots)`; `signed(Slots)` is `slots as i64`, but the
///   clamp to `len` makes it safe to compute as `min` over `usize`.
///
/// A failed `balance::ability_damage` lookup surfaces here as `Err`
pub fn fast_equip_abilities(ctx: &AbilityIdsCtx) -> anyhow::Result<Vec<Uuid>> {
    // Mirror `let abilities = []; for a in Abilities { abilities.push(a); }`,
    // pairing each ability with its precomputed damage. `sort_by`'s comparator
    // calls `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, exactly as the script would on its first evaluation of it.
    let mut scored: Vec<(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((dmg, ability));
    }

    // Stable sort by `floor(dmg_b - dmg_a)` ordering (descending damage with the
    scored.sort_by(|&(dmg_a, _), &(dmg_b, _)| {
        // `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 strongest pets to auto-equip and
//
//
// 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::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,
    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.
fn pet_power(ctx: &ItemIdsCtx, pet: &Pet) -> anyhow::Result<i64> {
    balance::character_attrs_power(ctx.config, 1, &[], std::slice::from_ref(pet))
        .map_err(|err| anyhow::anyhow!("balance::character_attrs_power: {err}"))
}

/// `sort_by(|a, b| floor((pet_power(b) - pet_power(a)) * 1000.0))`) and return
/// the `template_id`s of the top `min(pets.len, Slots)`.
pub fn fast_equip_pets(ctx: &ItemIdsCtx) -> anyhow::Result<Vec<Uuid>> {
    // comparator; the resulting order is identical for a stable input).
    let mut scored: Vec<(&Pet, i64)> = Vec::with_capacity(ctx.pets.len());
    for pet in ctx.pets {
        let power = pet_power(ctx, pet)?;
        scored.push((pet, power));
    }

    // Mirror `floor((pet_power(b) - pet_power(a)) * 1000.0)`: descending by
    // power. `pet_power` returns an integer (`balance::character_power` floors to
    // i64), so `(pb - pa) * 1000.0` is an exact multiple of 1000 and `floor`
    // reduces to the sign of `pb - pa` — i.e. a plain descending sort by power.
    // stable sort here too.
    scored.sort_by(|(_, pa), (_, pb)| pb.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 {
        Pet {
            template_id,
            name: Default::default(),
            icon_path: String::new(),
            rarity: PetRarity::default(),
            level: 1,
            shards_amount: 0,
            active_ability_id: None,
            passive_ability_id: None,
            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,
            config: &config,
            lookups: &lookups,
        };

        // Every pet must get a strictly positive, stat-dependent score.
        let powers: Vec<i64> = pets
            .iter()
            .map(|pet| pet_power(&ctx, pet).unwrap())
            .collect();
        assert!(
            powers.iter().all(|p| *p > 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)]);
    }
}