TheDeclineOfWarriors/docs/gameplay/attribute-stats-visibility-mvp.md

# Attribute Stats Visibility MVP

## Purpose

Этот документ фиксирует, какие derived stats должны быть видимы игроку в MVP, какие можно показывать только в расширенном виде, а какие должны оставаться внутренними runtime-параметрами.

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

## Related Docs

- `docs/gameplay/attribute-system-gdd.md`
- `docs/gameplay/attribute-reference.md`
- `docs/gameplay/stat-catalog-mvp.md`
- `docs/gameplay/combat-resolution-gdd.md`

## UI Philosophy

Для MVP игрок должен видеть минимум информации, но этот минимум должен быть полезным.

- игрок должен понимать, что прокачка реально меняет боевую эффективность
- экран характеристик не должен превращаться в таблицу внутренних коэффициентов
- основные сложные расчеты должны оставаться под капотом
- вторичные и технические derived stats лучше не показывать, если они не помогают принимать решения в билде

Главный принцип: отображать только те числа, которые игрок может быстро связать со своим ощущением в бою.

## Performance Philosophy

Система статов должна быть легковесной и быстрой.

- не пересчитывать весь stat sheet каждый кадр
- не пересчитывать все derived stats при любом мелком изменении
- хранить базовые атрибуты и заранее выделенные группы derived stats отдельно
- применять только минимальные модификаторы к затронутым группам статов
- обновлять итоговые значения по событию, а не по постоянному polling

Рекомендуемый runtime-подход для MVP:

- есть `base attributes`
- есть `derived stat buckets`
- есть `modifiers` от экипировки, класса, бафов и навыков
- есть `dirty flags` или аналогичная пометка затронутых групп
- при изменении источника обновляется только нужный bucket, а не весь персонаж целиком

Пример групп пересчета:

- offensive bucket: damage, attack speed, crit, penetration
- resource bucket: mana, mana regen, stamina, stamina regen
- caster bucket: spell power, cast speed, status power
- defense bucket: HP, HP regen, armor, control resist, stagger resist
- utility bucket: move speed, projectile speed, reload modifiers, class-specific mastery bonuses

Если меняется только `Стойкость`, нет причины пересчитывать весь ranged или caster stack. Если меняется только бонус на projectile speed, не нужно заново собирать защитные статы.

## MVP Main Stats

Это основные числа, которые стоит показывать в базовом MVP UI.

- `HP`
- `Stamina`
- `Mana`
- `Damage`
- `Attack Speed`
- `Armor`
- `Move Speed`

Правила показа:

- `Damage` должен быть приведен к понятной игроку форме, без раскрытия всех внутренних коэффициентов
- `Stamina` должна отображаться как физический ресурс действий и темпа
- `Mana` должна отображаться как магический ресурс каста и spell-oriented умений
- `Armor` лучше показывать как единое защитное число для MVP, если отдельный breakdown еще не нужен
- `Move Speed` полезен, потому что напрямую ощущается руками в top-down action RPG

Почему именно этот набор:

- он достаточно мал, чтобы не перегружать интерфейс
- он покрывает offensive, defensive и utility-изменения
- игрок видит, что числа меняются от атрибутов, оружия и экипировки
- сложные производные параметры при этом остаются скрытыми

## Advanced Stats

Эти статы не обязаны быть видны в основном экране, но могут отображаться в detail view, tooltip, расширенной панели или отладочном UI.

- `HP Regen`
- `Stamina Regen`
- `Mana Regen`
- `Cast Speed`
- `Crit Chance`
- `Magic Resist`
- `Armor Penetration`
- `Control Resist`
- `Status Power`
- `Block Power`
- `Projectile Speed`
- `Mastery Bonus`

Правила показа:

- `Mastery Bonus` лучше показывать не как абстрактное число, а как контекстный бонус класса, оружия или archetype
- `Crit Chance` и `Cast Speed` полезны только если соответствующий archetype реально на них опирается
- `Magic Resist` не нужно тащить в основной экран, если магические угрозы еще не занимают большую долю MVP-боя
- `Projectile Speed` и `Block Power` стоит показывать только когда игрок использует подходящее оружие или билд

Почему это не main UI:

- эти статы уже полезны для билдостроения, но не нужны каждую секунду
- без контекста они быстро создают лишний визуальный шум
- часть из них зависит от класса или weapon archetype и не обязана быть всегда релевантной

## Hidden Runtime Stats

Эти значения должны оставаться внутренними runtime-параметрами и не обязаны отображаться игроку в MVP.

- `crit quality`
- `weak spot multiplier`
- `headshot precision bonus`
- `debuff duration reduction` как отдельное техническое число
- `stagger threshold modifiers`
- `interrupt resistance coefficients`
- `anti-slow coefficients`
- `friendly fire reduction`
- `projectile control coefficients`
- `reload window modifiers`
- внутренние `mastery conversion rules`
- soft cap thresholds и post-cap diminishing returns
- служебные class-specific multipliers
- промежуточные коэффициенты скейлинга оружия и навыков

Почему эти статы нужно скрывать:

- они в основном полезны движку, а не игроку
- многие из них не читаются без длинного системного контекста
- их отображение повышает шум, но не улучшает качество решений в MVP
- часть этих параметров еще может меняться при балансировке и не должна закрепляться в UI слишком рано

## Attribute To UI Mapping

Чтобы игрок видел связь атрибутов с результатом, но без перегруза, для MVP рекомендуется такой уровень читаемости:

- `Мощь` в основном проявляется через `Damage`
- `Ловкость` в основном проявляется через `Attack Speed` и частично `Move Speed`
- `Фокус` в основном проявляется через `Mana`
- `Стойкость` в основном проявляется через `HP` и частично `Armor`
- `Stamina` в основном читается как отдельный физический ресурс, который поддерживается `Стойкостью`, `Ловкостью`, классом и экипировкой
- `Мастерство` в основном проявляется через контекстный `Mastery Bonus` в advanced view, а не как центральный main stat

Это дает игроку понятную обратную связь, но не заставляет UI раскрывать весь внутренний combat math.

## Runtime Update Model

Для MVP рекомендуется событийная модель обновления статов.

Источники изменений:

- изменение атрибутов персонажа
- смена класса или class state
- экипировка или снятие предмета
- применение бафа или дебафа
- смена оружия
- активация временного skill modifier

Правила обновления:

- каждое изменение должно помечать только затронутые stat buckets
- derived stats пересчитываются только по dirty-группам
- UI обновляется только если изменились отображаемые main или advanced stats
- hidden runtime stats могут обновляться вместе со своим bucket, но не должны триггерить лишние UI refresh
- ресурсные пулы и их автопополнение должны обновляться отдельно от offense/defense bucket, если изменение не затрагивает другие группы

Для MVP нежелательно:

- полный пересчет всех статов на каждом тике
- хранение одной гигантской формулы для всех классов и всех источников сразу
- постоянная сборка UI-строк из runtime-модели без кэша итоговых значений

## Recommended MVP Contract

Минимальный контракт для практической реализации:

- `MVP Main Stats`
  - `HP`
  - `Stamina`
  - `Mana`
  - `Damage`
  - `Attack Speed`
  - `Armor`
  - `Move Speed`
- `Advanced Stats`
  - `HP Regen`
  - `Stamina Regen`
  - `Mana Regen`
  - `Cast Speed`
  - `Crit Chance`
  - `Magic Resist`
  - `Armor Penetration`
  - `Control Resist`
  - `Status Power`
  - `Block Power`
  - `Projectile Speed`
  - `Mastery Bonus`
- `Hidden Runtime Stats`
  - все внутренние коэффициенты, soft caps, class hooks и промежуточные combat modifiers

## Final Position

Для MVP UI нужно показывать мало, но полезно. Игрок должен видеть, что его персонаж стал сильнее, быстрее или живучее, не погружаясь в технические детали формул.

Основной массив derived stats должен оставаться под капотом. Runtime-система должна обновлять только затронутые группы характеристик и не выполнять полный пересчет без необходимости. Это даст одновременно чистый UI и легковесную реализацию.