overlord_event_system/mechanics/

plinko.rs

//! Серверная механика доски Plinko.
//!
//! Путь шарика решает сервер: он выбирает физический слот под редкость
//! выданного предмета, катит `rows` шагов Left/Right своим сидом и отдаёт
//! путь клиенту событием `PlinkoBallDropped`. Колышки, задетые по дороге,
//! выводятся из пути детерминированно и начисляют постоянные прибавки к
//! статам — тоже на сервере.
//!
//! Клиент не участвует ни в одном из этих решений: путь определяет слот, а
//! слот определяет редкость награды, поэтому клиентский путь означал бы
//! клиента, выбирающего себе награду.

use configs::plinko::PlinkoSettings;
use essences::item_case::ItemCaseRarityWeight;
use essences::items::{AttributeId, ItemRarityId};
use essences::plinko::{PlinkoDirection, PlinkoPinBonusesMap, pins_touched_by_path};
use rand::RngExt;
use rand::rngs::StdRng;
use rand::seq::SliceRandom;

/// Одна начисленная прибавка — для логов и тестов.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GrantedPinBonus {
    pub attribute_id: AttributeId,
    /// Сколько реально начислено (0, если упёрлись в потолок).
    pub granted: i64,
    /// Значение накопленного бонуса после начисления.
    pub total: i64,
}

/// Runtime-раскладка физических слотов для отображения и серверного пути.
///
/// Авторская раскладка задаёт только количество физических слотов каждой
/// редкости. В runtime эти вхождения сортируются по фактическим весам уровня:
/// самое частое оказывается ближе всего к центру, самое редкое — у краёв.
/// При равных весах исходная близость к центру и номер слота сохраняют
/// раскладку стабильной. Клиент воспроизводит тот же простой порядок.
pub fn runtime_slot_layout(
    settings: &PlinkoSettings,
    chest_level: i64,
    rarity_weights: &[ItemCaseRarityWeight],
) -> Vec<(i64, ItemRarityId)> {
    let Some(layout) = settings.layout_for_level(chest_level) else {
        return Vec::new();
    };

    let doubled_distance = |slot: i64| (2 * slot - settings.rows).abs();
    let weight_of = |rarity_id: ItemRarityId| {
        rarity_weights
            .iter()
            .find(|weight| weight.rarity_id == rarity_id)
            .map(|weight| weight.weight)
            .unwrap_or(0.0)
    };

    let mut occurrences: Vec<_> = (0..settings.slot_count())
        .filter_map(|slot| {
            layout
                .rarity_for_slot(slot)
                .map(|rarity_id| (rarity_id, slot))
        })
        .collect();
    occurrences.sort_by(|(rarity_a, slot_a), (rarity_b, slot_b)| {
        weight_of(*rarity_b)
            .total_cmp(&weight_of(*rarity_a))
            .then_with(|| doubled_distance(*slot_a).cmp(&doubled_distance(*slot_b)))
            .then_with(|| slot_a.cmp(slot_b))
    });

    let mut physical_slots: Vec<_> = (0..settings.slot_count()).collect();
    physical_slots.sort_by_key(|slot| (doubled_distance(*slot), *slot));

    let mut assigned: Vec<_> = occurrences
        .into_iter()
        .zip(physical_slots)
        .map(|((rarity_id, _), physical_slot)| (physical_slot, rarity_id))
        .collect();
    assigned.sort_by_key(|(slot, _)| *slot);
    assigned
}

/// Все runtime-слоты уровня `chest_level`, несущие редкость выданного
/// предмета.
///
/// Пустой результат означает сломанный конфиг, а не штатный случай:
/// раскладка каждого уровня обязана покрывать все редкости, выпадающие на
/// этом уровне (`GameConfig::validate`). Подстановки чужой редкости здесь
/// больше нет: пока раскладка была одна на всю игру, непокрытая редкость
/// роняла шарик в слот с ближайшей меньшей подписью, и с 33-го уровня
/// сундука подпись под шариком не совпадала с наградой ни разу.
pub fn slots_for_rarity(
    settings: &PlinkoSettings,
    chest_level: i64,
    rarity_weights: &[ItemCaseRarityWeight],
    rarity_id: ItemRarityId,
) -> Vec<i64> {
    runtime_slot_layout(settings, chest_level, rarity_weights)
        .into_iter()
        .filter_map(|(slot, slot_rarity)| (slot_rarity == rarity_id).then_some(slot))
        .collect()
}

/// Катит путь шарика под редкость выданного предмета.
///
/// Ровно `rows` шагов; число шагов `Right` равно индексу целевого слота,
/// поэтому шарик гарантированно приземляется в слот, подписанный редкостью
/// этого предмета на доске уровня `chest_level`. Порядок шагов перемешивается
/// тем же `rng`, что и остальная серверная случайность события, — путь
/// воспроизводим по сиду сессии.
///
/// Ошибка означает сломанный конфиг (нет раскладки на уровень или редкость не
/// покрыта), а не штатную ситуацию.
pub fn roll_path_for_rarity(
    settings: &PlinkoSettings,
    chest_level: i64,
    rarity_weights: &[ItemCaseRarityWeight],
    rarity_id: ItemRarityId,
    rng: &mut StdRng,
) -> anyhow::Result<Vec<PlinkoDirection>> {
    let slots = slots_for_rarity(settings, chest_level, rarity_weights, rarity_id);
    if slots.is_empty() {
        anyhow::bail!(
            "No plinko slot on the chest level {chest_level} board matches item rarity {rarity_id}"
        );
    }

    let target_slot = slots[rng.random_range(0..slots.len())];
    path_to_slot(settings.rows, target_slot, rng)
}

/// Путь ровно из `rows` шагов, приводящий в слот `target_slot`.
pub fn path_to_slot(
    rows: i64,
    target_slot: i64,
    rng: &mut StdRng,
) -> anyhow::Result<Vec<PlinkoDirection>> {
    if rows <= 0 {
        anyhow::bail!("Plinko rows must be positive, got {rows}");
    }
    if target_slot < 0 || target_slot > rows {
        anyhow::bail!("Plinko slot {target_slot} is outside 0..={rows}");
    }

    let mut path = Vec::with_capacity(rows as usize);
    path.resize(target_slot as usize, PlinkoDirection::Right);
    path.resize(rows as usize, PlinkoDirection::Left);
    path.shuffle(rng);
    Ok(path)
}

/// Начисляет постоянные прибавки за колышки, задетые путём (BAL-021).
///
/// Прибавка считается в микроединицах: `вес колышка × scale активного
/// транша`, где активный транш — самый ранний уровень сундука, чей потолок
/// по этой оси ещё не набран. Накопленное значение не превышает потолок
/// этого транша; упёрлись — колышек не даёт ничего, частичное добирание
/// остатка допускается.
pub fn apply_pin_bonuses(
    settings: &PlinkoSettings,
    chest_level: i64,
    path: &[PlinkoDirection],
    bonuses: &mut PlinkoPinBonusesMap,
) -> Vec<GrantedPinBonus> {
    let mut granted = Vec::new();
    for pin in pins_touched_by_path(path) {
        let Some(bonus) = settings.pin_bonus(pin.row, pin.column) else {
            continue;
        };

        let current = bonuses.get(&bonus.attribute_id);
        // BAL-021: the pin's weight is priced by the tranche the axis is
        // currently filling — the oldest one still short of its cap, so a
        // player who outran the board catches the skipped capacity up at the
        // step of the level that opened it.
        let Some(tranche) = settings.active_tranche(chest_level, bonus.attribute_id, current)
        else {
            tracing::error!(
                "Plinko pin ({}, {}) pays attribute {} but chest level {chest_level} has no                  tranche for it; skipping",
                pin.row,
                pin.column,
                bonus.attribute_id
            );
            continue;
        };

        let gain_micro = bonus.value.saturating_mul(tranche.scale_micro);
        let total = current.saturating_add(gain_micro).min(tranche.cap_micro);
        let delta = (total - current).max(0);
        if delta > 0 {
            bonuses.set(bonus.attribute_id, total);
        }
        granted.push(GrantedPinBonus {
            attribute_id: bonus.attribute_id,
            granted: delta,
            total: current.max(total),
        });
    }
    granted
}

#[cfg(test)]
mod tests {
    use super::*;
    use configs::plinko::{
        PLINKO_MICRO, PlinkoAxisTranche, PlinkoLevelSlotLayout, PlinkoPinBonus, PlinkoSlotGroup,
        PlinkoTranche,
    };
    use configs::validated_types::NonEmptyVec;
    use essences::plinko::slot_index_for_path;
    use rand::SeedableRng;
    use uuid::Uuid;

    fn settings_with_rows(rows: i64) -> PlinkoSettings {
        PlinkoSettings {
            rows,
            slot_layouts: NonEmptyVec::new(vec![PlinkoLevelSlotLayout {
                chest_level: 1,
                slot_groups: NonEmptyVec::new(vec![PlinkoSlotGroup {
                    from_slot: 0,
                    to_slot: rows,
                    rarity_id: Uuid::nil(),
                    is_locked: false,
                }]),
            }]),
            pin_bonuses: vec![],
            tranches: vec![],
        }
    }

    fn settings_with_slots(rarities: &[Uuid]) -> PlinkoSettings {
        let rows = rarities.len() as i64 - 1;
        PlinkoSettings {
            rows,
            slot_layouts: NonEmptyVec::new(vec![PlinkoLevelSlotLayout {
                chest_level: 1,
                slot_groups: NonEmptyVec::new(
                    rarities
                        .iter()
                        .enumerate()
                        .map(|(slot, rarity_id)| PlinkoSlotGroup {
                            from_slot: slot as i64,
                            to_slot: slot as i64,
                            rarity_id: *rarity_id,
                            is_locked: false,
                        })
                        .collect(),
                ),
            }]),
            pin_bonuses: vec![],
            tranches: vec![],
        }
    }

    fn rarity_weights(entries: &[(Uuid, f64)]) -> Vec<ItemCaseRarityWeight> {
        entries
            .iter()
            .map(|(rarity_id, weight)| ItemCaseRarityWeight {
                rarity_id: *rarity_id,
                weight: *weight,
            })
            .collect()
    }

    /// One axis, one tranche per chest level: `caps` is the cap of each level
    /// in whole stat points, `scale` the price of one unit of pin weight.
    fn tranches(attribute: Uuid, caps: &[i64], scale: i64) -> Vec<PlinkoTranche> {
        caps.iter()
            .enumerate()
            .map(|(index, cap)| PlinkoTranche {
                chest_level: index as i64 + 1,
                axes: vec![PlinkoAxisTranche {
                    attribute_id: attribute,
                    cap_micro: cap * PLINKO_MICRO,
                    scale_micro: scale,
                }],
            })
            .collect()
    }

    #[test]
    fn path_has_one_step_per_row_and_lands_in_the_requested_slot() {
        let mut rng = StdRng::seed_from_u64(7);
        for target in 0..=7 {
            let path = path_to_slot(7, target, &mut rng).unwrap();
            assert_eq!(path.len(), 7, "one step per row");
            assert_eq!(slot_index_for_path(&path), target);
        }
    }

    #[test]
    fn same_seed_gives_the_same_path() {
        let first = path_to_slot(7, 3, &mut StdRng::seed_from_u64(1234)).unwrap();
        let second = path_to_slot(7, 3, &mut StdRng::seed_from_u64(1234)).unwrap();
        assert_eq!(first, second);
    }

    #[test]
    fn runtime_layout_puts_heavier_occurrences_closer_to_the_centre() {
        let high = Uuid::from_u128(1);
        let medium = Uuid::from_u128(2);
        let low = Uuid::from_u128(3);
        let settings = settings_with_slots(&[high, medium, medium, low, low, low, low, low]);
        let weights = rarity_weights(&[(high, 10.0), (medium, 5.0), (low, 1.0)]);

        let runtime: Vec<_> = runtime_slot_layout(&settings, 1, &weights)
            .into_iter()
            .map(|(_, rarity)| rarity)
            .collect();

        assert_eq!(runtime, vec![low, low, medium, high, medium, low, low, low]);
        assert_eq!(runtime.iter().filter(|&&rarity| rarity == high).count(), 1);
        assert_eq!(
            runtime.iter().filter(|&&rarity| rarity == medium).count(),
            2
        );
        assert_eq!(runtime.iter().filter(|&&rarity| rarity == low).count(), 5);
    }

    #[test]
    fn equal_weights_preserve_the_authored_slot_order() {
        let first = Uuid::from_u128(1);
        let second = Uuid::from_u128(2);
        let authored = vec![first, second, first, second];
        let settings = settings_with_slots(&authored);
        let weights = rarity_weights(&[(first, 5.0), (second, 5.0)]);

        let runtime: Vec<_> = runtime_slot_layout(&settings, 1, &weights)
            .into_iter()
            .map(|(_, rarity)| rarity)
            .collect();

        assert_eq!(runtime, authored);
    }

    /// Раскладка берётся под уровень сундука: одна и та же редкость на разных
    /// уровнях падает в разные слоты.
    #[test]
    fn the_board_of_the_players_chest_level_decides_the_slot() {
        let rarity = Uuid::from_u128(7);
        let other = Uuid::from_u128(8);
        let weights = rarity_weights(&[(rarity, 10.0), (other, 1.0)]);
        let mut settings = settings_with_rows(3);
        settings.slot_layouts = NonEmptyVec::new(vec![
            PlinkoLevelSlotLayout {
                chest_level: 1,
                slot_groups: NonEmptyVec::new(vec![PlinkoSlotGroup {
                    from_slot: 0,
                    to_slot: 3,
                    rarity_id: rarity,
                    is_locked: false,
                }]),
            },
            PlinkoLevelSlotLayout {
                chest_level: 2,
                slot_groups: NonEmptyVec::new(vec![
                    PlinkoSlotGroup {
                        from_slot: 0,
                        to_slot: 2,
                        rarity_id: other,
                        is_locked: false,
                    },
                    PlinkoSlotGroup {
                        from_slot: 3,
                        to_slot: 3,
                        rarity_id: rarity,
                        is_locked: false,
                    },
                ]),
            },
        ]);

        let mut rng = StdRng::seed_from_u64(11);
        for _ in 0..20 {
            let level_two = roll_path_for_rarity(&settings, 2, &weights, rarity, &mut rng).unwrap();
            assert_eq!(
                slot_index_for_path(&level_two),
                1,
                "the frequent rarity moves from authored slot 3 to the runtime centre"
            );
            let level_one = roll_path_for_rarity(&settings, 1, &weights, rarity, &mut rng).unwrap();
            assert!((0..=3).contains(&slot_index_for_path(&level_one)));
        }
    }

    /// Непокрытая редкость и уровень без раскладки — сломанный конфиг, а не
    /// штатный путь: подстановки чужой редкости больше нет.
    #[test]
    fn an_uncovered_rarity_is_an_error_not_a_fallback() {
        let settings = settings_with_rows(3);
        let weights = rarity_weights(&[(Uuid::nil(), 1.0)]);

        assert!(
            roll_path_for_rarity(
                &settings,
                1,
                &weights,
                Uuid::from_u128(42),
                &mut StdRng::seed_from_u64(1)
            )
            .is_err(),
            "a rarity with no slot on that level must fail loudly"
        );
        assert!(
            roll_path_for_rarity(
                &settings,
                2,
                &weights,
                Uuid::nil(),
                &mut StdRng::seed_from_u64(1)
            )
            .is_err(),
            "a chest level with no layout must fail loudly"
        );
    }

    #[test]
    fn cap_stops_further_grants() {
        let attribute = Uuid::from_u128(1);
        let mut settings = settings_with_rows(2);
        settings.pin_bonuses = vec![PlinkoPinBonus {
            row: 0,
            column: 0,
            attribute_id: attribute,
            value: 4,
        }];
        // One chest level, cap 6 whole points, one point per unit of weight.
        settings.tranches = tranches(attribute, &[6], PLINKO_MICRO);

        let mut bonuses = PlinkoPinBonusesMap::default();
        let path = vec![PlinkoDirection::Left, PlinkoDirection::Left];

        apply_pin_bonuses(&settings, 1, &path, &mut bonuses);
        assert_eq!(bonuses.get(&attribute), 4 * PLINKO_MICRO);

        // Второе касание добирает только остаток до потолка.
        apply_pin_bonuses(&settings, 1, &path, &mut bonuses);
        assert_eq!(bonuses.get(&attribute), 6 * PLINKO_MICRO);

        // Третье не даёт ничего.
        let granted = apply_pin_bonuses(&settings, 1, &path, &mut bonuses);
        assert_eq!(bonuses.get(&attribute), 6 * PLINKO_MICRO);
        assert_eq!(granted.first().map(|g| g.granted), Some(0));
    }

    /// BAL-021: a chest upgrade opens the NEXT tranche, and the axis keeps
    /// filling at the price of the tranche it is on — not at the newest one.
    #[test]
    fn a_new_chest_level_opens_the_next_tranche_at_its_own_price() {
        let attribute = Uuid::from_u128(1);
        let mut settings = settings_with_rows(2);
        settings.pin_bonuses = vec![PlinkoPinBonus {
            row: 0,
            column: 0,
            attribute_id: attribute,
            value: 1,
        }];
        // L1 pays a whole point per touch up to 2; L2 adds one more point of
        // room but pays a tenth of a point per touch.
        settings.tranches = vec![
            PlinkoTranche {
                chest_level: 1,
                axes: vec![PlinkoAxisTranche {
                    attribute_id: attribute,
                    cap_micro: 2 * PLINKO_MICRO,
                    scale_micro: PLINKO_MICRO,
                }],
            },
            PlinkoTranche {
                chest_level: 2,
                axes: vec![PlinkoAxisTranche {
                    attribute_id: attribute,
                    cap_micro: 3 * PLINKO_MICRO,
                    scale_micro: PLINKO_MICRO / 10,
                }],
            },
        ];

        let mut bonuses = PlinkoPinBonusesMap::default();
        let path = vec![PlinkoDirection::Left, PlinkoDirection::Left];

        // Two touches fill L1 exactly.
        apply_pin_bonuses(&settings, 2, &path, &mut bonuses);
        apply_pin_bonuses(&settings, 2, &path, &mut bonuses);
        assert_eq!(bonuses.get(&attribute), 2 * PLINKO_MICRO);

        // The third touch is priced by L2, so it moves a tenth of a point —
        // and stays visible only because the aggregate is fixed-point.
        apply_pin_bonuses(&settings, 2, &path, &mut bonuses);
        assert_eq!(
            bonuses.get(&attribute),
            2 * PLINKO_MICRO + PLINKO_MICRO / 10
        );
        assert_eq!(
            configs::plinko::PlinkoSettings::whole_from_micro(bonuses.get(&attribute)),
            2,
            "combat reads whole points; the tail accumulates"
        );
    }

    /// The catch-up rule: a player who upgraded past a tranche without filling
    /// it keeps filling THAT tranche first, at its price.
    #[test]
    fn a_skipped_tranche_is_caught_up_before_the_current_one() {
        let attribute = Uuid::from_u128(1);
        let mut settings = settings_with_rows(2);
        settings.pin_bonuses = vec![PlinkoPinBonus {
            row: 0,
            column: 0,
            attribute_id: attribute,
            value: 1,
        }];
        settings.tranches = vec![
            PlinkoTranche {
                chest_level: 1,
                axes: vec![PlinkoAxisTranche {
                    attribute_id: attribute,
                    cap_micro: 5 * PLINKO_MICRO,
                    scale_micro: PLINKO_MICRO,
                }],
            },
            PlinkoTranche {
                chest_level: 2,
                axes: vec![PlinkoAxisTranche {
                    attribute_id: attribute,
                    cap_micro: 6 * PLINKO_MICRO,
                    scale_micro: PLINKO_MICRO / 100,
                }],
            },
        ];

        // The player is on chest level 2 having banked nothing at all.
        let mut bonuses = PlinkoPinBonusesMap::default();
        let path = vec![PlinkoDirection::Left, PlinkoDirection::Left];
        apply_pin_bonuses(&settings, 2, &path, &mut bonuses);

        assert_eq!(
            bonuses.get(&attribute),
            PLINKO_MICRO,
            "the unfilled L1 tranche pays first, at L1's price"
        );
    }

    #[test]
    fn pins_without_a_configured_bonus_grant_nothing() {
        let settings = settings_with_rows(3);
        let mut bonuses = PlinkoPinBonusesMap::default();
        let path = vec![
            PlinkoDirection::Right,
            PlinkoDirection::Left,
            PlinkoDirection::Right,
        ];

        assert!(apply_pin_bonuses(&settings, 1, &path, &mut bonuses).is_empty());
        assert!(bonuses.is_empty());
    }
}