Команды оператора
Все команды, кроме /qs trace, требуют уровень оператора 2. Trace-команды требуют уровень 4, поскольку создают крупные диагностические файлы.
| Команда | Действие |
|---|---|
/qs load <path> | Принимает и планирует загрузку файла и выполнение top-level кода. |
/qs once <path> | Принимает и планирует однократное выполнение файла без Loaded Script. |
/qs unload <scriptId> | Выгружает скрипт и очищает его ресурсы. |
/qs reload <scriptId> | Закрывает скрипт и планирует загрузку его исходного файла заново. |
/qs lifecycle status [<scriptId>] | Возвращает JSON snapshot Loaded Scripts, переходов и последних ошибок. |
/qs lifecycle operation <operationId> | Возвращает JSON состояния одной lifecycle-операции. |
/qs diagnostics threading [<scriptId>] | Возвращает ограниченный JSON snapshot server-thread бюджета и очередей. |
/qs diagnostics build | Возвращает версию, commit, SHA-256 загруженного QuestScript artifact и launcher identity. |
/qs eval js <expression> | Выполняет временное JavaScript-выражение. |
/qs eval py <expression> | Выполняет временное Python-выражение. |
/qs script <scriptId> invoke <method> [args] | Вызывает доступный метод загруженного скрипта. |
/scriptevent <messageId> [message] | Публикует Script Event. |
/qs inventory-leases list | Показывает незавершённые inventory leases. |
/qs inventory-leases restore <leaseId> | Восстанавливает snapshot сейчас или при входе игрока. |
/qs inventory-leases discard <leaseId> | Удаляет snapshot без восстановления. |
/qs trace start [manifestId] | Начинает запись с границы следующего полного серверного тика. |
/qs trace stop | Завершает запись после текущего полного тика и асинхронно публикует dump. |
/qs trace cpu-window start <disabled|enabled> <ticks> | Ставит benchmark-only process-CPU окно на указанное число полных тиков. |
/qs trace cpu-window stop | Закрывает CPU-окно после текущего полного тика до финализации trace. |
path задаётся относительно config/questscript/scripts/. scriptId — имя файла без расширения, в нижнем регистре, с заменой пробелов на _.
Успешный немедленный результат /qs load, /qs reload и /qs once означает,
что операция принята и запланирована, но не что Script Run уже завершён.
Feedback содержит однострочный JSON с operationId, scriptId и действием.
Терминальный результат наблюдается через /qs lifecycle status или
/qs lifecycle operation. Общий status возвращает число Loaded Scripts как
Brigadier result, а feedback содержит versioned JSON с массивами loaded,
transitioning и recentFailures, а также serverTick, на котором сделан snapshot. Lifecycle snapshot и ответ одной операции используют schema version 2; операции содержат nullable runId, когда конкретный Script Run уже был создан или известен.
Watchdog quarantine появляется в recentFailures как действие quarantine, состояние quarantined и runId; такой Script Run уже удалён из loaded и требует новой /qs load. Ответ о принятии операции остаётся отдельным коротким schema-version-1 ticket.
/qs diagnostics threading возвращает schema-version-1 snapshot последней завершённой scripting-фазы, конфигурации бюджета, текущих очередей, переносов, interval skips, overflow, hard-watchdog и lifecycle failures. Вариант с scriptId предпочтителен для точного разбора одного Script Run. Brigadier result равен числу совпавших Loaded Scripts. Глобальный ответ ограничен 64 Script Run и 64 примерами ожидающей работы; на Script Run выдаётся не более 32 interval. Проверяйте scriptSamplesTruncated, pendingWorkSamplesTruncated и intervalSamplesTruncated. Команда только читает метаданные, не входит в Graal Context и не раскрывает исходный код, аргументы, event payload или результаты.
/qs diagnostics build возвращает schema-version-1 JSON с версией мода,
встроенными branch/commit, типом, путём и SHA-256 фактически загруженного
QuestScript code source, SHA-256 production manifest, Java command, classpath и
JVM arguments с редактированием секретов. Команда предназначена для operator
preflight; artifactKind: directory означает dev code source, а не production
JAR. Brigadier result успешного ответа равен 1.
/qs eval выполняется без host filesystem: выражение не может импортировать
файлы из config/questscript/scripts или других каталогов.
messageId команды /scriptevent должен иметь явный вид <namespace>:<path>, например arena:round_start. Namespace — независимый канал сообщений, а не Script ID или идентификатор отправителя. Некорректный ID отклоняется без публикации события.
При неудачном reload старая среда не восстанавливается. discard необратимо удаляет возможность восстановить inventory snapshot.
Trace dumps публикуются в <gameDir>/questscript-traces/ как versioned GZIP NDJSON (.qs-trace.ndjson.gz). Без manifest создаётся диагностическая запись. manifestId вида threading-model:baseline разрешается только внутри <gameDir>/questscript-benchmarks/manifests/ и включает fail-fast проверку окружения и checksum всех Loaded Scripts. Пока dump финализируется, новую запись начать нельзя.
Финализированный dump можно открыть локально в Trace viewer. Страница обрабатывает файл в браузере и не загружает его на сервер.