[Add] Attribute vis mvp

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

@@ -0,0 +1,199 @@
+# Attribute Stats Visibility MVP
+
+## Purpose
+
+Этот документ фиксирует, какие derived stats должны быть видимы игроку в MVP, какие можно показывать только в расширенном виде, а какие должны оставаться внутренними runtime-параметрами.
+
+Отдельная цель документа - зафиксировать легковесный подход к обновлению статов: система не должна постоянно пересчитывать весь набор характеристик, если можно применять только минимальные изменения к уже подготовленным значениям.
+
+## Related Docs
+
+- `docs/gameplay/attribute-system-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
+- caster bucket: spell power, resource, resource regen, 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`
+- `Resource`
+- `Damage`
+- `Attack Speed`
+- `Armor`
+- `Move Speed`
+
+Правила показа:
+
+- `Damage` должен быть приведен к понятной игроку форме, без раскрытия всех внутренних коэффициентов
+- `Resource` должен отображаться как основной кастерский или классовый ресурс
+- `Armor` лучше показывать как единое защитное число для MVP, если отдельный breakdown еще не нужен
+- `Move Speed` полезен, потому что напрямую ощущается руками в top-down action RPG
+
+Почему именно этот набор:
+
+- он достаточно мал, чтобы не перегружать интерфейс
+- он покрывает offensive, defensive и utility-изменения
+- игрок видит, что числа меняются от атрибутов, оружия и экипировки
+- сложные производные параметры при этом остаются скрытыми
+
+## Advanced Stats
+
+Эти статы не обязаны быть видны в основном экране, но могут отображаться в detail view, tooltip, расширенной панели или отладочном UI.
+
+- `HP Regen`
+- `Resource 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`
+- `Фокус` в основном проявляется через `Resource`
+- `Стойкость` в основном проявляется через `HP` и частично `Armor`
+- `Мастерство` в основном проявляется через контекстный `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
+
+Для MVP нежелательно:
+
+- полный пересчет всех статов на каждом тике
+- хранение одной гигантской формулы для всех классов и всех источников сразу
+- постоянная сборка UI-строк из runtime-модели без кэша итоговых значений
+
+## Recommended MVP Contract
+
+Минимальный контракт для практической реализации:
+
+- `MVP Main Stats`
+  - `HP`
+  - `Resource`
+  - `Damage`
+  - `Attack Speed`
+  - `Armor`
+  - `Move Speed`
+- `Advanced Stats`
+  - `HP Regen`
+  - `Resource 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 и легковесную реализацию.

docs/gameplay/attribute-system-gdd.md

@@ -277,6 +277,10 @@
 - scaling оружия и weapon archetypes
 - skill scaling и class-specific specialization hooks
 
+Связанный документ по слоям видимости статов и легковесному runtime-обновлению:
+
+- `docs/gameplay/attribute-stats-visibility-mvp.md`
+
 Связанные документы и задачи:
 
 - `docs/tasks/items/TASK-0007.md`
@@ -288,7 +292,6 @@
 
 ## Open Questions
 
-- какие именно derived stats нужны в MVP UI и какие можно оставить внутренними runtime-параметрами
 - как именно считать crit: через chance, crit quality, weak spot logic или их комбинацию
 - какие soft caps нужны для move speed, attack speed и cast speed
 - в каком виде `Мастерство` задается в коде: единый stat с archetype-specific conversion rules или набор class-owned scaling hooks