Order interactives inside their layer instead of a global z index; mod documentation

docs/ru.md

@@ -0,0 +1,88 @@
+# Interactive Base — то, по чему можно щёлкнуть в сцене
+
+Interactive Base добавляет в картинки-сцены кликабельные объекты: вещь, лежащую на земле, дверь, место «за склепом». У объекта может быть своя картинка поверх фона, он может подсвечиваться под курсором, а клик по нему запускает сценарий. Сценарии добавляют и убирают объекты по ходу истории.
+
+Interactive Base использует пролог Cthangover. Тайловые карты RPG World вместо этого работают со своими событиями.
+
+## В игре
+
+В начале Cthangover в переулке у велосипеда лежит красная тряпка. Она — не часть фона: это интерактивный объект со своей картинкой.
+
+![Переулок в начале Cthangover: велосипед у стены и свисающая с него красная тряпка; справа вверху — панель инструментов.](assets/alley.jpg)
+
+Когда курсор оказывается над тряпкой, он превращается в руку, а тряпка приобретает лёгкий золотистый оттенок:
+
+![Тряпка без курсора и с курсором поверх; справа она чуть теплее по тону.](assets/cloth-hover.jpg)
+
+Клик запускает сценарий тряпки: Марао поднимает её, а сценарий убирает объект со сцены.
+
+![После клика: портрет Марао и первая строка сценария тряпки в окне диалога.](assets/cloth-clicked.jpg)
+
+## Интерактивный объект
+
+Объекты — это JSON-файлы в папке `interactives/` мода. Вот тряпка с картинок (из Cthangover), контур в ней сокращён:
+
+```json
+{
+  "Items": [
+    {
+      "id": "cloak_ground",
+      "texture": "cloak_ground",
+      "layer": "foreground",
+      "zIndex": 5,
+      "cursor": "PointingHand",
+      "hitArea": {
+        "type": "polygon",
+        "vertices": [
+          { "x": 0.2796, "y": 0.7318 }, { "x": 0.3207, "y": 0.7167 },
+          { "x": 0.3456, "y": 0.8434 }, { "x": 0.3387, "y": 0.8872 }
+        ]
+      },
+      "highlight": { "color": "#FFD70044", "scale": 1, "duration": 0.12 },
+      "actions": {
+        "onClick": { "scenario": "scenarios/prolog/morning_cloak.scenario" }
+      }
+    }
+  ]
+}
+```
+
+- `texture` — картинка размером во весь экран, прозрачная везде, кроме самого объекта, поэтому с фоном она совмещается сама. Уберите её, если нужен невидимый участок.
+- `hitArea` — где объект можно щёлкать, в долях экрана (0–1): `rect` с `x`, `y`, `width`, `height`; `circle` с `x`, `y`, `radius`; или `polygon` с `vertices`.
+- `layer` — `background` или `foreground`; оба — часть картинки и остаются под окном диалога, панелью инструментов и панелями. `ui` рисуется поверх всего.
+- `zIndex` — порядок среди объектов одного слоя: большее число рисуется сверху.
+- `cursor` — курсор мыши над объектом, например `PointingHand`.
+- `highlight` — подсветка, пока курсор над объектом: `color` (с прозрачностью), `scale` и `duration` появления в секундах.
+- `enabled`, `visible` — реагирует ли объект и рисуется ли он поначалу.
+- `actions` — `onClick` запускает файл `scenario` или `commands` прямо в строке; `onHoverEnter` и `onHoverLeave` выполняют сценарные команды.
+
+## Как объекты попадают в сцену
+
+Само по себе описание нигде не появляется. Объект добавляет сценарий сцены, а убирает обычно сценарий клика:
+
+```scenario
+interactive_add cloak_ground
+interactive_remove cloak_ground
+```
+
+При смене сцены объекты очищаются, поэтому Cthangover добавляет их заново при каждом входе — сценарием сцены, который проверяет сюжет:
+
+```scenario
+scene: prolog_alley
+priority: 15
+condition: AwakeningQuest.notHasTag("cloak_taken") && AwakeningQuest.notHasTag("book_taken")
+---
+interactive_add cloak_ground
+interactive_add book_ground
+end
+```
+
+Добавление объекта, который уже есть, ничего не делает, поэтому повторять это безопасно.
+
+Расставить объекты и нарисовать их области клика можно и в интерактивном редакторе Editor Tools.
+
+## Если что-то пошло не так
+
+1. **Клик ни к чему не приводит.** Объект ни разу не добавлялся в этой сцене, у него выключен `enabled`, либо клик пришёлся мимо `hitArea`.
+2. **Картинка стоит не на месте.** Текстура должна быть картинкой во весь экран, совпадающей с фоном, а не маленькой вырезкой.
+3. **Объект возвращается после того, как его взяли.** Сценарий, который его добавляет, должен проверять тот же тег или флаг, который ставит сценарий клика.