overlord_event_system/gacha/

item_case.rs

use configs::game_config::GameConfig;
use essences::character_state::CharacterState;
use essences::item_case::ItemCasesSettingsByLevel;
use essences::items::{Item, ItemAttribute, ItemRarity, ItemRarityId, ItemTemplate};

use crate::BehaviorRegistry;
use crate::behaviors::items::ChestItemChooseCtx;
use crate::game_config_helpers::GameConfigLookup;
use rand::TryRng;
use rand::seq::IndexedRandom;
use rand::seq::SliceRandom;
use rand::{
    RngExt, SeedableRng,
    rngs::{StdRng, SysRng},
};

fn get_item_rarity_id(rng: &mut StdRng, level_settings: &ItemCasesSettingsByLevel) -> ItemRarityId {
    let total_weight: f64 = level_settings
        .rarity_weights
        .iter()
        .map(|rarity_weight| rarity_weight.weight)
        .sum();

    if total_weight < 1e-10 {
        panic!("Sum of weights is too low: {total_weight}");
    }

    let rnd_weight = rng.random_range(0.0..total_weight);

    let mut cumulative_weight = 0.0;
    for rarity_weight in &level_settings.rarity_weights {
        cumulative_weight += rarity_weight.weight;
        if rnd_weight < cumulative_weight {
            return rarity_weight.rarity_id;
        }
    }

    panic!("Failed to get item rarity id for weight {rnd_weight}");
}

/// `pending_items` are the items already rolled in the same batch open; they
/// are not in `character_state.inventory` yet, but the empty-slot guarantee
/// must treat their slots as filled.
pub fn try_open_item_case(
    character_state: &CharacterState,
    config: &GameConfig,
    seed: Option<u64>,
    behaviors: &BehaviorRegistry,
    pending_items: &[Item],
) -> anyhow::Result<Item> {
    let mut rng = StdRng::seed_from_u64(seed.unwrap_or(SysRng.try_next_u64()?));

    // Item override: mimic by code, or the first free slot of the current
    // inventory level. `None` means "no override" (roll by weights below).
    let item_template_id = crate::behaviors::items::chest_item_choose(&ChestItemChooseCtx {
        character: character_state,
        config,
        lookups: behaviors.lookups(),
        pending_items,
    })?;

    if let Some(item_template_id) = item_template_id {
        tracing::debug!("Got item_template_id from script: {item_template_id}");
        let Some(item_template) = config.item_template(item_template_id) else {
            anyhow::bail!("Failed to get item_template with id={}", item_template_id);
        };

        let Some(rarity) = config.item_rarity(item_template.rarity_id) else {
            anyhow::bail!(
                "Failed to get rarity with rarity_id={}",
                item_template.rarity_id
            );
        };

        let mut item = generate_item_from_template(
            item_template,
            rarity.clone(),
            character_state.character.character_level,
            crate::mechanics::balance::optional_attributes_for_chest_level(
                character_state.character.item_case_level,
            ),
            config,
            &mut rng,
        );
        // Guaranteed/custom drops (first item per empty slot, mimic custom
        // code) must be deterministic: no display power jitter. Finalization
        // still lifts power_bonus to keep the item's net contribution ≥ 1.
        item.power_bonus = 0;

        return Ok(item);
    };

    open_item_case(character_state, config, &mut rng)
}

pub fn open_item_case(
    character_state: &CharacterState,
    config: &GameConfig,
    rng: &mut rand::rngs::StdRng,
) -> anyhow::Result<Item> {
    let Some(level_settings) =
        config.item_case_settings_by_level(character_state.character.item_case_level)
    else {
        anyhow::bail!(
            "Failed to get case settings for item_case_level={}",
            character_state.character.item_case_level
        );
    };

    let rarity_id = get_item_rarity_id(rng, level_settings);

    let Some(rarity) = config.item_rarity(rarity_id) else {
        anyhow::bail!("Failed to get rarity with rarity_id={}", rarity_id);
    };

    let Some(inventory_level) = config
        .inventory_levels
        .iter()
        .rev()
        .find(|l| l.from_chapter_level <= character_state.character.current_chapter_level)
    else {
        anyhow::bail!(
            "Failed to get inventory level for current_chapter_level={}",
            character_state.character.current_chapter_level
        );
    };

    let chest_eligible_slots: Vec<_> = inventory_level
        .slots
        .iter()
        .map(|slot| slot.equipment_slot_key())
        .collect();
    let equipment_slot_key = *chest_eligible_slots.choose(rng).ok_or(anyhow::anyhow!(
        "No item slots specified for inventory_level={:?}",
        inventory_level
    ))?;

    let character_class_id = character_state.character.class;
    let class_match = |item: &&ItemTemplate| {
        item.required_class
            .is_none_or(|required| required == character_class_id)
    };

    let items_pool: Vec<&ItemTemplate> = {
        let result = config
            .items
            .iter()
            .filter(|item| {
                item.rarity_id == rarity.id
                    && item.equipment_slot_key() == equipment_slot_key
                    && !item.exclude_from_mimic
                    && class_match(item)
            })
            .collect::<Vec<_>>();

        if result.is_empty() {
            tracing::error!(
                "No items found for rarity_id={:?} and equipment_slot={:?}",
                rarity.id,
                equipment_slot_key
            );
            // Fallback: relax only the rolled logical slot, broadening to the
            // slots unlocked at the current inventory level. Keep the
            // exclude_from_mimic and class restrictions intact.
            // Artifact is always excluded from chest drops regardless of fallback.
            let result = config
                .items
                .iter()
                .filter(|item| {
                    item.rarity_id == rarity.id
                        && chest_eligible_slots.contains(&item.equipment_slot_key())
                        && !item.exclude_from_mimic
                        && class_match(item)
                })
                .collect::<Vec<_>>();
            if result.is_empty() {
                // A2-BAL-003 §3.2: the rarity catalog subdivides each family
                // into power tiers (Mythic I..V and so on). Those sub-tiers are
                // deliberately NOT given their own item templates — they share
                // their family's art, and authoring ~340 visually identical
                // templates to satisfy a lookup would be content churn for
                // nothing.
                //
                // Without this branch such a rarity does not degrade, it BAILS:
                // the chest open fails outright and the player gets no item. So
                // borrow the templates of the nearest rarity that has any,
                // measured by `order`, which puts a sub-tier on its own family
                // anchor. The rolled rarity is still what the item CARRIES —
                // only the template it is built from is borrowed — so `q`,
                // sell price and XP all follow the tier that was actually
                // rolled.
                let rolled_order = rarity.order;
                let mut by_distance: Vec<(u64, uuid::Uuid, &ItemTemplate)> = config
                    .items
                    .iter()
                    .filter(|item| {
                        chest_eligible_slots.contains(&item.equipment_slot_key())
                            && !item.exclude_from_mimic
                            && class_match(item)
                    })
                    .filter_map(|item| {
                        let order = config.item_rarity(item.rarity_id)?.order;
                        Some((order.abs_diff(rolled_order), item.id, item))
                    })
                    .collect();
                // Ties resolve by item id so the choice stays deterministic for
                // a given seed.
                by_distance.sort_by_key(|(distance, id, _)| (*distance, *id));
                let nearest = by_distance
                    .first()
                    .map(|(distance, _, _)| *distance)
                    .ok_or_else(|| {
                        anyhow::anyhow!("No items found for rarity_id={:?}", rarity.id)
                    })?;
                by_distance
                    .into_iter()
                    .take_while(|(distance, _, _)| *distance == nearest)
                    .map(|(_, _, item)| item)
                    .collect::<Vec<_>>()
            } else {
                result
            }
        } else {
            result
        }
    };

    let Some(&item_template) = items_pool.choose(rng) else {
        anyhow::bail!("Failed to choose random element from items");
    };

    let item = generate_item_from_template(
        item_template,
        rarity.clone(),
        character_state.character.character_level,
        crate::mechanics::balance::optional_attributes_for_chest_level(
            character_state.character.item_case_level,
        ),
        config,
        rng,
    );

    Ok(item)
}

/// Half-width of the per-item power jitter band, in raw combat-power units.
/// Each rolled item gets a uniform integer draw from `[-POWER_JITTER_HALF,
/// +POWER_JITTER_HALF]` using the session-seeded RNG already in scope, so:
///
/// - **Deterministic**: same session seed + same logical timestamp → same jitter.
/// - **Balance-neutral in expectation**: the distribution is symmetric around 0
///   (mean = 0), so population-average power is unchanged. Two items rolled from
///   the same template can differ by up to `2 × POWER_JITTER_HALF` power units.
/// - **Perceptible on early items**: at character level 1 the displayed
///   Combat-Power is in the low hundreds to low thousands; a ±5 shift is visible
///   to the player and guarantees the designer's requested "at least ±1" is met
///   everywhere on the curve. Late-game items (millions of power) absorb the ±5
///   as rounding noise — which is acceptable: the feature targets the feel
///   problem in the early game where each (rarity, type) cell has exactly ONE
///   eligible template.
/// - **Applied universally** (no per-item config flag per the project rule):
///   every rolled item gets the jitter, regardless of rarity or type.
pub const POWER_JITTER_HALF: i32 = 5;

/// `optional_count` is passed in rather than read off the template.
///
/// A2-BAL-003 §3.3 makes it a property of the CHEST — 0 at L1, 1 at L2..5, 2 at
/// L6+ — so the same sword rolls a different number of extras depending on where
/// it dropped. Ten templates also carried three, above the signed maximum of
/// two. Paths that are not a chest roll (bundles, cheats, bot fixtures) pass the
/// template's own count and keep their previous behaviour.
pub fn generate_item_from_template(
    template: &ItemTemplate,
    rarity: ItemRarity,
    level: i64,
    optional_count: u64,
    game_config: &GameConfig,
    rng: &mut rand::rngs::StdRng,
) -> Item {
    let mut attributes: Vec<ItemAttribute> = Vec::new();

    let mut optional_attribute_ids = template.attributes_settings.optional_attributes_ids.clone();
    optional_attribute_ids.shuffle(rng);
    optional_attribute_ids = optional_attribute_ids
        .into_iter()
        .take(optional_count as usize)
        .collect();

    for attribute in &game_config.attributes {
        if game_config
            .game_settings
            .required_attributes
            .contains(&attribute.id)
            || optional_attribute_ids.contains(&attribute.id)
        {
            attributes.push(ItemAttribute {
                attr_id: attribute.id,
                value: 0,
            });
        }
    }

    // Symmetric power jitter: uniform draw in [-POWER_JITTER_HALF, +POWER_JITTER_HALF].
    // Uses the in-scope seeded RNG so the result is deterministic per session-seed +
    // logical-timestamp. The range endpoint is inclusive on both sides.
    let power_bonus: i32 = rng.random_range((-POWER_JITTER_HALF)..=(POWER_JITTER_HALF));

    Item {
        id: uuid::Uuid::now_v7(),
        item_template_id: template.id,
        item_type: template.item_type,
        world_side: template.world_side,
        rarity,
        level,
        name: template.name.clone(),
        icon_url: template.icon_url.clone(),
        icon_path: template.icon_path.clone(),
        is_equipped: false,
        price: vec![],
        experience: 0,
        attributes,
        power_bonus,
        expires_at: None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::BehaviorRegistry;
    use crate::cases::try_finalize_item;
    use configs::tests_game_config::generate_game_config_for_tests;
    use essences::character_state::CharacterState;
    use rand::SeedableRng;

    /// Jitter assertions — verifies that the `power_bonus` field on rolled items
    /// satisfies all design constraints:
    ///
    /// 1. **Bounded**: each item's `power_bonus` is within `[-POWER_JITTER_HALF,
    ///    +POWER_JITTER_HALF]`.
    /// 2. **Both extremes are reachable**: over N seeds, at least one item with
    ///    `power_bonus == +POWER_JITTER_HALF` and one with `-POWER_JITTER_HALF`
    ///    are produced (proves the range is live, not dead-clamped).
    /// 3. **Mean-neutral in expectation**: the mean `power_bonus` across a large
    ///    population is close to 0 (|mean| ≤ 0.5), confirming the symmetric
    ///    distribution does not shift the population mean.
    /// 4. **Deterministic**: rolling the same seed twice produces the same
    ///    `power_bonus` — the jitter comes from the seeded RNG, not OS entropy.
    /// 5. **Perceptible**: at least one pair of same-template rolls at the same
    ///    level differs by ≥ 1 in `power_bonus` (the designer's minimum).
    #[test]
    fn test_power_jitter_bounded_mean_neutral_and_deterministic() {
        let config = generate_game_config_for_tests();
        let mut character_state = CharacterState::default();
        character_state.character.item_case_level = 1;

        let n = 10_000u64;
        let mut sum: i64 = 0;
        let mut saw_max = false;
        let mut saw_min = false;

        for seed in 0..n {
            let mut rng = StdRng::seed_from_u64(seed);
            let item = open_item_case(&character_state, &config, &mut rng)
                .expect("open_item_case should not fail");

            let pb = item.power_bonus;

            // 1. Bounded.
            assert!(
                (-POWER_JITTER_HALF..=POWER_JITTER_HALF).contains(&pb),
                "seed {seed}: power_bonus {pb} out of [{}, {}]",
                -POWER_JITTER_HALF,
                POWER_JITTER_HALF
            );

            sum += pb as i64;
            if pb == POWER_JITTER_HALF {
                saw_max = true;
            }
            if pb == -POWER_JITTER_HALF {
                saw_min = true;
            }
        }

        // 2. Both extremes reachable.
        assert!(
            saw_max,
            "power_bonus == +{POWER_JITTER_HALF} was never produced (range not live)"
        );
        assert!(
            saw_min,
            "power_bonus == -{POWER_JITTER_HALF} was never produced (range not live)"
        );

        // 3. Mean-neutral: |mean| ≤ 0.5 (should be essentially 0 for n=10000).
        let mean = sum as f64 / n as f64;
        assert!(
            mean.abs() < 0.5,
            "population mean {mean:.4} is too far from 0 — distribution is not symmetric"
        );

        // 4. Deterministic: same seed → same power_bonus.
        for seed in [0u64, 42, 999, 5000] {
            let pb_first = {
                let mut rng = StdRng::seed_from_u64(seed);
                open_item_case(&character_state, &config, &mut rng)
                    .expect("first roll")
                    .power_bonus
            };
            let pb_second = {
                let mut rng = StdRng::seed_from_u64(seed);
                open_item_case(&character_state, &config, &mut rng)
                    .expect("second roll")
                    .power_bonus
            };
            assert_eq!(
                pb_first, pb_second,
                "seed {seed}: power_bonus not deterministic ({pb_first} ≠ {pb_second})"
            );
        }

        // 5. Perceptible: at least one pair of consecutive seeds differs by ≥ 1.
        // (With a uniform draw over 11 values, this is virtually guaranteed in practice.)
        let pair_differs = (0u64..100).any(|seed| {
            let pb_a = {
                let mut rng = StdRng::seed_from_u64(seed);
                open_item_case(&character_state, &config, &mut rng)
                    .expect("roll A")
                    .power_bonus
            };
            let pb_b = {
                let mut rng = StdRng::seed_from_u64(seed + 1);
                open_item_case(&character_state, &config, &mut rng)
                    .expect("roll B")
                    .power_bonus
            };
            pb_a != pb_b
        });
        assert!(
            pair_differs,
            "no consecutive-seed pair differed in power_bonus — jitter is not perceptible"
        );
    }

    /// Verifies that after `try_finalize_item`, an item's effective power
    /// (attr-derived power + power_bonus) is always ≥ 1, even for items rolled at
    /// the lowest character level where the raw jitter could otherwise drive the
    /// net contribution to zero or negative.
    ///
    /// This is the floor guarantee added in Correction B of the post-playtest
    /// corrections: items must never contribute negative or zero power.
    #[test]
    fn test_finalized_item_effective_power_never_below_one() {
        let config = generate_game_config_for_tests();
        let behaviors = BehaviorRegistry::new(&config);
        let mut character_state = CharacterState::default();
        character_state.character.item_case_level = 1;

        for seed in 0u64..2000 {
            let mut rng = StdRng::seed_from_u64(seed);
            let mut item = open_item_case(&character_state, &config, &mut rng)
                .expect("open_item_case should not fail");

            // Apply the full finalization (attr values + power_bonus floor).
            try_finalize_item(
                &mut item,
                &config,
                &behaviors,
                &event_system::script::random::GameRng::new(StdRng::seed_from_u64(seed)),
            )
            .unwrap_or_else(|e| panic!("seed {seed}: try_finalize_item failed: {e}"));

            // Compute the item's standalone attribute power.
            let standalone_attr_power: i64 = {
                let mut attrs = crate::mechanics::balance::AttrMap::new();
                for attr in &item.attributes {
                    if let Some(a) = config.attribute(attr.attr_id) {
                        *attrs.entry(a.code.as_str().to_string()).or_insert(0.0) +=
                            attr.value as f64;
                    }
                }
                crate::mechanics::balance::power_from_attrs(&attrs)
            };

            let effective = standalone_attr_power + item.power_bonus as i64;
            assert!(
                effective >= 1,
                "seed {seed}: finalized item effective power {effective} < 1 \
                 (attr_power={standalone_attr_power}, power_bonus={})",
                item.power_bonus,
            );
        }
    }
}