Operator commands
Every command except /qs trace requires operator level 2. Trace commands require level 4 because they create large diagnostic files.
| Command | Action |
|---|---|
/qs load <path> | Accepts and schedules a file load and top-level evaluation. |
/qs once <path> | Accepts and schedules a one-time run without a Loaded Script. |
/qs unload <scriptId> | Unloads a Script and cleans its resources. |
/qs reload <scriptId> | Closes a Script and schedules its source to load again. |
/qs lifecycle status [<scriptId>] | Returns a JSON snapshot of Loaded Scripts, transitions, and recent failures. |
/qs lifecycle operation <operationId> | Returns JSON state for one lifecycle operation. |
/qs diagnostics threading [<scriptId>] | Returns a bounded JSON snapshot of server-thread budget and queues. |
/qs diagnostics build | Returns the version, commit, loaded QuestScript artifact SHA-256, and launcher identity. |
/qs eval js <expression> | Evaluates a temporary JavaScript expression. |
/qs eval py <expression> | Evaluates a temporary Python expression. |
/qs script <scriptId> invoke <method> [args] | Calls an available method on a loaded Script. |
/scriptevent <messageId> [message] | Publishes a Script Event. |
/qs inventory-leases list | Lists unfinished inventory leases. |
/qs inventory-leases restore <leaseId> | Restores a snapshot now or when the player joins. |
/qs inventory-leases discard <leaseId> | Deletes a snapshot without restoration. |
/qs trace start [manifestId] | Starts capture at the next complete server-tick boundary. |
/qs trace stop | Ends capture after the current complete tick and publishes the dump asynchronously. |
/qs trace cpu-window start <disabled|enabled> <ticks> | Arms the benchmark-only process-CPU window for the requested complete ticks. |
/qs trace cpu-window stop | Closes the CPU window after the current complete tick and before trace finalization. |
path is relative to config/questscript/scripts/. scriptId is the filename without its extension, lowercased, with spaces replaced by _.
An immediate successful result from /qs load, /qs reload, or /qs once
means that the operation was accepted and scheduled, not that Script Run has
already completed. Feedback contains one-line JSON with the operationId,
scriptId, and action. Observe the terminal result through /qs lifecycle status or /qs lifecycle operation. The general status command returns the
Loaded Script count as its Brigadier result and emits versioned JSON with
loaded, transitioning, and recentFailures arrays plus the serverTick on
which the snapshot was observed. Lifecycle snapshots and single-operation responses use schema version 2; operations contain a nullable runId once a concrete Script Run has been created or is otherwise known.
Watchdog quarantine appears in recentFailures with action quarantine, state quarantined, and its runId; that Script Run is no longer in loaded and requires a new /qs load. The operation-accepted response remains a separate short schema-version-1 ticket.
/qs diagnostics threading returns a schema-version-1 snapshot of the last completed scripting phase, configured budget, current queues, deferrals, interval skips, overflow, hard watchdog, and lifecycle failures. Prefer the scriptId form when investigating one Script Run. Its Brigadier result is the number of matching Loaded Scripts. A global response is capped at 64 Script Runs and 64 pending-work samples, with at most 32 interval samples per Script Run. Check scriptSamplesTruncated, pendingWorkSamplesTruncated, and intervalSamplesTruncated. The command reads metadata only, never enters a Graal Context, and exposes no Script source, arguments, event payloads, or results.
/qs diagnostics build returns schema-version-1 JSON containing the mod version,
embedded branch/commit, kind, path and SHA-256 of the actually loaded QuestScript
code source, production-manifest SHA-256, Java command, classpath, and JVM
arguments with secrets redacted. It is an operator preflight surface;
artifactKind: directory identifies a development code source rather than a
production JAR. A successful response has Brigadier result 1.
/qs eval runs without a host filesystem: the expression cannot import files
from config/questscript/scripts or any other directory.
The /scriptevent messageId must use the explicit <namespace>:<path> form, for example arena:round_start. Its namespace is an independent messaging channel, not a Script ID or sender identity. An invalid ID is rejected without publishing an event.
A failed reload does not restore the previous environment. discard permanently removes the ability to restore that inventory snapshot.
Trace dumps are published below <gameDir>/questscript-traces/ as versioned GZIP NDJSON (.qs-trace.ndjson.gz). Starting without a manifest creates a diagnostic capture. A manifestId such as threading-model:baseline resolves only below <gameDir>/questscript-benchmarks/manifests/ and enables fail-fast environment and Loaded Script checksum validation. A new capture cannot start while a dump is finalizing.
Open a finalized dump locally in the Trace viewer. The page processes the file in the browser and does not upload it to a server.