overlord_event_system/mechanics/

cores.rs

//! Pure arithmetic and state machines for the twin cores, laws and bridges
//! (OVT-2517, laws v0.2). No events, no IO — everything here is a function of
//! `CoresState` + `GameConfig`, so every acceptance criterion in the plan is
//! unit-testable without a fight or a database.
//!
//! Layering:
//! * `core_multiplier` / `law_slots_for_level` / `max_bridges` — part A plus
//!   the structural limits. Refitted for the artifact right column: one slot per
//!   core level and a cap of 5, so `min(level) − 1` is always exactly one short
//!   of what the slots allow and the bridge limit binds at every level again
//!   (post-merge plan §8).
//! * `laws_unlocked_by_core_level` / `grant_unlocked_laws` — the deterministic
//!   law schedule: a core level hands out its side's batch outright, so random
//!   copy drops fund LEVELLING only and never the unlock itself.
//! * `build_law_bridge_charges` / `law_power_multiplier` — the per-fight bridge
//!   charge machinery that replaced `LawRhythms`.
//! * `active_law_attribute_deltas` — the passive half of the active side's
//!   laws, amplified by whatever their bridge delivered at the last flip.

use std::collections::BTreeMap;

use configs::game_config::GameConfig;
use essences::cores::{
    BridgeCharge, CHARGE_SCALE, CoresState, LawBridge, LawBridgeCharges, LawTemplate,
    LawTemplateId, OwnedLaw,
};
use essences::flip::WorldSide;

use crate::mechanics::artifacts::LawColumnMods;

/// Damage bonus armed for the owner's next BASIC attack, permyriad.
///
/// Spent by [`crate::mechanics::fight::attack`], which picks between this and
/// [`ARM_SKILL`] by the cast kind recorded on the caster. Keeping the two
/// families in two keys is what makes `RL-02` ("next Basic Attack") and
/// `FL-02` ("next original Skill") two different laws rather than two names
/// for one arm.
pub const ARM_BASIC: &str = "law.arm_basic";

/// Damage bonus armed for the owner's next original SKILL, permyriad. See
/// [`ARM_BASIC`].
pub const ARM_SKILL: &str = "law.arm_skill";

/// Damage bonus armed for the strike being resolved RIGHT NOW, permyriad
/// (`RL-01` "every 5th Basic Attack: THIS strike deals +100%").
///
/// Unlike [`ARM_BASIC`] and [`ARM_SKILL`] this is not gated on the cast kind:
/// "this attack" is whatever is swinging, basic or skill. It is armed from the
/// pre-cast hook, which runs before the cast computes its damage, so the strike
/// that triggered the law is the one that spends it.
///
/// Its own key rather than the stones' `stone.next_attack_bonus`: that key is
/// charge-gated by the stones runtime, and a law writing a magnitude into it
/// with no charge behind it was read as unarmed — which is how this whole
/// family shipped inert.
pub const ARM_THIS: &str = "law.arm_this";

/// Which of the two arms a cast of `kind` spends.
pub fn law_arm_key(kind: crate::logic::combat_facts::CastKind) -> &'static str {
    match kind {
        crate::logic::combat_facts::CastKind::Basic => ARM_BASIC,
        crate::logic::combat_facts::CastKind::Skill => ARM_SKILL,
    }
}

/// The PER-STAT multiplier for the product of the two core levels — BAL-010's
/// `M_stat = (1 + min(P/5, sqrt(P) − 0.2))^(1/2.75)`
/// ([`configs::cores::core_stat_multiplier`] owns the arithmetic).
///
/// Product 0 (any character with an un-levelled core) gets ×1.0 — that is what
/// makes "a character with no cores plays exactly as before" (acceptance #14)
/// true by construction. The `config` parameter is kept so a future config
/// knob has an obvious home and every caller already threads it.
pub fn core_multiplier(config: &GameConfig, cores: &CoresState) -> f64 {
    let _ = config;
    let product = cores.real_level.saturating_mul(cores.fantasy_level);
    configs::cores::core_stat_multiplier(product)
}

/// `slots = min(ceil(level / core_levels_per_slot), max_slots_per_core)`.
/// Level 0 (no core) has no slots.
pub fn law_slots_for_level(config: &GameConfig, level: i64) -> i64 {
    if level <= 0 {
        return 0;
    }
    let per_slot = config.cores_settings.core_levels_per_slot.get().max(1);
    let slots = (level + per_slot - 1) / per_slot;
    slots.min(config.cores_settings.max_slots_per_core)
}

/// `bridges = min(real_level, fantasy_level, max_slot_level) - 1 + extra`,
/// floored at 0. With one core still at level 1 and no artifact, no bridge is
/// allowed at all.
///
/// `extra` is `BL-01 Extra Span`'s "+1 bridge"
/// ([`crate::mechanics::artifacts::LawColumnMods::extra_bridges`]), `0` for
/// everyone else. It is worth exactly one bridge only because the slot ladder
/// was refitted with it: at one slot per level and five slots, `min(level) − 1`
/// is always one short of what the slots physically allow, so the extra bridge
/// always has somewhere to go (post-merge plan §8). Under the old "a slot every
/// two levels, cap 10" pair the limit stopped binding from level 4 and this half
/// of the stone was dead.
///
/// The `max_slot_level` clamp is what keeps that true now that core levels are
/// unbounded: without it a level-9999 core would allow 9998 bridges against 5
/// possible, the limit would stop binding, and `BL-01` would go dead exactly the
/// way the refit existed to prevent.
pub fn max_bridges(config: &GameConfig, cores: &CoresState, extra: i64) -> i64 {
    let level = cores
        .real_level
        .min(cores.fantasy_level)
        .min(config.cores_settings.max_slot_level());
    (level - 1 + extra.max(0)).max(0)
}

/// Drops the bridges that no longer fit `max_bridges`, and reports how many
/// went.
///
/// The budget only ever shrinks one way: `BL-01 Extra Span` leaving the Bridge
/// socket takes its `+1` with it. The bridge it paid for has to go too, or the
/// stone is a ratchet — socket it, build the extra bridge, put another Bridge
/// stone in its place and keep both. Core levels only rise, so this is the one
/// direction that needs cleaning up, and it mirrors `UnslotLaw` dropping the
/// bridges of the law it unslots.
///
/// The bridges that go are the tail of the list. Inside one session that is the
/// newest first, but `character_law_bridges` is read back ordered by law id
/// rather than by creation time, so after a reconnect it is simply the last in
/// that order. Deterministic either way, and deliberately not shown to the
/// player as "your newest bridge".
pub fn prune_bridges_over_budget(config: &GameConfig, cores: &mut CoresState, extra: i64) -> usize {
    let allowed = max_bridges(config, cores, extra).max(0) as usize;
    if cores.bridges.len() <= allowed {
        return 0;
    }
    let dropped = cores.bridges.len() - allowed;
    cores.bridges.truncate(allowed);
    dropped
}

/// Every law of `side` the deterministic schedule hands out at core `level` and
/// below.
///
/// `<=`, not `==`, on purpose: that is the whole of the backfill requirement. A
/// character who reached level 4 before a law was rescheduled onto level 2, or
/// before the schedule existed at all, collects everything it owes on the next
/// upgrade rather than needing a migration.
pub fn laws_unlocked_by_core_level(
    config: &GameConfig,
    side: WorldSide,
    level: i64,
) -> impl Iterator<Item = LawTemplateId> + '_ {
    config
        .laws
        .iter()
        .filter(move |law| law.side == side && law.unlock_core_level <= level)
        .map(|law| law.id)
}

/// Grants every law `side`'s core has earned at its CURRENT level, and reports
/// how many were new.
///
/// Idempotent by construction: an owned law is skipped whole, so re-upgrading,
/// replaying an event or backfilling never adds a copy. That matters because
/// copies are the law upgrade currency — a duplicate grant would be free
/// progression, not a cosmetic double.
///
/// A granted law is a plain level-1 `OwnedLaw` with zero copies, unslotted:
/// identical to what the first random copy drop used to produce, so nothing
/// downstream has to tell a granted law from a dropped one.
pub fn grant_unlocked_laws(config: &GameConfig, cores: &mut CoresState, side: WorldSide) -> usize {
    let level = cores.level_of(side);
    let unlocked: Vec<LawTemplateId> = laws_unlocked_by_core_level(config, side, level).collect();
    let mut granted = 0;
    for template_id in unlocked {
        if cores.law(template_id).is_some() {
            continue;
        }
        cores.laws.push(OwnedLaw {
            template_id,
            level: 1,
            copies: 0,
            slot_index: None,
        });
        granted += 1;
    }
    granted
}

/// Law levels raise a value by the same fraction of its level-1 magnitude per
/// step. Integer arithmetic keeps the growth exactly reproducible and keeps a
/// negative value (e.g. −10% received damage) growing away from zero.
///
/// The step size itself is deliberately NOT a config knob yet: the values in
/// the starter catalog are placeholders, so a second placeholder controlling
/// how placeholders grow would only be noise. When the economy pass lands, this
/// becomes a `CoresSettings` field.
const LAW_LEVEL_GROWTH_PERMYRIAD: i64 = 2_500;

fn grow_value(level_one_value: i64, steps: i64) -> i64 {
    if steps <= 0 {
        return level_one_value;
    }
    let growth = level_one_value.saturating_mul(LAW_LEVEL_GROWTH_PERMYRIAD * steps) / 10_000;
    level_one_value.saturating_add(growth)
}

/// A law's own upgrade scaling, before any bridge amplification.
pub fn law_value_at_level(level_one_value: i64, level: i64) -> i64 {
    grow_value(level_one_value, (level - 1).max(0))
}

/// The number an effect (or a passive modifier) actually lands with: the
/// authored value, grown by the law's upgrade level, then multiplied by the
/// bridge amplification.
///
/// This is the ONE function that applies amplification. Resonance and every
/// condition parameter deliberately never pass through here — that separation
/// is what makes acceptance #8 structural instead of a rule someone has to
/// remember.
pub fn law_effect_number(level_one_value: i64, level: i64, amplification: f64) -> i64 {
    let leveled = law_value_at_level(level_one_value, level) as f64;
    (leveled * amplification).round() as i64
}

/// Builds the live bridge charges from the character's bridges. A bridge is
/// live only when BOTH of its laws are slotted — an unslotted law is not on a
/// core, so it can neither fill a charge nor receive one.
///
/// The capacity and the amplification ceiling this combatant plays against are
/// baked in here, once: the Bridge Law socket moves both per player, and every
/// later read (resonance banking, amplification, the passive strip-and-refold)
/// takes them off the charges rather than off config.
pub fn build_law_bridge_charges(
    config: &GameConfig,
    cores: &CoresState,
    mods: &LawColumnMods,
) -> LawBridgeCharges {
    let mut bridges = Vec::new();
    for bridge in &cores.bridges {
        if slotted_law_template(config, cores, bridge.real_law_id).is_none()
            || slotted_law_template(config, cores, bridge.fantasy_law_id).is_none()
        {
            continue;
        }
        bridges.push(BridgeCharge::new(bridge.real_law_id, bridge.fantasy_law_id));
    }
    LawBridgeCharges::new(
        bridges,
        bridge_capacity_hundredths(config, mods),
        mods.bridge_amplification_cap(config.cores_settings.bridge_amplification_cap()),
    )
}

/// Capacity of one bridge direction for this build, in hundredths — the
/// configured whole-unit capacity, moved by the Bridge Law socket, scaled to the
/// accumulator's own unit.
pub fn bridge_capacity_hundredths(config: &GameConfig, mods: &LawColumnMods) -> i64 {
    mods.bridge_capacity(config.cores_settings.bridge_capacity())
        .saturating_mul(CHARGE_SCALE)
}

/// Law Power multiplier currently enjoyed by `law_id`: `1.0` for an unbridged
/// law, a law whose partner banked nothing, and every law at the very start of
/// a fight.
///
/// Priced off the combatant's own capacity and ceiling, so a `BL-03 Short Span`
/// build reaches its (lower) cap in fewer fires and a `BL-02 Deep Span` build
/// needs more — which is the whole trade the Bridge Law socket sells.
pub fn law_power_multiplier(charges: &LawBridgeCharges, law_id: LawTemplateId) -> f64 {
    configs::cores::law_power_multiplier_for(
        charges.delivered_units(law_id),
        charges.capacity_hundredths / CHARGE_SCALE,
        charges.amplification_cap_permyriad,
    )
}

fn slotted_law_template<'a>(
    config: &'a GameConfig,
    cores: &'a CoresState,
    law_id: LawTemplateId,
) -> Option<&'a LawTemplate> {
    let owned = cores.law(law_id)?;
    owned.slot_index?;
    law_template(config, law_id)
}

pub fn law_template(config: &GameConfig, law_id: LawTemplateId) -> Option<&LawTemplate> {
    config.laws.iter().find(|law| law.id == law_id)
}

/// Attribute deltas contributed by the laws that are actually doing something:
/// slotted, on the side that is currently up, at their current level, scaled by
/// whatever their bridge delivered at the last flip.
///
/// Laws of the inactive side contribute nothing (acceptance #3) — that is the
/// whole reason this is keyed on `active_side` rather than folded into the
/// shared attribute aggregation the way the core multiplier is.
///
/// An inactive law (`is_active == false`, the mana-dependent catalog entries)
/// contributes nothing either: it is content that exists but does not run.
pub fn active_law_attribute_deltas(
    config: &GameConfig,
    cores: &CoresState,
    active_side: WorldSide,
    charges: &LawBridgeCharges,
) -> BTreeMap<String, i64> {
    let mut deltas: BTreeMap<String, i64> = BTreeMap::new();
    for owned in cores.slotted_laws() {
        let Some(template) = law_template(config, owned.template_id) else {
            continue;
        };
        if template.side != active_side || !template.is_active {
            continue;
        }
        let amplification = law_power_multiplier(charges, owned.template_id);
        for modifier in &template.modifiers {
            let Some(attribute) = config
                .attributes
                .iter()
                .find(|attr| attr.id == modifier.attribute_id)
            else {
                continue;
            };
            let value = law_effect_number(modifier.base_value, owned.level.max(1), amplification);
            *deltas.entry(attribute.code.clone()).or_insert(0) += value;
        }
    }
    deltas
}

/// Why a bridge could not be created.
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
pub enum BridgeError {
    #[error("a law referenced by the bridge is not owned")]
    LawNotOwned,
    #[error("a law referenced by the bridge is not in a slot")]
    LawNotSlotted,
    #[error("both laws belong to the same core")]
    SameCore,
    #[error("this bridge already exists")]
    Duplicate,
    #[error("a law may belong to at most one bridge")]
    LawAlreadyBridged,
    #[error("bridge count would exceed min(core level) - 1")]
    BridgeLimitReached,
}

/// Maximum number of bridges one law may sit in.
///
/// **One, since laws v0.2** (plan §4). A law has exactly one partner, so the
/// build decision is which pairing to make rather than how many wires to run;
/// the asymmetry between a frequent `+1` source and a rare `+5` one is the
/// whole content of that choice.
pub const MAX_BRIDGES_PER_LAW: usize = 1;

/// Validates a would-be bridge and returns it side-normalized.
pub fn validate_new_bridge(
    config: &GameConfig,
    cores: &CoresState,
    law_a: LawTemplateId,
    law_b: LawTemplateId,
    extra_bridges: i64,
) -> Result<LawBridge, BridgeError> {
    let template_a = law_template(config, law_a).ok_or(BridgeError::LawNotOwned)?;
    let template_b = law_template(config, law_b).ok_or(BridgeError::LawNotOwned)?;
    let owned_a = cores.law(law_a).ok_or(BridgeError::LawNotOwned)?;
    let owned_b = cores.law(law_b).ok_or(BridgeError::LawNotOwned)?;

    if owned_a.slot_index.is_none() || owned_b.slot_index.is_none() {
        return Err(BridgeError::LawNotSlotted);
    }
    if template_a.side == template_b.side {
        return Err(BridgeError::SameCore);
    }

    let (real_law_id, fantasy_law_id) = if template_a.side == WorldSide::Real {
        (law_a, law_b)
    } else {
        (law_b, law_a)
    };
    let bridge = LawBridge {
        real_law_id,
        fantasy_law_id,
    };

    if cores.bridges.contains(&bridge) {
        return Err(BridgeError::Duplicate);
    }
    // Checked BEFORE the budget so re-wiring an already-bridged law reports the
    // reason the player can act on ("this law already has a partner") instead
    // of a budget message that would be wrong the moment the budget is large.
    for law_id in [law_a, law_b] {
        if cores.bridge_count_for_law(law_id) >= MAX_BRIDGES_PER_LAW {
            return Err(BridgeError::LawAlreadyBridged);
        }
    }
    if cores.bridges.len() as i64 + 1 > max_bridges(config, cores, extra_bridges) {
        return Err(BridgeError::BridgeLimitReached);
    }

    Ok(bridge)
}

#[cfg(test)]
mod tests {
    use super::*;
    use configs::tests_game_config::generate_game_config_for_tests;

    fn cores(real_level: i64, fantasy_level: i64) -> CoresState {
        CoresState {
            real_level,
            fantasy_level,
            ..Default::default()
        }
    }

    /// BAL-004: the first bridge opens exactly at Cores L2/L2 — the lower core
    /// binds, so no uneven pair below it allows a bridge.
    #[test]
    fn first_bridge_opens_exactly_at_l2_l2() {
        let config = generate_game_config_for_tests();
        assert_eq!(max_bridges(&config, &cores(1, 1), 0), 0);
        assert_eq!(max_bridges(&config, &cores(2, 1), 0), 0);
        assert_eq!(max_bridges(&config, &cores(1, 5), 0), 0);
        assert_eq!(max_bridges(&config, &cores(2, 2), 0), 1);
        assert_eq!(max_bridges(&config, &cores(3, 2), 0), 1);
    }

    /// BL-01 Extra Span is worth exactly one bridge at every level, and a
    /// negative modifier can never push the limit below zero.
    #[test]
    fn extra_span_adds_exactly_one_bridge() {
        let config = generate_game_config_for_tests();
        assert_eq!(max_bridges(&config, &cores(1, 1), 1), 1);
        assert_eq!(max_bridges(&config, &cores(2, 2), 1), 2);
        assert_eq!(max_bridges(&config, &cores(1, 1), -3), 0);
    }

    /// The `max_slot_level` clamp keeps the limit binding now that core levels
    /// are unbounded; without it the bridge limit would stop meaning anything.
    #[test]
    fn slot_ladder_clamps_unbounded_core_levels() {
        let config = generate_game_config_for_tests();
        let cap = config.cores_settings.max_slot_level();
        assert_eq!(max_bridges(&config, &cores(9999, 9999), 0), cap - 1);
        assert_eq!(max_bridges(&config, &cores(9999, 9999), 1), cap);
    }
}