Перейти к содержанию

Формат файла квеста

Статический квест — это один JSON-файл в датапаке по пути data/<namespace>/quests/<id>.json, где <id> становится путём идентификатора квеста (<namespace>:<id>). Эта страница — точный справочник: какие поля бывают, какого они типа, что обязательно, а что нет.

Если ты только начинаешь — сначала прочти Быстрый старт и Структура квеста. Здесь же — словарь полей, к которому удобно возвращаться.

Минимальный валидный квест — это две служебные строки версии и заголовок:

{
    "version": 3,
    "variant": 1,
    "title": "Слух о пропавшем караване"
}

Такой квест существует, выдаётся игроку и появляется в книге, но не завершается сам — у него нет задач (см. КВЕСТ-ЗАМЕТКА).

Версия формата: version и variant

Два обязательных числовых поля в начале файла. Они защищают от попытки загрузить квест в несовместимой версии мода.

{
    "version": 3,
    "variant": 1
}
Поле Что значит Что будет при несовпадении
version Несовместимая версия формата. Меняется, когда правки ломают старые файлы: добавлено/убрано обязательное поле, изменён тип поля, убрано одно из допустимых значений поля. Квест не загрузится — в лог попадёт ошибка несовместимости.
variant Совместимая версия формата. Меняется, когда правки обратно совместимы: добавлено/убрано необязательное поле или добавлено новое допустимое значение поля. Квест загрузится, но в лог попадёт предупреждение: часть новых возможностей может быть проигнорирована.

Практическое правило: указывай текущие значения мода — version: 3, variant: 1. Если после обновления мода квест перестал грузиться — первым делом сверь эти числа.

Поля квеста

Указываются на верхнем уровне файла.

Поле Тип Обязательное По умолчанию Описание
version int да — Версия формата (см. выше). Сейчас 3.
variant int да — Вариант формата (см. выше). Сейчас 1.
title Text да — Заголовок квеста. См. Текстовые поля и стилизация.
description Text нет — Описание квеста.
icon Identifier нет inkquest:default Иконка квеста в HUD и книге. Атлас textures/icons/<path>.png.
index int нет 0 Порядок сортировки в книге: меньше — выше.
repeatable bool нет false Можно ли выдать квест повторно после завершения. См. Повторяемые квесты.
pin_mode auto | off | force нет auto Режим автозакрепления при автовыдаче по зависимости. См. Закрепление.
after список групп Identifier нет — Зависимости от других квестов. См. Зависимости между квестами.
require объект нет — Доп. условия разблокировки (tags, predicate). Игнорируется без after. См. Зависимости между квестами.
tasks объект taskId → задача нет — Словарь задач квеста. См. Поля задачи.
stages список списков taskId нет — Этапы: каждый этап — список ID задач, первая — обязательная. См. Активный этап.
$schema string нет — Путь к JSON-схеме для редактора. Модом игнорируется.

tasks задаёт, какие задачи существуют, а stages — как они расставлены по этапам. Задача, объявленная в tasks, но не попавшая ни в один этап stages, в квесте не участвует (её можно посмотреть командой /quest list tasks <id> unused).

Пример со всеми основными полями

{
    "version": 3,
    "variant": 1,
    "title": "Пропавший караван",
    "description": "Торговцы не вернулись в срок. Кто-то должен выяснить, что случилось.",
    "icon": "inkquest:note",
    "index": 10,
    "after": [["story:prologue"]],
    "require": { "tags": ["joined_guild"] },
    "tasks": {
        "find_tracks": {
            "title": "Найти следы каравана",
            "description": "Дорога на восток — последнее, где их видели."
        },
        "talk_to_witness": {
            "title": "Поговорить со свидетелем"
        }
    },
    "stages": [
        ["find_tracks", "talk_to_witness"]
    ]
}

Поля задачи

Каждая задача — это запись в объекте tasks, где ключ записи — её taskId (без namespace, например find_tracks).

Поле Тип Обязательное По умолчанию Описание
title Text да — Заголовок задачи.
description Text нет — Описание задачи.
condition объект нет — Условия автозавершения: success и/или failure. См. Условия выполнения задачи.
on объект нет — Хуки жизненного цикла: load, tick, pinned_tick, unload, success, failure. См. Хуки жизненного цикла задачи.
buttons список из success | failure | skip нет — Кнопки ручного завершения в книге. См. Условия выполнения задачи. 
"find_tracks": {
    "title": "Найти следы каравана",
    "description": "Дорога на восток — последнее, где их видели.",
    "condition": {
        "success": { "type": "predicate", "predicate": "story:at_caravan_site" }
    },
    "on": {
        "success": { "functions": ["story:caravan/found"], "tags": ["found_tracks"] }
    }
}

Текстовые поля и стилизация

Поля title и description — как у квеста, так и у задачи — принимают Minecraft JSON text component. Допустимы три формы записи:

"title": "Обычная строка"
"title": {"translate": "my.key"}
"title": ["Текст ", {"translate": "my.key"}, " продолжение"]

Что работает:

  • Простые строки.
  • Стили: color, bold, italic, underlined, strikethrough, obfuscated, font, insertion, clickEvent, hoverEvent.
  • {"translate": "..."} — с полем with или без.
  • {"keybind": "..."} — показывает актуальную клавишу игрока.
  • Вложенные массивы и поле extra.

Что не работает в HUD и книге:

Компонент Проблема
{"score": {...}} Показывается пустым.
{"selector": "..."} Показывается пустым.
{"nbt": "..."} Показывается пустым.

Эти компоненты подставляют значение только в чате и командах; в книге и HUD оно остаётся пустым — это ограничение реализации.

Чтобы показать игроку числовой прогресс, не используй score-компонент в тексте — задай условие score. Оно рисует прогресс-бар напрямую и этих ограничений не имеет. См. Условия выполнения задачи.

Неизвестные и лишние поля

Мод не падает на опечатках, но и не угадывает их. Любой ключ, которого нет в списках выше, игнорируется, а в лог сервера попадает предупреждение вида Unknown key "<ключ>" in <quest|task|…> — it will be ignored — часть in … показывает, на каком уровне лежит лишний ключ. Также мод предупреждает, если задан require без after.

Если ожидаемое поле «не сработало» — в первую очередь проверь лог на такие предупреждения: чаще всего это опечатка в имени поля или вложенность на уровень выше/ниже нужного. Подробнее — в Частые вопросы и ошибки.

См. также