# Turn Battle Base — общая платформа для всех боёв

Turn Battle Base — это то общее, что есть у всех пошаговых боёв в коллекции: запуск боя из сценария, боевая сцена с фоном того места, где бой начался, экраны победы и поражения, опыт и добыча, статусные эффекты вроде оглушения — и выбор **боевой системы**. Как именно сражается игрок, платформа не решает: это задача мода боевой системы — **FF Battle** (меню команд) или **Card Battle** (карты, которые перетаскивают на цели).

## Две боевые системы, одна платформа

Один и тот же бой в RPG Plus — воин против волка в деревне — в обеих системах:

![Слева: FF Battle — волк вверху, маленькая карточка героя внизу слева, журнал боя справа. Справа: Card Battle — крупные карты персонажей, панель действий и кнопка End turn.](assets/two-cores.jpg)

Всё вокруг боя одинаковое: фон деревни, цифры волка, кнопки скорости **x1 / x4 / x8** в правом верхнем углу (они ускоряют анимации, а выбор запоминается) и то, что происходит после боя.

Свою систему игра выбирает настройкой коллекции `battle.core`; в RPG Plus это `ff_battle`. Без настройки берётся первая из установленных систем. В редакторе коллекций настройка называется «Боевая система».

## Как проходит бой

```text
scenario: battle.init / rpg.battle
        |
        v
battle scene: backdrop of the current place, party from the roster, enemies from their files
        |
        v
battle system (ff_battle or card_battle): player turn <-> enemy turn
        |                                          |
   all enemies defeated                      party defeated
        v                                          v
  Victory: experience, loot             Defeat: Main menu
        |
        v
  back to the scene the battle started from
```

## Победа и поражение

Когда падает последний враг, экран победы показывает опыт каждого уцелевшего члена отряда и добычу:

![Экран победы: надпись «Victory», кнопка Continue, герой с +24 и добыча — шкуры волка x2, монеты x8 и янтарь.](assets/victory.jpg)

- **Опыт.** Каждый побеждённый враг приносит свой `Level × Exp`, который поровну делится между теми, кто остался на ногах. Волк — 2-го уровня с `Exp` 12, итого **+24**.
- **Добыча.** Для каждого побеждённого врага разыгрывается его список `Loot`; предметы сразу попадают в инвентарь.
- **Continue** возвращает в сцену, откуда пришёл бой. Потерянное в бою здоровье не восстанавливается.

Если падает весь отряд, экран поражения предлагает только **Main menu** — без опыта и без добычи.

![Экран поражения: надпись «Defeat» на тёмно-красной луже и кнопка Main menu.](assets/defeat.jpg)

## Запуск боя из сценария

```scenario
action battle.init scene=town_entry enemies=wolf_1,wolf_2 quest_id=MeetingMurakamiQuest new_tag=wolf_battle
switch_scene Battle
end
```

- `enemies` — id персонажей через запятую; один и тот же id дважды — это два врага.
- `scene` — сцена, в которую игра вернётся после победы.
- `quest_id`, `new_tag` (необязательные) — привязывают бой к заданию и помечают его тегом (уведомление в журнале).
- Фон боя — тот, что показан в этот момент, поэтому задайте его до `battle.init`.

На тайловой карте вместо этого используйте `action rpg.battle enemies=rpg_wolf win_flag=rpg_wolf_dead` из мода RPG: отряд вернётся в ту же клетку карты, а при победе выставится флаг.

Команда `action battle.set_core core=card_battle` переключает боевую систему для последующих боёв.

## Враги, добыча и статусные эффекты в данных

Враги — обычные персонажи (см. Characters Engine). Добыча волка из RPG Plus:

```json
{
  "Id": "rpg_wolf",
  "Loot": [
    { "ItemId": "rpg_plus/wolf_pelt", "MinCount": 2, "MaxCount": 3, "Probability": 100 },
    { "ItemId": "money/coin", "MinCount": 8, "MaxCount": 14, "Probability": 100 }
  ]
}
```

`Probability` — вероятность в процентах; количество — случайное число от `MinCount` до `MaxCount` включительно.

**Статусные эффекты** — это сущности вида `status_effect`. Уже в платформе есть оглушение: персонаж пропускает свои ходы:

```json
{ "Id": "effect/physics/stun", "Icon": "characters/effects/stun", "Type": "Stun", "Duration": 3, "Actions": "basic/stun" }
```

Боевое действие, накладывающее эффект, может задать своё число ходов; длительность уменьшается в начале каждого хода.

## Авторам модов

Боевая система — мод, регистрирующий `IBattleCore` (и `IBattleAutoPlayable` для автоматических тестов). Её действия выполняются через исполнители платформы, поэтому мод вроде Battle Formulas добавляет новые виды действий сразу всем системам. Код может узнавать о конце боя через `BattleEndedEvent`, а о победе — через `IWingroundListener`; так работает Recruiting, предлагая побеждённым врагам место в отряде.

## Если что-то пошло не так

1. **У боя пустой фон.** `battle.init` выполнился раньше, чем у сцены появился фон.
2. **Открывается не та система.** Проверьте настройку игры `battle.core` и не переключал ли её какой-нибудь сценарий через `battle.set_core`.
3. **После победы нет опыта.** Враги с `Exp` 0 не дают опыта; павшие члены отряда его не получают.