feat(simulator): автономный симулятор баланса (#2967)

[kvirund]

Автономный симулятор баланса (issue #2967)

Что это

Отдельная сборочная цель mud-sim — исполняемый файл, который линкует тот же движок, что и circle, но запускается без сетевого слоя. Грузит мир, по YAML-сценарию программно создаёт участников, гоняет бой в цикле и пишет JSONL-журнал событий. Вся логика боя/магии/аффектов — настоящая, общая с продом; меняется только обвязка.

Цель — давать имплементеру и иммам данные о балансе, которые из живой игры не достать: матрицы урона по статам и владениям, сравнение классов, вклад чармисов, точные цифры на каждый swing, без шума регенерации и поведения игроков.

Сборка

mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DHAVE_YAML=ON ..
make -j$(($(nproc)/2)) mud-sim tests

-DHAVE_YAML=ON обязателен: симулятор парсит YAML-сценарии, движок при этом грузит мир в YAML-формате.

Подготовка мира

Симулятор работает с любым миром, переданным через -d. Один раз нужно подготовить:

mkdir -p small && cp -r ../lib/* small/ && cp -r ../lib.template/* small/
pip install --user --break-system-packages ruamel.yaml      # если ещё не стоит
python3 ../tools/converter/convert_to_yaml.py -i small -o small -f yaml

Базовый прогон: PC против моба

Минимальный сценарий — игрок-богатырь без оружия бьёт моба автоатакой:

seed: 42
rounds: 100
output: /tmp/sim.jsonl
attacker: { type: player, class: bogatyr, level: 30 }
victim:   { type: mob, vnum: 102 }

./mud-sim --config scen.yaml -d small

Параметры:

• seed — зерно RNG для воспроизводимости (по умолчанию 0).
• rounds — число боевых раундов; один раунд = одно pulse_violence.
• output — путь к выходному JSONL.
• attacker / victim — type: player или type: mob.

Каст заклинаний

Поле action переключает режим. По умолчанию melee (автоатака). Для каста:

attacker: { type: player, class: koldun, level: 30 }
victim:   { type: mob, vnum: 102 }
action:   { type: cast, spell: шаровая молния }

Симулятор каждый раунд ждёт kGlobalCooldown и wait_state после прошлого спелла, потом вызывает движковый CastSpell (минуя DoCast, чтобы избежать ветки отложенного каста через SetCast). Память заклинаний и wait_state уважаются как в реальной игре.

Имя заклинания — точно как в lib/cfg/spells.xml (русское). Если класс знает это заклинание на этом уровне — каст пройдёт.

Чармисы / поднятая нежить

Никакого kCharm не кастуется. Подчинённые описываются прямо в участнике и приходят с ним уже лояльными:

attacker:
  type: player
  class: kudesnik
  level: 30
  pets:
    - { vnum: 4001 }
    - { vnum: 4002, stats: { max_hit: 800 } }
victim: { type: mob, vnum: 102 }

Каждый pet получает EAffect::kCharmed, set_master(owner), add_follower, SetFighting(pet, victim) — ровно тот же setup, что делает движок в конце kCharm. Cleanup в порядке pet-then-owner.

Damage от чармиса в JSONL помечается attacker_is_charmie: true и полем attacker_master_name.

PvP

type: player для обоих участников:

attacker: { type: player, class: bogatyr, level: 30 }
victim:   { type: player, class: lekar, level: 30 }

Работает через тот же SpawnParticipant / SetFighting, без отдельной ветки кода.

Mob vs Mob

«Спарринг мобов» — оба type: mob:

attacker: { type: mob, vnum: 101 }
victim:   { type: mob, vnum: 102 }

Перебивка статов и HP

Любой стат (str/dex/con/int/wis/cha) и max_hit можно переопределить:

attacker:
  type: player
  class: koldun
  level: 30
  stats:
    wis: 80
    int: 60
    max_hit: 1500

Что не указано — остаётся как назначил движок: для PC CharacterBuilder.make_basic_player ставит все статы по 25, для моба — берётся прототип. max_hit, если задан — побеждает дефолтную выдачу INT_MAX/4 (которую симулятор иначе ставит, чтобы участник пережил все раунды).

Стартовая экипировка

attacker:
  type: player
  class: bogatyr
  level: 30
  inventory: [111, 207]

Каждый предмет создаётся через world_objects.create_from_prototype_by_vnum и автонадевается:

• оружие (kWeapon): kWield → kBoth → kHold (как equip_start_outfit для noob outfits);
• всё остальное: через find_eq_pos.

Что не нашло слот — остаётся в инвентаре. После надевания пересчитывается affect_total, чтобы applies от предмета (например, kPhysicDamagePercent от меча) попали в add_abils.

Алиасы имён классов

Чтобы YAML был ASCII-friendly, поддерживаются латинские и английские алиасы вместо русских имён из pc_*.xml:

класс	латиница	английский
богатырь	bogatyr	warrior
наёмник	naemnik	assassin
кудесник	kudesnik	charmer
колдун	koldun	conjurer
лекарь	lekar	sorcerer / healer
охотник	ohotnik	ranger
волхв	volkhv	magus
дружинник	druzhinnik	guard
купец	kupets	merchant
чернокнижник	chernoknizhnik	necromancer
витязь	vityaz	paladine / paladin
тать	tat	thief
кузнец	kuznets	vigilant / smith
волшебник	volshebnik	wizard

Русские имена тоже работают, если YAML записан в KOI8-R.

Матричный прогон по статам

Главный кейс из задачи — таблица «урон vs значение стата». Достаточно прогнать одинаковый сценарий N раз с разными значениями и подать вывод в tools/balance_simulator_matrix.py:

for w in 10 20 30 40 50 60 70 80; do
  cat > /tmp/scen.yaml <<EOF
seed: 42
rounds: 50
output: /tmp/sim_wis_$w.jsonl
attacker: { type: player, class: koldun, level: 30, stats: { wis: $w } }
victim:   { type: mob, vnum: 102 }
action:   { type: cast, spell: шаровая молния }
EOF
  iconv -f utf-8 -t koi8-r /tmp/scen.yaml | sponge /tmp/scen.yaml
  ./mud-sim --config /tmp/scen.yaml -d small
done

python3 ../tools/balance_simulator_matrix.py wisdom \
  10:/tmp/sim_wis_10.jsonl 20:/tmp/sim_wis_20.jsonl ... 80:/tmp/sim_wis_80.jsonl \
  /tmp/lightning_by_wis.png

На выходе график «средний урон за каст vs мудрость», на котором видно плато до wisdom 30 и линейный рост дальше — настоящая балансная формула шаровой молнии.

События в JSONL

Один JSON на строку, ключи в фиксированном порядке (ts, name, потом атрибуты по алфавиту). Совместимо с OTLP log record schema.

name	когда эмитится	ключевые поля
damage	каждый успешный удар, в Damage::Process после set_hit	attacker_name, victim_name, dam, real_dam, over_dam, victim_hp_after, dmg_type, crit, spell_id, skill_id, attacker_is_charmie, attacker_master_name
miss	каждый промах автоатаки, в hit()	attacker_name, victim_name, reason ∈ {auto_5pct, level_diff, thac0_roll}
affect_added	в affect_to_char после affect_total	target_name, spell_id, duration, modifier, location, bitvector
affect_removed	в RemoveAffectFromChar перед AffectRemove	то же
char_state	старт боя + после каждого раунда для всех ролей (attacker, victim, attacker_pet_N, victim_pet_N)	role, target_name, hp, max_hp, move, max_move, position, in_room, spellpower_add_pct, physdam_add_pct, affects_count, aff_silence, aff_charmed, aff_sleep
round	конец каждого раунда	round, attacker_*, victim_*, hp_before, hp_after, damage_observed, victim_alive

Этого достаточно, чтобы внешний скрипт восстановил состояние любого участника на любой момент боя (replay-режим).

Глобальный EventSink в движке

MUD::observability::GlobalEventSink() + SetGlobalEventSink(EventSink*) — точка подключения для боевого/магического/affects-кода. По умолчанию возвращается NoOp (нулевая регрессия в проде). Симулятор ставит FileEventSink на время прогона и сбрасывает в nullptr на выходе (включая catch-ветку).

Реализация FileEventSink спрятана за фабрикой MakeFileEventSink(path) — публичен только интерфейс EventSink.

Воспроизводимость

./mud-sim --config scen.yaml -d small  # выдаёт /tmp/sim.jsonl
cp /tmp/sim.jsonl /tmp/sim_first.jsonl
./mud-sim --config scen.yaml -d small
diff -I '"ts":' /tmp/sim_first.jsonl /tmp/sim.jsonl   # пусто

Игнорируется ts (wall-clock), всё остальное побайтно совпадает: те же броски, те же попадания, тот же урон. Управляется через SetRandomSeed — единственный экземпляр std::mt19937 (Random::rnd), через который идут все боевые броски (number(), RollDices(), BernoulliTrial(), GaussIntNumber()).

Визуализаторы

• tools/balance_simulator_viz.py — обзор нескольких прогонов: stacked dpr (master melee + master spell + pets), hit rate, кумулятивный урон по реальному таймлайну.
• tools/balance_simulator_matrix.py — линейный график «средний урон за каст vs значение варьируемого стата», для матричных прогонов.

python3 tools/balance_simulator_viz.py /tmp/sim_*.jsonl --output /tmp/demo.png

Новые модульные тесты (23)

• tests/random.seed.cpp — детерминизм RNG.
• tests/file_event_sink.cpp — формат JSONL, escape, порядок ключей.
• tests/character_builder.cpp — сеттеры и make_basic_player.
• tests/event_sink_global.cpp — NoOp-дефолт, рутинг через установленный sink, сброс.
• tests/scenario_loader.cpp — 16 тестов: парсер YAML, action-варианты, ошибки, PvP, mob-vs-mob, статовые перебивки, чармисы, inventory.

Где какие правки

• src/utils/random.{h,cpp} — SetRandomSeed.
• src/engine/observability/event_sink.{h,cpp}, file_event_sink.cpp — приёмник событий, фабрика, KOI8-R → UTF-8 конвертер для JSON.
• src/engine/entities/character_builder.{h,cpp} — перенос из tests/, расширение под симулятор: статы, skills/feats/spells класса, размещение в комнате.
• src/gameplay/mechanics/damage.cpp — точка эмиссии damage в Damage::Process.
• src/gameplay/fight/fight_hit.cpp — точка эмиссии miss в hit().
• src/gameplay/affects/affect_data.cpp — точки эмиссии affect_added / affect_removed.
• src/simulator/main.cpp, scenario.h, scenario_loader.{h,cpp}, scenario_runner.{h,cpp} — собственно симулятор.
• src/simulator/README.md — документация.
• tools/balance_simulator_viz.py, tools/balance_simulator_matrix.py — построение графиков.

Известные ограничения

• Каст идёт через прямой CastSpell (минуя DoCast), потому что DoCast в бою уходит в отложенный путь через SetCast/mem_queue, и magic damage начинает прилетать через несколько pulse, плохо согласуясь с понятием «раунд». Для синтетического PC в одной арене такой обход адекватен; в живой игре поведение другое.
• Арена — это room rnum 1 из загруженного мира. С неё временно снимаются kNoMagic и kPeaceful на время прогона и возвращаются на выходе.
• После affect_total синтетический PC оказывается в position 3 (kSit/Rest); симулятор принудительно ставит kStand после ВСЕХ вызовов affect_total, иначе движок отказывается кастовать.
• Свой синтетический загрузчик мира (одна стерильная комната без зависимости от lib.template) не делается — текущая работа со small достаточна.
• Способности (feats) выдаются по «верхнему потолку». PC получает все способности класса, доступные на его уровне и реморте: и врождённые (inborn=1), и автоматические по уровню (inborn=0 slot=0), и слотовые (inborn=0 slot>=1) — последние без оглядки на лимит слотов. То есть симулятор играет «идеально прокачанным» персонажем, а реальный игрок ограничен числом слотов и должен выбирать. Числа в матрицах — это «верхняя граница dpr класса при идеальной прокачке».
• Родовые способности (race feats) не выдаются. Раса у синтетического PC не задана (default), так что родовые feats игнорируются. Если для класса есть существенные родовые — в реальной игре они дадут плюс сверху симуляторных чисел. Расширение YAML под race: <название> — отдельный пункт.
• OtlpLogsSink отложен (изначально планировался поверх OtelLogSender, пользователь снизил приоритет).

Контрольные прогоны

сценарий	dpr	примечание
богатырь без оружия	65.7	kPunch + kLeftHit (вторая рука)
богатырь + алебарда (vnum 111)	82.1	+25% от оружия
кудесник + кислота	548.5	spell-урон, spellpower_add_pct = 0
кудесник + 2 чармиса (101, 105)	581.1	+33 dpr от двух слабых чармисов
колдун + кислота	814.5	kPowerMagic +50% подтверждён ровно
колдун + шаровая молния, wisdom 30 → 80	619 → 890	плато до 30, линейный рост дальше