Keep skill total labels visible in the grid; mod documentation

docs/ru.md

@@ -0,0 +1,69 @@
+# Skills Engine — коллекция карточек умений игрока
+
+Skills Engine хранит собранные игроком умения и показывает их в панели **Умения** карточками. Умение может открыть возможность в другой механике (пассивная «проходная дверь»), выдать игроку новую карточку действия для боёв и добавить числа к **эффекту коллекции** — сумме всех собранных умений.
+
+Входит в Cthangover: там игра начинается с одного умения — **Работорговец**.
+
+## Панель умений
+
+Открывается иконкой умений на панели инструментов.
+
+![Панель умений в Cthangover: карточка «Работорговец» (эпическая, пассивная, +10% к шансу вербовки) в сетке, её описание в области изучения карты справа и плашка эффекта коллекции в углу с надписью «+10% к шансу вербовки».](assets/skills-panel.jpg)
+
+- **Вкладки** фильтруют по типу — **Пассивные**, **Активные**, **Для персонажа** — а ряд редкостей по редкости, от **обычной** до **легендарной**; поле поиска и список сортировки сужают сетку.
+- **Цвет рамки и ромбики** показывают редкость карточки.
+- **Щёлкните карточку**, чтобы рассмотреть её в области изучения карты: картинка, значки редкости и типа, описание, её эффекты, а для умения с выдачей — карточка действия, которую оно даёт.
+- **Эффект коллекции** складывает эффекты всех собранных умений: два умения на +10% и +5% к вербовке покажут +15%.
+
+У карточки «Работорговец» пока нет картинки: игра называет её изображением `characters/skills/slave_master`, но ни один мод не кладёт такого файла, поэтому рамка пустует.
+
+## Описание умения
+
+Умения — это JSON-файлы вида `skill`, в любом месте мода. Вот Работорговец из Cthangover — сравните с панелью выше:
+
+```json
+{
+  "Kind": "skill",
+  "Items": [
+    {
+      "Id": "slave_master",
+      "Name": "characters/skills/slave_master_name",
+      "Description": "characters/skills/slave_master",
+      "Image": "characters/skills/slave_master",
+      "Type": 1,
+      "Rare": 3,
+      "Effects": [
+        { "Key": "characters/skills/effects/recruit", "Value": 10, "Percent": true }
+      ]
+    }
+  ]
+}
+```
+
+- `Name`, `Description` — ключи перевода.
+- `Image` — картинка карточки.
+- `Type` — `Active` (0), `Passive` (1) или `ForCharacter` (2); подходят и имена, и числа. Работорговец — **пассивное**.
+- `Rare` — `Common` (0), `Uncommon`, `Rare`, `Epic` (3), `Legendary`. Работорговец — **эпическое**.
+- `Effects` — числа для эффекта коллекции: `Key` — ключ перевода того, что усиливается, `Value` — величина, `Percent` — показывать ли со знаком %. Один ключ во всех умениях должен измеряться в одних единицах, потому что значения складываются.
+- `GrantsAction` (необязателен) — id карточки действия (см. Characters Engine). Получив умение, игрок получает и эту карточку — она попадает в пул действий панели «Действия персонажей».
+
+## Что умение делает в игре
+
+Панель только показывает умение. Что оно меняет, решают моды, которые его проверяют:
+
+- Recruiting предлагает **обратить в рабство** поверженного врага, только пока у игрока есть `slave_master`. Шанс успеха — собственный `RecruitmentChance` врага; +10% с карточки видны в панели, но recruiting их не прибавляет.
+- Умение с `GrantsAction` выдаёт свою карточку действия, которую игрок затем кладёт в слот персонажа.
+
+## Выдать умение из сценария
+
+```scenario
+action character.add_skill skill_id=slave_master
+```
+
+Повторная выдача умения ничего не меняет, поэтому повторяющаяся сцена не задвоит ни умение, ни его карточку действия. Cthangover выдаёт Работорговца при начале новой игры.
+
+## Если что-то пошло не так
+
+1. **Умение не появляется.** `skill_id` должен совпадать с `Id` умения; неизвестный id попадает в лог предупреждением.
+2. **У карточки нет картинки.** Ни один мод не кладёт изображение с именем из `Image`.
+3. **Эффект коллекции показывает странную сумму.** Два умения используют один ключ эффекта с разными `Percent`.