overlord_event_system/behaviors/

power.rs

//! Native functions for the power categories (`character_power`, `item_power`,
//! ...). These handle the loadout marshalling and then call the
//! [`crate::mechanics::balance`] logic for the core power formula.
//!
//! Reference category for the rollout: every other category follows the same
//! shape — a typed `*Ctx`, a `*Fn` alias, native impls, and a `register`.

use configs::game_config::GameConfig;
use essences::character_state::CharacterState;
use essences::items::Item;
use essences::pets::Pet;

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

/// `character_power_calculate_script` sees (`CharacterState`) plus the config /
/// content lookups the `balance` module carries.
pub struct CharacterPowerCtx<'a> {
    pub character: &'a CharacterState,
    pub config: &'a GameConfig,
    pub lookups: &'a ContentLookups,
}

/// Signature of a `character_power` native fn. Free `fn` (no captured state) so
/// it is `Copy` and trivially stored in the registry; runtime context arrives
/// via [`CharacterPowerCtx`].
pub type CharacterPowerFn = fn(&CharacterPowerCtx) -> anyhow::Result<i64>;

/// Native port of `character_power_calculate_script` (the `CharacterState`
/// branch): keep equipped inventory items, then call `balance::character_power`.
pub fn character_power(ctx: &CharacterPowerCtx) -> anyhow::Result<i64> {
    // The displayed / matchmaking / gating power must reflect ALL combat
    // sources — char-level, items, class, pets, talents, statue, class-levels
    // — i.e. the *same* aggregation combat uses; a subset under-counts
    // invested players in PvP matchmaking and drifts gear-compare. Route
    // through the canonical aggregation so the scalar is one source of truth
    // with combat-effective stats.
    let stats = crate::attributes::calculate_player_entity_stats_with_zeroes(
        &essences::entity::EntityState::Character(ctx.character),
        ctx.config,
    )?;
    let attrs: balance::AttrMap = stats
        .attributes
        .0
        .iter()
        .map(|(code, value)| (code.clone(), *value as f64))
        .collect();
    // `P_static`: combat-effective stats plus the analytic ability factors.
    // The per-item `power_bonus` jitter is deliberately NOT part of it — it
    // changes no combat outcome, so BAL-030 keeps it out of displayed Power,
    // matchmaking and the auto-equip comparison. The field stays persisted and
    // inert for compatibility.
    let static_power = balance::character_power_from_attrs_raw(
        ctx.config,
        ctx.lookups,
        &attrs,
        &ctx.character.equipped_abilities,
        // Pets cast nothing: they contribute attributes and Team Die facets.
        None,
    );

    // `Πq`: everything that cannot be folded honestly into a stat — laws,
    // bridges, artifact rules, ability stones, equipment packages, facets.
    let dynamic = crate::mechanics::power_q::dynamic_power_multiplier(ctx.config, ctx.character);

    // One rounding, at the very end (BAL-030): intermediate components are
    // never floored, so a small component cannot vanish before it is applied.
    Ok((static_power * dynamic).floor() as i64)
}
// Native function for the `item_power` category — the marginal power an item
// contributes when added to the character's currently-equipped loadout.
//
// `character_power` of the equipped inventory *without* any item in the same
// logical equipment slot as the candidate `Item`, then again *with* the candidate pushed
// on, and returns the difference. The underlying `balance::character_power`
// call uses [`crate::mechanics::balance::character_power`] for the power
// formula, so this fn only handles the loadout marshalling.
//
// Note on scope: the authoritative production caller is
// `OverlordState::calculate_item_power` (`state.rs`), which sets both
// this native port takes the same `CharacterState` plus the candidate `Item`.

/// `item_power_calculate_script` sees in the production path: the owning
/// `CharacterState` and the candidate `Item`, plus the config / content lookups
/// the `balance` module carries.
pub struct ItemPowerCtx<'a> {
    pub character: &'a CharacterState,
    pub item: &'a Item,
    pub config: &'a GameConfig,
    pub lookups: &'a ContentLookups,
}

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

/// Native port of `item_power_calculate_script`: power of the equipped loadout
/// with the candidate item minus the power without the same logical slot.
///
/// - `level`      = `CharacterState.character.character_level`
/// - `inventory`  = every equipped `CharacterState.inventory` item outside the
///   candidate's logical equipment slot.
/// - `abilities`  = `CharacterState.equipped_abilities`
/// - `pets`       = `CharacterState.equipped_pets`
///
/// Then `power_without = balance::character_power(...)`, push the candidate,
/// `power_with = balance::character_power(...)`, return `power_with - power_without`.
pub fn item_power(ctx: &ItemPowerCtx) -> anyhow::Result<i64> {
    let level = ctx.character.character.character_level;

    let candidate_slot_key = ctx.item.equipment_slot_key();

    // Base build = the EQUIPPED loadout minus the candidate's logical slot.
    // `is_equipped` is load-bearing: without it, a dirty inventory (e.g. the
    // server-chest opening a whole batch before equipping) leaks every loose,
    // unequipped item of other types into the base, so the candidate's marginal
    // is measured against a phantom build — corrupting the ranking and letting
    // the equip pick gear that lowers real `character.power`. With a clean
    // inventory (one-at-a-time flow) the filter is a no-op, since all items are
    // equipped. Matches `character_power`, which counts equipped items only.
    let mut inventory: Vec<Item> = ctx
        .character
        .inventory
        .iter()
        .filter(|item| item.is_equipped && item.equipment_slot_key() != candidate_slot_key)
        .cloned()
        .collect();

    // Pets in `EquippedPets.slotted` (BTreeMap) value order — matches the old
    // `eq.slotted.into_values()` marshalling.
    let pets: Vec<Pet> = ctx
        .character
        .equipped_pets
        .slotted
        .values()
        .cloned()
        .collect();
    let abilities = &ctx.character.equipped_abilities;

    let power_without =
        balance::character_power(ctx.config, ctx.lookups, level, &inventory, abilities, &pets)
            .map_err(|err| anyhow::anyhow!("balance::character_power (without): {err}"))?;

    inventory.push(ctx.item.clone());

    let power_with =
        balance::character_power(ctx.config, ctx.lookups, level, &inventory, abilities, &pets)
            .map_err(|err| anyhow::anyhow!("balance::character_power (with): {err}"))?;

    Ok(power_with - power_without)
}
// Native function for the `party_power_adjust` category — the
// `power_adjust_script` slot (`run_party_power_adjust` in `script.rs`).
//
// the player's power, so a (real-money-irrelevant) idle party ally is neither
// trivially weak nor stronger than the player. The shipped script is:
//
//
// `POWER_MIN` / `POWER_MAX` are `FLOAT`, and `INT.min(FLOAT).max(FLOAT)`
// evaluates the whole clamp in `FLOAT`. The native port therefore performs the
// arithmetic in `f64` and only narrows to `i64` at the very end, so it produces
// integer-valued results wherever the slot yields a whole `i64` (the slot is
// read as `i64`, so a non-integral `FLOAT` result is rejected).

/// Inputs available to a `party_power_adjust` native fn — the same scope the
/// member's `CharacterState` (the slot's two `set_const` bindings in
/// `run_party_power_adjust`).
pub struct PartyPowerAdjustCtx<'a> {
    pub player_character_state: &'a CharacterState,
    pub party_character_state: &'a CharacterState,
}

/// Signature of a `party_power_adjust` native fn. Free `fn` (no captured state)
/// so it is `Copy` and trivially stored in the registry; runtime context
/// arrives via [`PartyPowerAdjustCtx`].
pub type PartyPowerAdjustFn = fn(&PartyPowerAdjustCtx) -> anyhow::Result<i64>;

/// Native port of the shipped `power_adjust_script`: clamp the party member's
/// power into `[floor(0.5 * player), floor(1.1 * player)]`.
///
/// does after the `FLOAT` promotion) and narrowed to `i64` last.
pub fn power_adjust(ctx: &PartyPowerAdjustCtx) -> anyhow::Result<i64> {
    Ok(power_adjust_scalar(
        ctx.player_character_state.character.power,
        ctx.party_character_state.character.power,
    ))
}

/// Clamp `party_power` into `[floor(0.5 * player_power), floor(1.1 * player_power)]`.
///
/// Scalar form so callers that already hold both power values (e.g. party-preview
/// assembly) avoid fetching a full `CharacterState` just to read `.character.power`.
pub fn power_adjust_scalar(player_power: i64, party_power: i64) -> i64 {
    let power_min = (0.5_f64 * player_power as f64).floor();
    let power_max = (1.1_f64 * player_power as f64).floor();

    // (`INT.min(FLOAT)` / `INT.max(FLOAT)` promote the INT to FLOAT).
    let adjusted = (party_power as f64).min(power_max).max(power_min);

    // The slot is read as `i64` (a non-integral FLOAT is rejected); narrowing
    // truncates toward zero, matching that integer value.
    adjusted as i64
}