Add mod documentation in seven languages

2026-10-29 09:26:07 +01:00
1 parent 4876275f81
commit 59663653a4
@@ -0,0 +1,81 @@
+# Quests Engine — задания, их шаги и журнал
+
+Quests Engine ведёт счёт задачам игрока. У задания есть название и нумерованный список шагов; сценарии берут его в работу, переводят на следующий шаг, отмечают тегами и завершают. Панель **Журнал** показывает задания, которые взял игрок, а их состояние игра сохраняет.
+
+Его используют Cthangover (пробуждение в прологе и старый дом) и RPG Plus (лесные задания).
+
+## Журнал
+
+Открывается иконкой журнала на панели инструментов. Пока игрок не взял ни одного задания, журнал пуст:
+
+![Журнал в RPG Plus на старте: вкладки «Активные» и «Завершённые», на обеих страницах «Заданий нет».](assets/journal-before.jpg)
+
+В RPG Plus первое задание даёт староста деревни. Спросите его, куда идти:
+
+![Дом старосты: герой перед старостой, справа два варианта — «Волк умеет гасить фонари?» и «Где его искать?».](assets/elder-choice.jpg)
+
+После ответа задание появляется в журнале:
+
+![Журнал после разговора: «Свет по ведомости» в списке активных; справа «Запись II из V», первый шаг зачёркнут, текущий шаг — «Прогони волка у пещеры на востоке леса. Найди янтарное сердце».](assets/journal-after.jpg)
+
+- **Активные** — список заданий в работе, **Завершённые** — законченных. Ещё не начатые задания не появляются никогда.
+- Правая страница показывает выбранное задание: выполненные шаги зачёркнуты, текущий отмечен, а будущие скрыты — журнал не раскрывает сюжет заранее.
+- Заработанные заданием теги показаны под записью маленькими золотыми метками.
+
+## Описание задания
+
+Задания — это JSON-файлы вида `quest` в папке `quests/` мода. Вот задание с картинок (из RPG Plus):
+
+```json
+{
+  "Kind": "quest",
+  "Items": [
+    {
+      "Id": "woodland_ward",
+      "Name": "rpg_plus/quest/ward/name",
+      "StatusToDescription": {
+        "0": "rpg_plus/quest/ward/0",
+        "1": "rpg_plus/quest/ward/1",
+        "2": "rpg_plus/quest/ward/2",
+        "3": "rpg_plus/quest/ward/3",
+        "4": "rpg_plus/quest/ward/4"
+      }
+    }
+  ]
+}
+```
+
+`Name` и каждый шаг — ключи перевода. Числа — это **шаги** задания: на шаге 1 текст `1` показан как текущий, а `0` — зачёркнутым; на картинке это «Запись II из V».
+
+## Как сценарий двигает задание
+
+Ответ старосты в RPG Plus запускает задание и ставит его на шаг 1:
+
+```scenario
+action quest.set_status quest_id=woodland_ward status=Progress
+action quest.set_data_status quest_id=woodland_ward level=1
+```
+
+- `quest.set_status` — состояние задания: `NotStarted`, `Progress` (активно) или `End` (завершено).
+- `quest.set_data_status` — текущий шаг, `level` — его номер.
+- `quest.add_tag` / `quest.remove_tag` с `tag=…` — запомнить случившееся, например, какой предмет игрок взял первым.
+- `quest.send_notification` — показывает игроку уведомление о задании; само по себе изменение задания уведомления не даёт.
+
+## Как проверить задание
+
+Проверки задания работают везде, где игра принимает условие: в `when`, в условиях ответов, условиях сцен и событиях карты.
+
+```scenario
+when "woodland_ward.DataStatus >= 2" -> :lantern
+```
+
+- `<quest>.IsActive` — задание в работе;
+- `<quest>.Status` — `0` не начато, `1` в работе, `2` завершено;
+- `<quest>.DataStatus` — текущий шаг;
+- `<quest>.hasTag("tag")`, `<quest>.notHasTag("tag")` — так Cthangover выбирает, какой сценарий сцены играть, например `AwakeningQuest.hasTag("book_taken")`.
+
+## Если что-то пошло не так
+
+1. **Задания нет в журнале.** Его состояние должно быть `Progress` (или `End` для вкладки завершённых); одной установки шага мало.
+2. **Журнал показывает ключ вместо текста.** Добавьте ключ шага в файлы `locale` мода.
+3. **Условие всегда ложно.** Идентификатор задания написан иначе, чем `Id` в файле задания; в логе будет предупреждение о неизвестном задании.