Создание наборов правил Game Mode

Набор правил объясняет Game Mode, как работает настольная система: какие кости бросает проверка, что есть в листе персонажа, какие ресурсы тратятся и что возвращает отдых. Напишите свой набор, чтобы перенести собственную систему в Game Mode и поделиться ею. Чтобы играть с чужим набором, см. руководство Игра с набором правил.

Набор правил – один JSON-файл. Это данные, а не код, поэтому ничего из него не выполняется и импорт не может навредить компьютеру. Перед импортом чужого файла прочитайте текст Game Master: он передается модели в каждой игре с этим набором.

Как начать набор правил

1. Скопируйте пример, который подходит к тому, как бросает кости ваша система:

• ember-roads.json – небольшая система 2d6 с тремя характеристиками. Она показывает, что формат не предполагает ни d20, ни шести характеристик.
• gravewatch.json – небольшой пул десятигранных костей с тремя рейтингами и шестью профессиональными навыками.
• Официальный пакет 5e (SRD 5.1) – полноразмерный пример. Его ruleset.json и catalogs/ – то, что устанавливает Agent Organizer.

1. Замените id своим. Идентификатор состоит из строчных букв, цифр и одиночных дефисов, например ember-roads.
2. Откройте копию в текстовом редакторе, например в Notepad или VS Code, и сохраните ее с окончанием .json. Сначала измените name, затем названия характеристик в sheet, затем rests и текст gm. В разделе Части файла перечислен каждый ключ, а в разделе Справочные страницы собраны ссылки на страницы, которые их объясняют.
3. Импортируйте файл (см. Как опробовать набор правил). Импорт проверяет весь файл и построчно сообщает, что не так, прежде чем что-либо сохранить.
4. Создайте новую игру (см. Game Mode: начало работы), выберите свой набор в Rules (правила) и выполните несколько проверок.

Если не получилось, см. раздел Устранение неполадок.

Чтобы редактор подсказывал при вводе, добавьте эту строку первой внутри внешних фигурных скобок файла. Она указывает редактору на JSON Schema:

"$schema": "https://raw.githubusercontent.com/Pasta-Devs/Marinara-Engine/staging/docs/extending/ruleset.schema.json",

Схема находит ошибки в именах ключей и неверные типы. Она не может проверить, указывают ли имена на то, что существует, например называет ли навык существующую характеристику. Это делает импорт. В любой объект можно добавить строку "$comment": "...", чтобы оставить себе заметку. Engine ее игнорирует.

Что набор правил может и чего не может

Набор правил заполняет пробелы в механике, которую Engine уже знает. Engine знает пять способов разрешить проверку, и ваш файл выбирает один из них через resolution.kind:

• dice-sum: бросить кости, прибавить числа из листа и достигнуть сложности или превысить ее. Подходит для систем d20, систем 2d6 плюс характеристика и многих других.
• dice-pool: бросить столько костей, сколько есть у персонажа, и сосчитать те, что достигли цели. Подходит для систем, где рейтинг – это горсть костей, а не бонус.
• dice-highest: бросить пул и взять его наибольшую кость или сложить несколько наибольших. Подходит для Blades in the Dark и Trophy Dark.
• roll-against: выбросить не больше (или не меньше) числа из листа. Подходит для процентных навыков и проверок GURPS.
• symbol-pool: набрать и улучшить повествовательные кости, затем взаимно отменить противоположные символы. Подходит для проверок Genesys, а с Capability API 1.382 – и для боев.

Все пять полностью описаны в разделе Виды разрешения.

Механику, которая не укладывается в эти формы, например встречные пулы, нельзя записать в файле набора правил. Ей нужен новый вид разрешения внутри Engine, то есть вклад в код с тестами. Если такой вид нужен вашей системе, откройте запрос функции в репозитории Engine и опишите механику на нескольких полностью разобранных бросках. Эти броски станут тестами.

Game Mode разрешает бой либо по собственной боевой системе Marinara, либо по правилам вашего набора. Необязательный блок battle передает бою Marinara числа из листов ваших персонажей: см. Сражения. Необязательный блок combat определяет, как набор сам разрешает бой: см. Бой. Combat Preference (предпочтительный вид боя) игры выбирает представление Classic или, если набор определяет расстояние, поле боя Tactical. Набор может ограничить, какие из них используют его игры, через combat.styles (см. Какие стили доступны игре).

Части файла

Размер файла – до 512 KB (до Capability API 1.340 – 256 KB). Текст, который попадает в промпт (имена, подписи, текст Game Master), не может содержать переносов строк, квадратных скобок или двойных фигурных скобок.

Идентификаторы внутри листа (характеристики, навыки, поля, запасы и прочее) состоят из строчных букв, цифр и подчеркиваний и начинаются с буквы, например grit_max.

Справочные страницы

Эта страница объясняет, как начать набор правил, опробовать его и поделиться им. Каждая из остальных страниц посвящена одной теме:

• Проверки набора правил: пять видов разрешения, степени исхода, проверки с собственным способом броска, а также расходы или талисманы, меняющие бросок.
• Листы набора правил: характеристики, навыки, поля и списки, текущие состояния, шкалы ран, штрафы, отдых, текст Game Master, лист отряда и часы прогресса.
• Каталоги набора правил: готовые записи, которые редактор листа предлагает в окне выбора.
• Механика записей набора правил: блок mechanics записи каталога, который читают проверки, отдых и бои.
• Конструктор персонажей набора правил: создание персонажа по шагам, от расы и класса до показателей, владений, заклинаний и снаряжения.
• Предметы набора правил: категории, оружие, доспехи, боеприпасы, добыча, деньги, начальное снаряжение и рынки.
• Бой по набору правил: блок battle и блок combat с бестиарием, полем боя, реакциями и состязаниями.
• Слои, переводы и миграции наборов правил: варианты, которые игрок включает для одной игры, переводы и перенос значений на новые идентификаторы при изменении листа.

Как опробовать набор правил

Перед началом включите Allow custom Agent imports (разрешить импорт своих агентов) в разделе Settings → Advanced → Danger Zone (настройки → дополнительно → опасная зона). Импортированные наборы правил используют тот же защитный переключатель, что и импортированные агенты, поэтому он выключен, пока вы его не включите. Для импорта также нужен доступ через localhost или секрет администратора (Settings → Advanced → Admin Access).

1. Откройте панель Agents (агенты) и нажмите кнопку Import agents (импортировать агентов; значок загрузки в ряду кнопок вверху панели).
2. Выберите Game Mode ruleset (набор правил Game Mode) и свой файл JSON или файл пакета набора правил с окончанием .ruleset.json (см. Как поделиться набором правил).
3. Прочитайте обзор. В нем показаны имя, версия, лицензия, что охватывает набор и текст Game Master. Нажмите Import (импортировать).

Набор появится в разделе Rules панели и в выборе Rules мастера настройки новых игр. Набор, импортированный из файла, записывается как local/<your id>, поэтому его никогда не спутать с официальным или чужим набором.

Изменение уже импортированного набора правил

Импортированная версия никогда не переписывается. Если импортировать измененный файл с тем же version, импорт отклоняется с просьбой поднять номер. Игра привязана к точной версии, на которой она создана, поэтому математика идущей кампании никогда не меняется.

Пока вы работаете над черновиком, цикл такой: отредактировать, поднять version, импортировать, начать новую игру. Старые версии остаются установленными рядом с новой, пока вы не удалите набор из раздела Rules. Если удалить набор, который еще использует игра, она будет сообщать, что ее набора правил нет, пока вы не импортируете его снова.

При изменении формы листа (добавлении, удалении или переименовании) поднимите также sheet.version. Существующие листы читаются терпимо: значения, которых новый лист не знает, сохраняются, а отсутствующие получают значения по умолчанию.

Как поделиться набором правил

Поделиться набором можно пятью способами.

Файлом

Отправьте файл JSON другу. Он импортирует его так же, как вы.

Файлом пакета

Набор правил, слишком большой для одного файла, с каталогами в отдельных файлах, передается одним простым файлом JSON с именем <name>.ruleset.json. Он содержит манифест пакета и документы набора правил, каждый в виде base64 (способа записать файл простым текстом):

{
  "format": "marinara-ruleset",
  "version": 1,
  "manifest": { "kind": ["ruleset"], "…": "the package manifest" },
  "files": {
    "ruleset.json": "<base64>",
    "catalogs/spells.json": "<base64>"
  }
}

Манифест перечисляет ruleset.json и каждый catalogs/<id>.json в contributions.assets.paths и в files, с размером и sha256 (отпечатком файла) каждого. Такой файл создает редактор наборов правил, например Pixelforge. Import agents → Game Mode ruleset принимает файл и показывает тот же обзор, что и для файла набора правил, с каждым каталогом и числом его записей.

Файл читается как данные и никогда не устанавливается как пакет. Ничто в нем не сжато, поэтому он никогда не содержит больше собственного размера. Ограничения:

• Он записывается как local/<its id>, как и файл набора правил.
• Его размер – не больше 132 MB, в нем не больше 12 файлов каталогов по 2 MB каждый и 40 переводов по 8 MB каждый (см. ниже).
• Версия – это набор правил вместе с его каталогами, поэтому измененному каталогу тоже нужна более высокая version.
• Пакеты наборов правил не принимаются в виде zip.

Он отклоняется с указанием причины, если:

• в нем есть другой ключ или любой другой файл либо документ, который не является строгим base64 или текстом UTF-8;
• его манифест запрашивает больше, чем нужно набору правил (любой код, разрешения или другие вклады);
• файл не тот, который перечисляет манифест;
• $comment длиннее 2 000 символов или $schema называет что-либо, кроме собственной схемы Engine;
• набор правил или каталог не читается.

Через официальный каталог агентов

Набор правил, опубликованный в каталоге, – это файл пакета набора правил именно такой формы, <id>.ruleset.json, никогда не zip-пакет. Его манифест объявляет Capability API 1.374 или новее, поэтому более старому Engine он никогда не предлагается. Engine читает его тем же средством и с теми же проверками, что и импортируемый файл пакета, сверяет с манифестом, указанным в каталоге, и устанавливает как любой пакет каталога. Набор правил из каталога, чей артефакт – zip, отклоняется до начала скачивания; уже установленные наборы правил продолжают работать.

Из репозитория GitHub

Если вы храните работу в публичном репозитории GitHub, поместите каждый набор в папку rulesets в корне репозитория, по одному файлу на набор:

your-repository/
  agents.json        (optional, only if you also share agents)
  rulesets/
    ember-roads.json
    another-system.json

Пользователь один раз добавляет ваш репозиторий, просматривает его содержимое и позже синхронизирует его, чтобы получить новые версии. Список пользовательских репозиториев – расширенная возможность. Тот, кто держит сервер, включает ее через ENABLE_CUSTOM_AGENT_REPOS=true, а затем открывает Agents → Agent Organizer → Custom Sources (агенты → организатор агентов → свои источники). Наборы из репозитория записываются под именем владельца репозитория, например alice/ember-roads, поэтому два автора могут опубликовать набор v20 без конфликта.

Есть два ограничения. В репозитории может быть не более 32 файлов JSON непосредственно в rulesets, а репозиторий с большим числом файлов отклоняется. Аккаунт с именем local не может публиковать наборы, поскольку local/ зарезервирован для наборов, импортированных из файла.

В официальном каталоге

Широко используемую систему с чистой лицензией можно предложить всем через Agent Organizer. Чтобы предложить ее, откройте pull request в репозиторий Marinara-Agents. Пример структуры – пакет ruleset-5e-2014 там.

Лицензирование

Публикуйте только тот текст правил, которым вправе делиться. Многие системы выпускают справочный документ по открытой лицензии, и копировать можно именно из него. Укажите в license id лицензии (идентификатор SPDX – короткое стандартное название, например CC-BY-4.0) и текст указания авторства, которого требует лицензия. Не копируйте текст из книг правил без открытой лицензии. Набору в основном нужны названия и числа. Текст Game Master пишите своими словами.

Устранение неполадок

• Импорт сообщает, что имя не существует. Что-то в файле ссылается на необъявленный id, например навык называет удаленную характеристику. Сообщение указывает путь к строке.
• Импорт сообщает, что версия уже установлена с другим содержимым. Поднимите version и импортируйте снова.
• Моего набора нет в мастере настройки. Проверьте, что переключатель Allow custom Agent imports включен. Пока он выключен, импортированные наборы не попадают в новые игры, а игры, которые уже используют такой набор, продолжают работать.
• Игра сообщает, что ее набора правил нет. Точная версия, на которой создана игра, не установлена. Импортируйте эту версию файла снова.