autohero/docs/specification.md

# AutoHero — Полная спецификация игры

---

## 1. 🎮 Обзор игры

### 1.1 Концепция

AutoHero — это idle/incremental RPG с изометрическим видом и таймер-базированной боевой системой.

### 1.2 Первый вход: имя героя

При **первом** входе в игру (создание профиля героя) игрок обязан **ввести имя героя** — это отдельный шаг до полноценного геймплея на карте.

**Назначение имени:**

- Отображается **над моделью героя** (nameplate / табличка), читаемая на мобильном экране.
- Используется в **социальных взаимодействиях**: встречи с другими игроками (§2.3), приглашения на дуэль, отображение в UI рядом с портретом/иконкой, будущие списки друзей/гильдий — везде, где нужен человекочитаемый идентификатор вместо Telegram ID.

**Правила имени:**

- **Уникальность глобальная:** в рамках игры не может существовать двух героев с одинаковым именем (регистронезависимое сравнение: `Ser` и `ser` — конфликт; точная политика нормализации — на стороне сервера).
- Если выбранное имя **уже занято**, клиент получает **ошибку** (например, код `HERO_NAME_TAKEN` / сообщение для пользователя «Имя занято») и **не создаёт** героя до смены имени.
- Длина и допустимые символы (ориентир): **2–16** символов; буквы (латиница и/или кириллица по политике продукта), цифры; без пробелов в начале/конце; запрещены оскорбительные шаблоны (модерация — отдельная политика, в MVP достаточно длины + уникальности).
- После успешной регистрации имя **меняется только** через отдельную платную/редкую механику или саппорт — не часть базового MVP, если не указано иначе.

**UX:**

- Один экран: поле ввода, кнопка «Продолжить», подсказка про уникальность.
- При ошибке занятости — поле подсвечивается, текст ошибки краткий.

---

## 2. 🌍 Мир игры

### 2.1 Общее описание

Игрок автоматически движется, встречает врагов, собирает лут и развивает персонажа.

### 2.2 Поведение перемещения героя

Герой не должен бесконечно идти по одной диагонали. В MVP используется **wander-поведение** с мягкими сменами направления и короткими паузами:

- Длина одного отрезка движения: `2.5-5.5 сек`
- В начале нового отрезка герой меняет курс относительно текущего направления на `-35° ... +35°`
- Во время движения каждые `0.7-1.2 сек` добавляется мягкая корректировка курса на `-10° ... +10°`
- Скорость поворота ограничена `90°/сек`, чтобы движение выглядело как плавная дуга, а не как резкий рывок
- Множитель скорости ходьбы на отрезок: `0.90x-1.10x` от базовой
- После каждого отрезка есть `18%` шанс остановиться и "отдохнуть" на `1-3 сек`
- Если герой двигался без паузы более `25 сек`, следующая пауза становится обязательной
- Во время паузы герой не запрашивает новые энкаунтеры, но сохраняет текущее состояние/ориентацию

**Коллизии и непроходимость:** герой **не может** перемещаться **сквозь** препятствия. К непроходимым относятся как минимум:

- **деревья** и **кусты** (объекты природы на тайле);
- **камни** (включая крупные валуны);
- **постройки** (стены, дома, руины и прочие здания — см. §2.6);
- при необходимости — **вода** / обрывы по дизайну карты (если на карте есть непроходимые биомы).

Поведение: траектория wander и любое автоматическое движение **обходит** препятствия (коррекция курса, локальный обход, упрощённый pathfinding — деталь реализации). Визуально герой не «режет» силуэты объектов и не проходит по их клеткам/полигонам коллизии.

### 2.3 Карта и встречи с другими игроками (shared world)

На общей карте герои разных игроков могут оказываться рядом (один шард/чанк/инстанс — деталь реализации). Это **не обязательно** приводит к бою.

**Принципы:**

- **По умолчанию — мирный контакт:** чаще всего герои **просто проходят мимо**, обмениваются коротким **эмоутом/репликой** (иконка + 1 строка текста по желанию) и продолжают wander.
- **Дуэль — опционально и по шансу:** при сближении двух чужих героев система может предложить **всплывающий выбор** «Дуэль?» с таймаутом. Игрок может **отказаться без штрафа**; при отказе или таймауте оба продолжают путь как в пункте выше.
- **Вероятности (ориентиры для баланса, не жёсткий MVP):**
  - `p_social_only` — «поздороваться и разойтись» (talk / walk): **~55–75%** от срабатываний «встречи».
  - `p_duel_prompt` — показать предложение дуэли: **~10–25%** (остальное до 100% — тихий проход без UI, если не хотим спамить).
  - Из тех, кому показали дуэль, оба должны согласиться; иначе — отмена без последствий.
- **Дуэль не обязательна для прогрессии:** награды за дуэль — отдельный небольшой пул (честь/косметика/чуть золота), без блокировки основного PvE-loop.

**Ограничения UX (mobile-first):**

- Один экран, минимум текста: иконки «меч», «ладонь (отказ)», таймер **3–5 сек**.
- Нет обязательного чата; опционально пресеты фраз.

### 2.4 Несраженческие события (дружелюбные NPC)

Помимо врагов на карте могут встречаться **нейтральные NPC** (не враждебные).

**Пример мини-квеста «alms» (подай монет):**

- NPC появляется как отдельная сущность карты (см. каталог `npc.*`).
- Условие: отдать **N** золота (`N` масштабируется от уровня/биома или фиксировано для MVP).
- Награда: **случайный предмет экипировки** в одном из **гармент-слотов** (см. §6.3), редкость по общим правилам лута или смещённая таблица «quest reward».
- Ограничения: кулдаун между такими событиями на героя / глобальный лимит в день — чтобы не было эксплойта.

Другие варианты non-combat (на будущее): короткий диалог-ветка, обмен ресурса, временный бафф от «благословения» NPC — в MVP достаточно одного шаблона выше.

### 2.5 Города и населённые пункты на карте

Мир содержит **несколько городов** разного **размера** и **планировки**. Они зафиксированы в данных карты (координаты, границы, входы). Город — это зона с **плотной застройкой**, **без спавна враждебных энкаунтеров** внутри (или с сильно сниженным шансом — по балансу), плюс визуальные маркеры на миникарте/краю экрана по желанию.

**Распределение по карте (логические регионы):**

| Ключ (для контента) | Название | Размер | Конфигурация / силуэт | Регион на карте |
|---------------------|----------|--------|------------------------|-----------------|
| `city.silver_rampart` | **Серебряный Вал** | Крупный (XL) | Кольцо стен + внутренний рынок и кварталы; 4 ворот | Центр — столица региона |
| `city.ashen_march` | **Пепельный Марш** | Средний (M) | Две параллельные улицы вдоль дороги; узкий «город-лента» | Восток — тракт у скал |
| `city.oak_haven` | **Ясеневая Гавань** | Средний (M) | Радиальная площадь + 3 «луча» улиц к причалам/полям | Север — лесная окраина |
| `city.stone_morrow` | **Каменное Утро** | Средний (M) | Сетка кварталов 3×4 с узкими переулками | Юго-запад — подножие холмов |
| `city.three_lanterns` | **Три Фонаря** | Малый (S) | Один двор + кольцо домов вокруг колодца | Запад — перекрёсток троп |
| `city.dry_ford` | **Сухой Брод** | Малый (S) | Дома вдоль брода; вытянутый вдоль реки | Юг — речная низина |
| `city.greymoor` | **Серомур** | Малый (S) | Полукруг домов у старой башни | Северо-восток — туманные низины |
| `city.watch_rest` | **Сторожевой Привал** | Крошечный (XS), форпост | Укреплённый донжон + 2–3 дома + палисад | Восточная граница карты — КПП |

Города **не должны** перекрывать друг друга; между ними — дикие зоны (лес, дорога, поля). Размер влияет на число NPC, точек квестов и длину «городского» пути при проходе wander.

### 2.6 Постройки и объекты окружения

На карте (в городах и вне них) встречаются **различные постройки** и декоративно-геймплейные объекты:

- **Жилые:** дом, хижина, длинный дом общины.
- **Хозяйственные:** мельница, амбар, кузница, стойка торговца.
- **Оборонительные:** стена, башня, ворота, баррикада, руины укрепления.
- **Религиозные / культурные:** часовня, святилище, памятник.
- **Инфраструктура:** мост, причал, колодец, дорожный указатель.
- **Временные / сюжетные:** лагерь, повозка, костёр (как точка интереса, не обязательно интерактив в MVP).

У всех построек с **объёмом** на карте задаётся **коллизия** (см. непроходимость в §2.2): герой обходит контур. Мелкие декоративные объекты без коллизии — только по явному флагу в данных карты.

### 2.7 Типы квестов

Квесты группируются по **источнику** и **цели**. Ниже — каноническая типология для дизайна контента и API.

**По источнику:**

| Тип | Описание | Примеры |
|-----|----------|---------|
| **Сюжетный** | Привязан к фазе мира / одной цепочке; прогресс хранится сервером | Введение, открытие города |
| **Побочный** | Опционален, не блокирует основной прогресс | «Принеси 10 когтей» |
| **Ежедневный / еженедельный** | Обновляется по таймеру, награды в таблице ретенции (см. §10) | Убить N врагов |
| **Микро-квест NPC** | Короткое взаимодействие на карте (§2.4) | Alms: монеты → предмет |
| **Исследование** | Награда за посещение точки / города / первое открытие зоны | Первый визит в «Серебряный Вал» |
| **Социальный** | Связан с другими игроками | Условный «свидетель дуэли», обмен эмоутом (расширение) |

**По цели (механика):**

| Тип цели | Условие выполнения |
|----------|-------------------|
| **Убить** | Победить N врагов заданного типа / класса |
| **Собрать** | Накопить золото / дроп / валюту квеста |
| **Доставить** | Принести предмет или золото NPC |
| **Посетить** | Дойти до маркера / города / здания |
| **Выжить / удержать** | Пробежать маршрут без смерти / удержать HP выше порога до конца таймера |
| **Поговорить / взаимодействовать** | Завершить диалог или взаимодействие с объектом/NPC |

**Правила наград:**

- Квест не должен нарушать глобальное правило: **золото с убийств врагов** остаётся по §8; награда квеста — **дополнительный** слой (XP, предмет, косметика).
- Повторяемые квесты (ежедневные) имеют **сброс** и **лимит** попыток в день.

---

## 3. ⚔️ Combat Balance

### 3.1 Модель боя

Система основана на временных интервалах (next_attack_at).

### 3.2 Баланс коэффициентов

- agility_coef = 0.03
- MIN_ATTACK_INTERVAL = 250 ms
- целевой максимум: 4 атаки/сек

### 3.3 Уточнения боевой модели

- Бой остаётся **timer-based** через `next_attack_at`, а не через кадры или частоту рендера.
- HP героя **сохраняется между боями** и не восстанавливается автоматически после каждой победы.
- Допустимые источники восстановления HP:
  - бафф **Исцеление**
  - бафф **Воскрешение**
  - механика revive
  - явно описанная регенерация/лечение по механике врага, баффа или режима
- **Level Up не восстанавливает HP полностью автоматически**, если это не описано отдельной механикой.
- Смерть должна ощущаться как пауза/потеря темпа, но не как бесплатный сброс всех последствий боя.

### 3.4 Рост героя по уровням

После плейтестов выяснилось, что даже замедленная MVP-кривая (v2) всё ещё слишком быстро усиливает героя. **Версия v3** снова ужимает прогрессию примерно в **10 раз** относительно v2: пороги XP к следующему уровню умножены на `10`, награды за убийство — поделены на `10` (с минимумом `1`), а шаги роста статов при `LevelUp` сделаны в **10 раз реже** (кратности `30 / 40 / 50 / 60 / 100` вместо `3 / 4 / 5 / 6 / 10`, MaxHP — каждые `10` уровней вместо каждого уровня).

| Параметр | v2 | v3 |
|------|------|------|
| MaxHP | `+1 + floor(Constitution / 6)` каждый уровень | то же правило, но только на уровнях, кратных `10` |
| Attack / Defense | `+1` на уровнях, кратных `3` | `+1` каждый на уровнях, кратных `30` |
| Base Speed за уровень | `+0.0` | `+0.0` |

Новые derived-формулы героя:

- `EffectiveAttack = Attack + Strength * 2 + floor(Agility / 4)`
- `EffectiveDefense = Defense + Constitution + floor(Agility / 4)`
- `EffectiveSpeed = Speed + Agility * 0.03`

Правила роста вторичных статов при `LevelUp` (v3):

- `Strength +1` только на уровнях, кратных `40`
- `Constitution +1` только на уровнях, кратных `50`
- `Agility +1` только на уровнях, кратных `60`
- `Luck +1` только на уровнях, кратных `100`
- `HP` при повышении уровня **не восстанавливается автоматически**; увеличивается только `MaxHP`
- Стартовые статы героя **не меняются**: `HP=100`, `MaxHP=100`, `Attack=10`, `Defense=5`, `Speed=1.0`, `Strength=1`, `Constitution=1`, `Agility=1`, `Luck=1`

Причина: рост силы теперь идёт не через частые level-up бонусы, а через более редкие вторичные статы, экипировку и длинную кривую прогрессии. Это убирает резкий разгон героя без искусственного ослабления стартового опыта.

Контрольная таблица роста героя **без экипировки и без временных баффов** (v3, канон — `hero.go` и тест `TestProgressionV3CanonicalSnapshots`):

| Уровень | MaxHP | Attack | Defense | Strength | Constitution | Agility | Luck | AttackPower | DefensePower | AttackSpeed |
|------|------|------|------|------|------|------|------|------|------|------|
| 1 | `100` | `10` | `5` | `1` | `1` | `1` | `1` | `12` | `6` | `1.03` |
| 5 | `100` | `10` | `5` | `1` | `1` | `1` | `1` | `12` | `6` | `1.03` |
| 10 | `101` | `10` | `5` | `1` | `1` | `1` | `1` | `12` | `6` | `1.03` |
| 20 | `102` | `10` | `5` | `1` | `1` | `1` | `1` | `12` | `6` | `1.03` |
| 30 | `103` | `11` | `6` | `1` | `1` | `1` | `1` | `13` | `7` | `1.03` |
| 45 | `104` | `11` | `6` | `2` | `1` | `1` | `1` | `15` | `7` | `1.03` |

### 3.5 Целевые боевые показатели героя

Ориентиры для инженеров и QA при проверке новой кривой силы героя **без временных баффов**:

| Уровень | MaxHP | AttackPower | DefensePower | AttackSpeed |
|------|------|------|------|------|
| 10 | `100-105` | `12-16` | `6-9` | `1.03-1.10 APS` |
| 25 | `101-108` | `12-18` | `6-12` | `1.03-1.15 APS` |
| 45 | `103-120` | `14-28` | `7-18` | `1.03-1.30 APS` |

Герой `L45` без временных баффов и без сильной экипировки остаётся относительно плоским по числам; основной рост mid/late-game должен ощущаться через экипировку, баффы и редкие уровни.

---

## 4. 🧟 Враги (Enemy Design)

### 4.1 Базовые враги (7 типов)

#### 🐺 Лесной волк (Уровни 1-5)
- Быстрый, низкий HP, часто атакует
- Крит шанс: 5%

#### 🐗 Дикий кабан (Уровни 2-6)
- Средний HP, высокий урон, редкие атаки
- Крит шанс: 8%

#### 🧟 Гниющий зомби (Уровни 3-8)
- Медленный, много HP, слабый урон
- Способность: 10% шанс apply Poison

#### 🕷 Пещерный паук (Уровни 4-9)
- Очень быстрый, может критовать
- Крит шанс: 15%

#### 👹 Орк-воин (Уровни 5-12)
- Сбалансированный враг мид-гейма
- Способность: раз в 3 атаки = 1.5x урона

#### 💀 Скелетный лучник (Уровни 6-14)
- Средние статы
- Способность: 20% dodge входящего урона

#### 🐢 Боевая ящерица (Уровни 7-15)
- Много HP, высокая защита
- Способность: восстанавливает 2% от полученного урона

### 4.2 Элитные враги (6 типов)

#### 🔥 Огненный демон (Уровни 10-20)
- Высокий урон
- Способность: 30% шанс apply Burn

#### ❄️ Ледяной страж (Уровни 12-22)
- Высокая защита
- Способность: -20% скорость атаки игрока

#### 💀 Король Скелетов (Уровни 15-25)
- Восстанавливает 10% HP
- Создаёт скелетных слуг раз в 15 сек

#### 🌊 Водяной элемент (Уровни 18-28)
- Много HP
- Способность: apply Slow (-40% Movement)

#### 🌳 Лесной страж (Уровни 20-30)
- ОЧЕНЬ МНОГО HP, ОЧЕНЬ ВЫСОКАЯ защита
- Регенерирует 5% HP/сек

#### ⚡ Молниевой титан (Уровни 25-35)
- ОЧЕНЬ ВЫСОКИЙ урон, ОЧЕНЬ быстрый
- Способность: 25% шанс Stun
- Цепная молния: после 5 атак = 3x урон

### 4.3 Масштабирование врагов

Старый множитель `1 + (heroLevel - 1) * 0.08` растит врагов слишком резко на длинной дистанции и конфликтует с ростом героя. В новой версии враги масштабируются **от своей level band**, а не от глобального уровня героя:

- `bandLevel = clamp(heroLevel, enemy.minLevel, enemy.maxLevel)`
- `bandDelta = bandLevel - enemy.minLevel`
- `overcapDelta = max(0, heroLevel - enemy.maxLevel)`
- `hpMultiplier = 1 + bandDelta * 0.05 + overcapDelta * 0.025`
- `attackMultiplier = 1 + bandDelta * 0.035 + overcapDelta * 0.018`
- `defenseMultiplier = 1 + bandDelta * 0.035 + overcapDelta * 0.018`
- `speedMultiplier = 1.0` (скорость атаки задаётся архетипом, а не разгоняется по уровню)

Это даёт:

- Более мягкий рост внутри зоны врага
- Сильную разницу между архетипами за счёт базовых шаблонов
- Контролируемый бесконечный рост после выхода героя за верхний `levelBand`

Примеры:

| Враг | Уровень героя | HP Mult | ATK/DEF Mult |
|------|------|------|------|
| Forest Wolf | `1` | `1.00` | `1.00` |
| Forest Wolf | `5` | `1.20` | `1.14` |
| Lightning Titan | `35` | `1.50` | `1.35` |
| Lightning Titan | `45` | `1.75` | `1.53` |

### 4.4 Базовые награды врагов

**v3:** к шаблонам v2 применено ещё одно десятикратное сжатие базовых наград (целочисленно, с минимумом `1` для золота и XP). Реализация — `EnemyTemplates` в `enemy.go`.

| Enemy ID | Базовый XP | Базовое золото |
|------|------|------|
| `enemy.wolf_forest` | `1` | `1` |
| `enemy.boar_wild` | `1` | `1` |
| `enemy.zombie_rotting` | `1` | `1` |
| `enemy.spider_cave` | `1` | `1` |
| `enemy.orc_warrior` | `1` | `1` |
| `enemy.skeleton_archer` | `1` | `1` |
| `enemy.lizard_battle` | `1` | `1` |
| `enemy.demon_fire` | `1` | `1` |
| `enemy.guard_ice` | `1` | `1` |
| `enemy.skeleton_king` | `1` | `1` |
| `enemy.element_water` | `2` | `1` |
| `enemy.guard_forest` | `2` | `1` |
| `enemy.titan_lightning` | `3` | `2` |

Формулы наград при спавне:

- `xpReward = round(baseXP * (1 + bandDelta * 0.05 + overcapDelta * 0.03))`
- `goldReward = round(baseGold * (1 + bandDelta * 0.05 + overcapDelta * 0.025))`

Золото масштабируется мягче, чем XP, потому что при замедлении левелинга игрок должен продолжать ощущать прогресс через экипировку и экономику.

---

## 5. 🗡 Оружие

### 5.1 Типы оружия

#### Кинжалы
- Скорость: 1.3x базовая
- Урон: 0.7x базовый

#### Мечи
- Скорость: 1.0x (базовая)
- Урон: 1.0x (базовый)

#### Топоры
- Скорость: 0.7x
- Урон: 1.5x (ВЫСОКИЙ)

#### Луки (дальний бой, требуют слот `quiver`, см. §5.3)
- Скорость: 0.85x базовой частоты атак (чуть быстрее топора, медленнее меча)
- Урон: 1.0x базового **до** бонуса боеприпасов; итоговый урон складывается из оружия и аммуниции

#### Арбалеты (дальний бой, требуют слот `quiver`)
- Скорость: 0.55x
- Урон: 1.35x (сильнее лука за счёт темпа)

### 5.2 Примеры оружия (15 штук)

#### Кинжалы:
- Rusty Dagger (Common)
- Iron Dagger (Uncommon)
- Assassin's Blade (Rare)
- Phantom Edge (Epic)
- Fang of the Void (Legendary)

#### Мечи:
- Iron Sword (Common)
- Steel Sword (Uncommon)
- Longsword (Rare)
- Excalibur (Epic)
- Soul Reaver (Legendary)

#### Топоры:
- Rusty Axe (Common)
- Battle Axe (Uncommon)
- War Axe (Rare)
- Infernal Axe (Epic)
- Godslayer's Edge (Legendary)

### 5.3 Боеприпасы (аммуниция) и слот колчана

**Слот:** `quiver` (см. §6.3 и каталог `gear.slot.quiver`, `gear.ammo.*`).  
**Условие:** бонусы из колчана применяются **только** если в `main_hand` экипирован лук или арбалет (`gear.form.main_hand.bow` / `gear.form.main_hand.crossbow`). Иначе слот игнорируется в расчёте боя (предмет может храниться, но не даёт статов).

**Роль в бою:** каждый тип боеприпасов задаёт **базовые коэффициенты** в каталоге; у конкретного экземпляра числа получаются по **§6.4** (уровень предмета `ilvl` и редкость).  
**Вклад в героя:** рассчитанный `bonusAttack` аммуниции суммируется с **Attack** (как плоский бонус к цепочке `EffectiveAttack` после базы героя и остальной экипировки — порядок суммирования на стороне сервера фиксируется в коде, но обязан быть детерминированным).

**Вторичные поля** (крит, пробитие, штраф к скорости): для боеприпасов используется **упрощённое** масштабирование только по редкости — **§6.4.4**; иначе высокий `ilvl` раздувал бы утилити без контроля.

**Баланс:** сильные семейства боеприпасов имеют больший `basePrimary`, но могут иметь штрафы (`deltaSpeed`, низкий потолок крита и т.д.) — см. каталог.

---

## 6. 🛡 Броня

### 6.1 Типы брони

- Лёгкая: 0.8x Defense, +Agility/Speed
- Средняя: 1.0x Defense, +Constitution/Luck
- Тяжёлая: 1.5x Defense, +Constitution/Strength, -30% Speed

### 6.2 Комплекты брони (4 комплекта)

- Assassin's Set
- Knight's Set
- Berserker's Set
- Ancient Guardian's Set

### 6.3 Расширенные категории гардероба и экипировки (слоты)

Помимо базовой пары «оружие + броня» (см. §5 и §6.1), целевая модель включает **дополнительные слоты предметов** — для разнообразия билдов и наград (в т.ч. с NPC-квестов и дуэлей).

**Канонические слоты (ключи для каталога `gear.slot.*`):**

| Слот (ключ) | Описание |
|-------------|----------|
| `main_hand` | Основное оружие (как сейчас) |
| `off_hand` | Вторая рука: щит **или** лёгкое off-hand (деталь баланса отдельно) |
| `head` | Шлем / шапка / капюшон |
| `chest` | Нагрудник (тяжёлая «броня» из §6.1 маппится сюда) |
| `legs` | Поножи / штаны |
| `feet` | Сапоги / ботинки |
| `cloak` | Плащ / накидка (часто даёт малый утилити-стат или чисто визуал в косметике) |
| `neck` | Амулет |
| `finger` | Кольцо (возможны **2** слота `finger_1`, `finger_2` в реализации; в каталоге — одно семейство `gear.slot.finger`) |
| `wrist` | Браслеты (опционально) |
| `quiver` | Боеприпасы (стрелы / болты); дают бонус к дальнему бою при луке или арбалете (§5.3) |

**Правила:**

- Каждый предмет принадлежит **ровно одному** слоту; нет «универсальных» без явного правила в каталоге.
- Щит в `off_hand` даёт защиту и может иметь штраф к скорости атаки по архетипу (как в классических RPG); детальные множители — в балансе предметов, не в этом разделе.
- Реализация может вводить слоты поэтапно: сначала `head` / `feet` / `neck`, затем остальные — но **ID слотов в каталоге** фиксируются заранее.

### 6.4 Уровень предмета (`ilvl`) и масштабирование от уровня и редкости

Каждый выпавший предмет (включая боеприпасы) имеет:

- **`ilvl`** — целое **≥ 1** (уровень предмета; не путать с уровнем героя).
- **`rarity`** — одна из глобальных редкостей (`Common` … `Legendary`, как в §8.1–8.2).
- **`familyId`** — ссылка на строку каталога (`gear.ammo.*`, форма `gear.form.*`, в будущем — семейства оружия/брони), откуда берутся **базовые** числа.

#### 6.4.1 Фактор уровня предмета

Коэффициент (плавный рост от `ilvl`, без ступеней):

- `α = 0.03`
- `L(ilvl) = 1 + α × max(0, ilvl − 1)`

Примеры: `L(1) = 1.00`; `L(10) = 1.27`; `L(25) = 1.72`; `L(50) = 2.47`.

#### 6.4.2 Множитель редкости

Одинаков для всех типов предметов, для воспроизводимости:

| Редкость | `M(rarity)` |
|----------|----------------|
| Common | `1.00` |
| Uncommon | `1.12` |
| Rare | `1.30` |
| Epic | `1.52` |
| Legendary | `1.78` |

#### 6.4.3 Первичные статы предмета (урон / защита от предмета)

Для величин, которые напрямую входят в `EffectiveAttack` / `EffectiveDefense` как **плоские бонусы** от экипировки (в т.ч. `bonusAttack` боеприпасов, бонус Defense с нагрудника и т.д.):

```
primaryOut = round( basePrimary × L(ilvl) × M(rarity) )
```

`basePrimary` — целое из каталога для семейства предмета на «эталоне» `ilvl = 1`, `Common`.

**Свойство баланса:** при тех же `basePrimary` возможны ситуации, когда **редкий предмет с меньшим `ilvl` даёт больше или столько же**, чем **обычный с большим `ilvl`**, потому что `M(rarity)` растёт быстрее, чем `L(ilvl)` в типичных диапазонах дропа. Примеры (без привязки к слоту, `basePrimary = 10`):

| Конфигурация | Вычисление | `primaryOut` |
|--------------|------------|----------------|
| Common, ilvl 25 | `round(10 × 1.72 × 1.00)` | `17` |
| Rare, ilvl 13 | `round(10 × 1.36 × 1.30)` | `18` |
| Epic, ilvl 7 | `round(10 × 1.18 × 1.52)` | `18` |

То есть **Rare ниже по ilvl** и **Epic ещё ниже по ilvl** могут превосходить **Common высокого ilvl** — это намеренно.

#### 6.4.4 Вторичные статы (крит, пробитие, малые штрафы скорости у аммуниции)

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

```
secondaryOut = round( baseSecondary × M(rarity) )
```

`baseSecondary` — из каталога (например крит в базисных пунктах: `100 = 1.00%`). Рост только от редкости; при необходимости позже вводится мягкий множитель от `ilvl` отдельным баланс-пасом.

#### 6.4.5 Связь `ilvl` с уровнем источника дропа

Базовое правило для дропа с убитого врага уровня `monsterLevel` (уровень экземпляра в бою):

1. Сэмплируется смещение `δ` ∈ `{ −1, 0, +1 }` с **равными** вероятностями `1/3` каждое.
2. `ilvl = clamp( monsterLevel + δ, 1, ilvlMax )`, где **`ilvlMax = 100`** (резерв под эндгейм).

**Elite-враги** (класс elite в каталоге): вместо шага 1 используется `δ` ∈ `{ 0, +1, +2 }` с весами **`0.4 / 0.4 / 0.2`** — смещение в сторону более высокого уровня предмета.

**Правило согласованности:** типичный дроп с врага уровня `N` имеет `ilvl` около `N`, реже на `1` ниже или выше; сильные враги не обязаны давать предмет выше своего уровня без elite-бонуса, чтобы не ломать ранний прогресс.

#### 6.4.6 Ничьи при сравнении экипировки

Если после §6.4 два предмета в одном слоте дают одинаковый вклад в `combatRating` (§8.5), **предпочтение отдаётся более высокой редкости**; если и редкость совпала — большему `ilvl`.

---

## 7. ✨ Баффы и Дебаффы

### 7.1 Баффы (8 штук)

| Бафф | Эффект |
|------|--------|
| Рывок | +50% движение |
| Ярость | +100% урон |
| Щит | -50% входящий урон |
| Удача | x2.5 лут |
| Воскрешение | Воскрес 50% HP |
| Исцеление | +50% HP |
| Зелье силы | +150% урон |
| Боевой клич | +100% Attack speed |

### 7.2 Дебаффы (6 штук)

| Дебафф | Эффект |
|--------|--------|
| Отравление | -2% HP/сек |
| Заморозка | -50% Attack speed |
| Горение | -3% HP/сек |
| Оглушение | Нет атак (2 сек) |
| Замедление | -40% Movement |
| Ослабление | -30% входящий урон |

---

## 8. 💰 Система лута и золота

### 8.1 Дроп система

- Шанс, что враг вообще дропнет предмет экипировки: `22%`
- Если предмет выпал, его редкость распределяется так:
  - Common: `75%`
  - Uncommon: `20%`
  - Rare: `4%`
  - Epic: `0.9%`
  - Legendary: `0.1%`
- Каждый побеждённый враг **всегда** даёт золото.
- Золото — это **гарантированная базовая награда** за убийство, чтобы каждая победа ощущалась как прогресс.
- Предметы экипировки — это **дополнительный необязательный дроп**, а не замена золоту.
- Отсутствие предмета после убийства — это нормальное поведение; отсутствие золота — нет.

### 8.2 Таблица редкости предмета

| Редкость | Шанс внутри выпавшего предмета | Золото |
|----------|---|---|
| Common | 75% | 5-15 |
| Uncommon | 20% | 20-50 |
| Rare | 4% | 50-150 |
| Epic | 0.9% | 200-500 |
| Legendary | 0.1% | 1000-5000 |

### 8.3 Правила наград

- Награда за бой состоит из:
  - гарантированного золота
  - возможного предмета (оружие, броня нагрудника или — после внедрения §6.3 — предмет в любом доступном слоте)
- Если предмет выпал, он должен использовать ту же систему редкости (`Common` ... `Legendary`).
- Бафф **Удача** усиливает лут, но не отменяет правило гарантированного золота.
- В MVP допустим простой формат награды, но логика должна быть прозрачной: `gold always, item sometimes`.
- Уровень выпавшего предмета (`ilvl`) и масштабирование статов — **§6.4**; связь `ilvl` с уровнем убитого врага — **§6.4.5**.

### 8.4 MVP Inventory / Equipment HUD

Для MVP нет полноценного инвентаря-рюкзака. Игрок хранит только то, что влияет на бой прямо сейчас:

- `equippedWeapon` (слот `main_hand`; при появлении off-hand — `off_hand`)
- `equippedArmor` (слот `chest`, пока не разделён UI)
- `equippedQuiver` или аналог (слот `quiver`) — когда включён дальний бой и колчан в дропе
- `gold`
- По мере внедрения §6.3 — дополнительные `equipped*` по слотам из каталога

Правила:

- На каждый слот из §6.3 — не более **одного** экипированного предмета (кольца: до **двух**, если включены оба слота пальцев).
- Предметы не складываются в bag/stash
- Все выпавшие предметы обрабатываются сразу после боя
- UI обязан постоянно показывать:
  - золото
  - текущее оружие: иконка, имя, редкость
  - текущую броню: иконка, имя, редкость
  - по мере расширения слотов — компактная полоса иконок по активным слотам или свёрнутая панель «gear»
  - краткий toast о последнем дропе/автоэкипировке/автопродаже

### 8.5 Правила автоэкипировки и автопродажи

Чтобы MVP оставался простым, предмет не требует ручного менеджмента:

- Если слот пустой, предмет сразу экипируется
- Если слот занят, игра считает `combatRating`
- `combatRating = EffectiveAttack * EffectiveSpeed + EffectiveDefense * 0.35`
- Для сравнения подставляется герой с новым предметом того же слота и герой с текущим предметом
- Если новый предмет даёт `>= 3%` улучшения `combatRating`, он автоматически экипируется
- Иначе предмет автоматически продаётся

Фиксированные цены автопродажи по редкости:

| Редкость | Auto-sell Gold |
|------|------|
| Common | `3` |
| Uncommon | `8` |
| Rare | `20` |
| Epic | `60` |
| Legendary | `180` |

Эта схема даёт игроку прозрачный MVP loop: золото приходит всегда, хороший предмет сразу усиливает героя, плохой предмет всё равно конвертируется в ощутимую награду.

### 8.6 Кратко: уровень предмета при дропе

Полные формулы — **§6.4** и **§6.4.5**. Для дизайна контента:

- Чем выше **уровень поверженного врага**, тем выше типичный **`ilvl`** выпавшего предмета (с джиттером ±1, у elite — сдвиг вверх).
- Редкость по-прежнему крутится по таблице §8.1 внутри события «предмет выпал»; затем к выбранному семейству применяется §6.4.
- Автоэкипировка (§8.5) сравнивает итогового героя с учётом **всех** активных слотов, включая `quiver`, если лук/арбалет экипирован.

---

## 9. 📈 Система прогрессии

### 9.1 Уровни персонажа

Используется **piecewise XP curve** по фазам игры. **v3** умножает базовые коэффициенты v2 на `10` (темп до следующего уровня в тех же условиях боя — примерно в `10` раз медленнее).

`XPToNextLevel(L)`:

- Для `L = 1-9`: `round(180 * 1.28^(L-1))`
- Для `L = 10-29`: `round(1450 * 1.15^(L-10))`
- Для `L >= 30`: `round(23000 * 1.10^(L-30))`

`TotalXPForLevel(1) = 0`

`TotalXPForLevel(L) = sum(XPToNextLevel(n))`, где `n = 1 .. L-1`

- Формула XP одинакова для online/offline прогрессии.
- Рост статов при повышении уровня должен использовать **один и тот же канонический путь** во всех режимах.
- Offline-прогрессия не должна использовать отдельные "упрощённые" правила роста статов, если они дают другой результат.

Контрольные значения `XPToNextLevel`:

| Текущий уровень | XP до следующего уровня |
|------|------|
| 1 | `180` |
| 5 | `483` |
| 10 | `1450` |
| 20 | `5866` |
| 30 | `23000` |
| 40 | `59656` |
| 45 | `96077` |
| 50 | `154732` |

### 9.2 Игровые фазы

| Фаза | Уровни | Время |
|------|--------|-------|
| Ранняя | 1-10 | 3-5 часов |
| Середина | 11-30 | 25-45 часов |
| Поздняя | 31-50 | 90-150 часов |
| Лейт/предэндгейм | 51-100 | 300+ часов |
| Эндгейм | 100+ | Бесконечная |

### 9.3 Система Аскензии

После L100: AP = (Max_Level - 50) / 10

---

## 10. 🏆 Meta-Game & Retention

### 10.1 Дневные задачи

- Kill 10 enemies
- Defeat an Elite
- Collect 500 Gold
- Use 3 Buffs
- Reach Level X

### 10.2 Еженедельные вызовы

- Reach Level 50
- Defeat 5 Elites
- Collect 5000 Gold
- Die less than 5 times

### 10.3 Достижения

- Первая кровь
- Воин (L50)
- Легенда (L100)
- Охотник
- Богач
- Везунчик
- Неустрашимый

---

## 11. 🎨 Визуальная система

### 11.1 Система цветов

| Редкость | Цвет | Эффект |
|----------|------|--------|
| Common | Серый | Обычный |
| Uncommon | Зелёный | Glow |
| Rare | Синий | Частицы |
| Epic | Фиолетовый | Яркие частицы |
| Legendary | Золотой | Золотой луч |

---

## 12. 📱 UX принципы

1. Один экран = вся игра
2. Минимум текста — максимум визуала
3. Всё через иконки и цвета
4. Игрок всегда в моменте
5. Нет загрузок — всё instant
6. Мобильная оптимизация
7. Кнопка паузы/play
8. UI должен честно показывать состояние героя: нельзя визуально скрывать потерю HP автоматическим лечением, если сервер/механика этого не дали
9. UI должен ясно показывать модель наград: золото за каждую победу, предметы только при фактическом дропе
10. **Имя героя** (§1.2) всегда видно над моделью в мире; в социальных контекстах — то же имя, без расхождения с сервером

---

## 13. 📊 Баланс-принципы

### 13.1 Цели дизайна

- Ранняя (1-10): Щедрая прогрессия
- Середина (11-50): Сбалансированное развитие
- Поздняя (51+): Медленная прогрессия
- Эндгейм (100+): Аскензия, сезоны

---

## 14. 🔮 Будущие расширения

- Рейды
- Гильдии
- Питомцы
- Ремесло
- Полноценный PvP-рейтинг и арена (базовые **опциональные дуэли на карте** описаны в §2.3)
- Сезонные события
- Расширение полного комплекта слотов §6.3 с отдельным экраном «персонаж»

---

**Конец спецификации**