# Combat Resolution GDD

## Purpose

Этот документ фиксирует единый порядок расчета боевого действия, правила псевдорандома и место `crit`, `weak spot`, `status` и защитных расчетов в общем pipeline.

## Related Docs

- `docs/gameplay/attribute-system-gdd.md`
- `docs/gameplay/attribute-reference.md`
- `docs/gameplay/stat-catalog-mvp.md`
- `docs/gameplay/attribute-stats-visibility-mvp.md`

## Design Goals

- один общий combat pipeline для игрока, врага, оружия и навыков
- chance-based события должны ощущаться честно и стабильно
- в action RPG физический контакт не должен часто превращаться в нелогичный miss
- `crit`, `weak spot`, `penetration`, `status` и `stagger` должны быть частью одной цепочки, а не отдельными системами
- сервер должен быть источником истины для всех roll-based результатов

## Core Position

Для MVP pseudo-random distribution применяется к chance-based исходам, но не заменяет фактическую физику попадания.

То есть:

- hitbox, projectile impact и valid AoE contact сначала определяют, был ли контакт
- только после этого идут roll-based проверки
- псевдорандом используется для уменьшения длинных серий неудач и успехов

## Combat Pipeline

### 1. Action Start

Система получает попытку действия:

- melee attack
- projectile attack
- cast skill
- area effect
- block/guard reaction

Перед выполнением действия проверяется resource gate.

Проверяется:

- использует ли действие `Mana`, `Stamina` или не использует отдельный ресурс
- хватает ли нужного ресурса для старта
- есть ли специальные cost modifiers от класса, оружия, навыка или `Мастерства`

Правила resource gate для MVP:

- `Stamina` используется для dodge, sprint, block/guard upkeep, heavy attacks, charged attacks и weapon-heavy abilities
- базовая легкая атака и простой core loop не должны регулярно блокироваться отсутствием `Stamina`
- если `Stamina` исчерпана, игрок в первую очередь теряет доступ к сильным commit-действиям или получает short exhaustion pressure, а не полностью выключается из боя
- `Stamina Regen` должен быть быстрым, чтобы темп open world ARPG не разваливался даже в PvP и затяжных PvE-сценариях

На этом этапе определяются:

- источник действия
- тип действия
- weapon archetype
- skill archetype
- target rules
- resource type
- resource cost

### 2. Contact Resolution

Система определяет, был ли валидный контакт.

Примеры:

- melee через hitbox/overlap
- ranged через projectile collision
- spell через trace, overlap или target validation
- AoE через положение цели внутри области

Результат этапа:

- `No Contact` -> дальнейшие offensive roll-этапы не выполняются
- `Valid Contact` -> переход к следующему шагу

### 3. Server Validation

Сервер проверяет:

- допустимость действия
- валидность target
- допустимость дистанции, угла, времени и состояния
- отсутствие фальшивого попадания со стороны клиента

### 4. Hit Quality Resolution

Для MVP рекомендуется модель без обязательного stat-based miss после уже произошедшего контакта.

То есть:

- если действие физически попало и прошло валидацию сервера, это считается попаданием
- `Accuracy` и `Evasion` не являются обязательным MVP-слоем

Если позже потребуется accuracy-модель:

- она должна стоять здесь
- она должна использовать отдельный PRD accumulator
- ее нельзя смешивать с crit или status rolls

### 5. Critical Resolution

`Crit` считается как комбинация трех разных сущностей.

#### Crit Chance

Отвечает на вопрос: сработал ли крит.

Источники:

- `Ловкость`
- weapon modifiers
- buffs/debuffs
- часть `Мастерства` у precision-архетипов

Правило:

- `Crit Chance` является chance-based stat
- для него используется PRD

#### Crit Quality

Отвечает на вопрос: насколько сильным будет крит.

Источники:

- `Ловкость`
- `Мастерство`
- weapon archetype
- skill modifiers

Правило:

- `Crit Quality` не определяет факт крита
- `Crit Quality` определяет величину бонуса при уже успешном crit roll

#### Weak Spot Logic

Отвечает на вопрос: было ли точное позиционное или skill-based попадание в уязвимую зону.

Источники:

- hit zone
- angle or position check
- weapon type
- skill archetype
- `Мастерство`

Правило:

- `Weak Spot` не заменяет `Crit Chance`
- `Weak Spot` является skill-based усилителем
- при наличии weak spot попадание может усиливать crit или давать отдельный bonus layer

## Recommended Crit Model

Каноническая схема для MVP:

1. определить факт контакта
2. выполнить `Crit Chance` через PRD
3. при успехе применить `Crit Quality`
4. если сработал `Weak Spot`, усилить итог крита или применить отдельный precision bonus

Это дает:

- случайность для крита
- контролируемую силу крита
- отдельную награду за точное исполнение

## Base Damage Build

После того как подтверждено попадание и разрешены crit/precision-модификаторы, строится базовый урон.

В расчет входят:

- weapon base values
- skill coefficients
- уровень оружия
- relevant derived offense stats
- `Мощь`, `Фокус` и другие атрибутные конверсии через derived stats
- `Мастерство` как specialization modifier

Правило:

- оружие и навыки не должны считать урон по собственным отдельным формулам в обход общего offense build

## Penetration And Defense Pass

После построения offense value применяется защитный проход.

Участвуют:

- `Armor`
- `Magic Resist`
- `Armor Penetration`
- `Spell Penetration`, если введен для archetype
- small mitigation и другие defense modifiers

Правило источников магической защиты:

- `Magic Resist` формируется из сочетания `Фокуса`, `Мастерства` и экипировки
- ни `Фокус`, ни `Мастерство` по отдельности не должны давать самодостаточную магическую защиту

Порядок на MVP:

1. определить тип урона
2. выбрать релевантную защиту
3. применить penetration
4. применить mitigation

## Block And Guard Pass

Если у цели есть активный или пассивный defensive response, он обрабатывается после основного defense pass или как его часть, но в одном каноническом месте.

Участвуют:

- `Block Power`
- shield modifiers
- guard state
- directional defense rules

## Status Resolution

После разрешения основного урона система считает статусные эффекты.

Участвуют:

- `Status Power`
- skill status modifiers
- target resist hooks
- mastery hooks

Если эффект chance-based:

- применяется отдельный PRD accumulator

Примеры:

- bleed
- burn
- poison
- shock
- slow proc

## Stagger And Control Resolution

После урона и статусов обрабатываются control-related последствия.

Участвуют:

- stagger power
- `Stagger Resist`
- `Control Resist`
- `Debuff Duration Reduction`
- interrupt resistance

Правило:

- длительность и сила контроля не должны жить в отдельной автономной формуле вне общего pipeline

## Pseudo-Random Distribution Rules

### Scope

PRD используется только для chance-based событий.

Рекомендуемые MVP-области:

- `Crit Chance`
- chance-based `Status Apply`
- chance-based `Proc Effects`

Не использовать для MVP:

- фактического projectile contact
- melee hitbox contact
- AoE presence check

### PRD State

Для каждого roll type хранится отдельное состояние.

Минимальный состав:

- `roll type`
- `base chance`
- `failure streak`
- `current adjusted chance`

Разделять состояния по типам:

- `Crit PRD`
- `Status PRD`
- `Proc PRD`
- `Accuracy PRD`, только если accuracy-layer появится позже

### PRD Behavior

- после неуспеха шанс немного растет
- после успеха streak сбрасывается
- итоговый шанс не должен слишком быстро гарантировать успех
- PRD работает на сервере
- клиент может показывать только результат, но не хранить authoritative PRD state

## System Links

### Attributes To Combat

- `Мощь` -> physical damage, heavy impact, penetration, block power
- `Ловкость` -> cadence, crit chance, crit quality, projectile handling, stamina recovery
- `Фокус` -> spell power, mana, status power, part of magic mitigation
- `Стойкость` -> HP, stamina pool, mitigation, control resistance, stagger resistance
- `Мастерство` -> weak spot bonuses, proc quality, archetype specialization, part of magic mitigation

### Weapons To Combat

- задают base damage
- задают hit delivery method
- задают часть crit, penetration и block hooks

### Skills To Combat

- задают execution pattern
- задают mana consumption или stamina consumption
- задают coefficients и status hooks
- задают mastery-specific behavior

### Classes To Combat

- задают стартовые attribute priorities
- задают class affinity
- задают доступ к разным mastery conversion rules

## Final Position

Для MVP бой должен считаться в одном общем pipeline: контакт, валидация, crit/precision, offense build, defense pass, status, control. Псевдорандом нужен для chance-based механик и должен жить как отдельный серверный слой, а не как замена физическому попаданию.