Документация: Quest Exporter + Validator

Полное описание режимов, проверок, кнопок и форматов экспорта.

Охват: от загрузки payload до скачивания итоговых JSON.

1. Назначение

Validator нужен для двух задач: проверить корректность квест-графа и получить готовые JSON-выгрузки в нескольких режимах.

  • Вход: payload проекта (nodes, connections, variables, characters, title, version).
  • Промежуточный этап: валидация структуры, связей, достижимости, ссылок, переменных.
  • Выход: Runtime Export, DataAsset Export, Unity Export, Debug Pack.

2. Быстрый сценарий работы

  1. Открой Validator и нажми Request From Architect (или загрузи JSON вручную).
  2. Проверь блок Validation Summary: critical/warning/runtime/unreachable.
  3. Перейди в Diagnostics и обработай список Validation Issues.
  4. Для проблемных нод используй Jump и поправь граф в Architect.
  5. Вернись и нажми Rebuild Exports.
  6. Выбери нужный таб экспорта.
  7. Используй Copy или Download для выдачи результата.

3. Блок Source

Request From Architect

Просит актуальный payload у открытого Quest Architect через postMessage. Это основной рабочий путь внутри редактора.

Load JSON File

Загружает payload из файла. Удобно для оффлайн-проверки версии графа из архива/репозитория.

Paste Raw JSON + Parse JSON

Ручной ввод payload в textarea. Подходит для диагностики маленьких фрагментов и быстрых экспериментов.

Load Sample

Подставляет демонстрационный payload, чтобы проверить интерфейс и выходные форматы без подготовки своих данных.

Source Meta

Показывает источник, имя проекта, количество нод/связей и время последнего обновления данных.

4. Validation Summary

  • Critical: ошибки, при которых граф технически некорректен и экспорт небезопасен.
  • Warnings: рискованные/неполные места, не всегда блокирующие экспорт.
  • Runtime Nodes: число runtime-нод, учитываемых в экспортах.
  • Unreachable: количество нод, недостижимых от Start.

Практика: доводи Critical = 0; предупреждения разбирай по контексту дизайна.

5. Export Options

Pretty JSON formatting

Влияет только на читаемость (отступы). Структура данных не меняется.

Include docs nodes in runtime export

Добавляет layout/doc ноды (comment, group) в runtime-выгрузки. Обычно выключено.

Include source payload in debug export

В Debug Pack добавляется полный исходный payload (sourcePayload) для глубокого разбора.

6. Таб Diagnostics

Validation Issues

Список найденных проблем с кодом и уровнем:

  • critical: broken_connection, missing_start, unresolved link target и т.д.
  • warning: dead-end ветви, пустые поля, недостижимые ноды, дубликаты имен.

Кнопка Jump отправляет фокус к ноде в Architect.

Runtime Diagnostics

Сводные метрики графа (например, Runtime Edges, Avg Out Degree, Branch Nodes, Leaf Nodes, Approx Max Depth).

Дополнительно отображаются UX-метрики завершения: Quest End Nodes, Reachable Quest Ends, Terminal Dead-Ends, Nodes Without End Path, Objective Without End Path.

7. Таб Runtime Export

Базовый runtime JSON для исполнения квеста:

  • meta: служебные поля генерации.
  • graph.startNodeId и graph.nodes[].
  • Каждая нода содержит id, type, title, data, transitions.
  • Также включаются variables и characters.
{
  "graph": {
    "startNodeId": "node_start",
    "nodes": [{ "id": "node_a", "type": "dialog", "data": {}, "transitions": [] }]
  }
}

8. Таб DataAsset Export

Структура с PascalCase-полями и явной схемой:

  • Schema, QuestId, DisplayName, StartNodeId.
  • Variables[], Characters[].
  • Nodes[]: Id, Type, Title, Payload, Links[].
{
  "Schema": "QuestDataAsset.v1",
  "Nodes": [
    {
      "Id": "node_a",
      "Type": "Dialog",
      "Payload": {},
      "Links": [{ "Socket": "choice-0", "To": "node_b", "Kind": "edge" }]
    }
  ]
}

9. Таб Unity Export

Аналогичная по смыслу выгрузка, но в lowerCamelCase:

  • schema, questId, displayName, startNodeId.
  • variables[], characters[].
  • nodes[] с payload и links[].

Это отдельный формат выдачи, удобный для сериализации под Unity-пайплайн.

10. Таб Debug Pack

Пакет для расследования проблем и сверки версий. Внутри:

  • meta, summary, issues, diagnostics.
  • Вложенные результаты всех режимов: runtimeExport, dataAssetExport, unityExport.
  • Опционально sourcePayload (если включен чекбокс Include source payload).

11. Copy / Download / Rebuild / Jump

Copy

Копирует содержимое текущего активного таба в буфер обмена.

Download

Скачивает JSON текущего таба. Имена файлов задаются автоматически:

  • quest_runtime_export.json
  • quest_dataasset_export.json
  • quest_unity_export.json
  • quest_debug_pack.json

Rebuild Exports

Повторно считает валидацию и пересобирает все выгрузки на основе текущего payload и выбранных опций.

Jump To Start

Переход к Start-ноде в Architect (через bridge-сообщение).

12. Status и интерпретация

  • Waiting for data: payload еще не загружен.
  • Requesting payload from architect...: отправлен запрос в Architect.
  • Validation failed: critical issues: есть критические ошибки.
  • Validation has warnings: критических нет, но есть предупреждения.
  • Validation passed: критических и предупреждений нет.

13. Troubleshooting

Пусто после Request From Architect

  • Убедись, что Validator открыт из Architect, а не отдельной вкладкой.
  • Нажми Request повторно или перезагрузи Architect.
  • Если нужно, загрузи payload вручную через File/Paste.

Неактивен экспорт / пустые output

  • Проверь, что payload успешно распарсен.
  • Нажми Rebuild Exports.
  • Проверь статус-строку и список issues.

Много unreachable / cycles

Начни с Start и Link State/Link Entry связок, затем проверь default/true/false ветви и отсутствующие sockets.

14. Checklist перед экспортом

  1. Critical = 0.
  2. Все важные warning разобраны осознанно.
  3. Start есть и ведет в рабочий путь.
  4. Нет битых ссылок и пустых обязательных полей.
  5. Выбраны корректные Export Options.
  6. Проверен нужный формат (Runtime/DataAsset/Unity/Debug).
  7. Выгрузка выполнена через Copy или Download.