From c4aac00dc7962c787058dc9ea9f2167091d4e0a6 Mon Sep 17 00:00:00 2001 From: Konstantin Dyachenko Date: Thu, 9 Apr 2026 10:20:59 +0700 Subject: [PATCH] [Add] Attribute vis mvp --- .../attribute-stats-visibility-mvp.md | 199 ++++++++++++++++++ docs/gameplay/attribute-system-gdd.md | 5 +- 2 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 docs/gameplay/attribute-stats-visibility-mvp.md diff --git a/docs/gameplay/attribute-stats-visibility-mvp.md b/docs/gameplay/attribute-stats-visibility-mvp.md new file mode 100644 index 00000000..2cdd3d66 --- /dev/null +++ b/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 и легковесную реализацию. diff --git a/docs/gameplay/attribute-system-gdd.md b/docs/gameplay/attribute-system-gdd.md index 4cd4ecaf..68881ab7 100644 --- a/docs/gameplay/attribute-system-gdd.md +++ b/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