CLI

CLI

The atlas dotnet tool (NuGet package Pixnop.Atlas.Cli) runs the Atlas scenarios of a compiled test assembly without VSTest, through the same in-process xunit runner dotnet test would use. It builds nothing: point it at the compiled test assembly. Two commands: run executes scenarios, fixture authors a prebuilt world save from a builder scenario.

dotnet tool install -g Pixnop.Atlas.Cli

atlas run bin/Debug/net10.0/MyMod.Scenarios.dll              # run everything, sequentially
atlas run bin/Debug/net10.0/MyMod.Scenarios.dll --filter Chest
atlas run bin/Debug/net10.0/MyMod.Scenarios.dll --list       # discover only, no server boot
atlas run bin/Debug/net10.0/MyMod.Scenarios.dll --parallel   # multi-process, one class per worker
atlas fixture bin/Debug/net10.0/MyMod.Scenarios.dll \
      --scenario BuildsCastleWorld --out fixtures/castle.vcdbs   # author a world fixture
atlas --version                                              # print the tool version

run and fixture need VINTAGE_STORY set to the Vintage Story install directory, same as dotnet test (see Getting Started). The variable is validated up front, so a missing install fails fast at the CLI boundary instead of deep inside the first scenario's fixture.

atlas run

Boots the embedded server in-process and executes the assembly's [AtlasScenario] methods sequentially, exactly like dotnet test would: same server, same world lifecycle, one live server per process. Output is a per-scenario PASS/FAIL line with duration, plus a summary; a scenario's non-empty test output (e.g. a rollback-degrade note, see Writing Scenarios) prints indented beneath its PASS/FAIL line.

Exit codes (same contract in every mode):

Code	Meaning
0	Every scenario passed and at least one ran
1	At least one failure or runner error, or nothing ran (an empty run counts as a failure, so a typo'd filter cannot go green in CI)
2	Environment or usage error (VINTAGE_STORY missing, bad arguments)

--filter <substring>

Runs only the scenarios whose display name contains the substring (ordinal, case-insensitive). Display names are the same fully qualified names dotnet test reports. Combines with every mode, including --list and --parallel.

--list

Prints the discovered scenarios and exits without booting anything; VINTAGE_STORY is not required. Useful to sanity-check a --filter before paying for a server boot.

Worker mode: --worker

atlas run <dll> --worker runs exactly like plain run (one process, sequential, same exit codes) but reports exclusively as line-delimited JSON events on stdout: run-start, class-start, test-pass/test-fail/test-skip, class-end, error, run-end, every line versioned with v: 1. All human and engine chatter (the embedded server logs to the console) is rerouted to stderr, and a fail-safe guarantees the stream always ends with a well-formed run-end even when the run crashes.

• --classes <A,B> (worker mode only; a usage error without --worker) restricts the run to the given scenario classes, comma-separated fully qualified names, exact match.
• atlas run <dll> --list --worker performs discovery only: one discovered event per scenario, no server boot, VINTAGE_STORY not required.

Worker mode is the seam the --parallel orchestrator drives, and any tool that wants machine-readable Atlas results can consume it too. The full protocol contract (transport, versioning rules, every event's fields, an example transcript) lives in the repo: docs/specs/2026-07-06-worker-protocol.md.

Parallel execution: --parallel [N]

atlas run <dll> --parallel orchestrates the assembly's scenario classes over N worker subprocesses. The orchestrator discovers the classes without booting anything, then drains a greedy per-class queue: each worker is one atlas run <dll> --worker --classes <class> subprocess (one live server per worker, one class per dispatch), and workers pull the next class as they free up. Results stream back over the worker protocol and print live, per test; the final summary adds per-class wall clocks and the measured speedup versus the sum of class times (what running the classes back to back would have cost).

Default N. Without an explicit count, N is min(cores / 2, class count), always at least 1. Half the cores because each embedded server wants roughly two cores before workers start slowing each other down; capped at the class count because a worker without a class to run is pure overhead.

Crash translation. A worker that dies without a well-formed run-end, exits nonzero without a failing scenario explaining it, or outlives its per-class timeout is translated into a synthesized failed class carrying a stderr tail for forensics, and the queue keeps draining. A crashed worker can fail its class, never shorten the test list.

• --worker-timeout <seconds> (parallel mode only): kills a worker stuck on one class for more than the given time (the whole worker process tree) and reports the class as failed. Default 600 per class: a generous outer defense above the in-process per-scenario watchdog (TimeoutMs), for the day a worker wedges outside any scenario.
• --trx <path> (parallel mode only): writes one aggregated VSTest-style TRX report covering every class, so CI artifact upload and TRX tooling keep working without dotnet test. See CI Recipes.

Flag combination rules: --parallel is incompatible with --worker (workers are what it spawns) and with --list (listing never spawns workers); --worker-timeout and --trx require --parallel; --classes requires --worker.

atlas fixture

atlas fixture authors the prebuilt world save (.vcdbs) that [AtlasWorld(SaveFile = "fixtures/castle.vcdbs")] boots against, turning what used to be folklore (run a builder scenario, then harvest the save its graceful teardown wrote from the host's scratch data path) into a first-class command:

atlas fixture bin/Debug/net10.0/MyMod.Scenarios.dll \
      --scenario BuildsCastleWorld --out fixtures/castle.vcdbs

The builder-scenario contract. The builder is an ordinary [AtlasScenario] on a class deriving from AtlasScenarioBase, whose side effect is building the world: place blocks, run commands, seed data. Nothing marks it as special; any scenario can be a builder.

public class FixtureBuilders : AtlasScenarioBase
{
    [AtlasScenario]
    public async Task BuildsCastleWorld()
    {
        World.PlaceSchematic("fixtures/castle.json", World.Spawn.Offset(20, 0, 20));
        await World.ExecuteCommand("/time set day");
        await World.Ticks(5);
    }
}

How the command behaves:

• --scenario <substring> (required) selects the builder by display-name substring (ordinal, case-insensitive) and must match exactly ONE scenario: zero or several matches is a usage error listing the candidates (exit 2).
• The run uses the same in-process mechanics as atlas run --filter. After the scenario passes and the host tears down gracefully (the graceful shutdown is what makes the engine persist the save), the persisted save is copied to --out.
• --out <path> (required) is where the fixture is written. Parent directories are created as needed; an existing file is only overwritten with --force (refusing without it is a usage error, exit 2).
• A failing builder writes nothing and exits 1, so a broken builder can never silently produce a half-built fixture.

Exit codes: 0 with the fixture written; 1 when the builder failed or left no save (no fixture is written then); 2 on usage errors.

--version

atlas --version (or atlas version) prints the package version (the informational version without the +sha build metadata) and exits 0. It needs no scenario assembly and no VINTAGE_STORY.

Option summary

Option	Modes	Meaning
--filter <substring>	run: all	Only scenarios whose display name contains the substring (ordinal, case-insensitive).
--list	run: plain, worker	Print the discovered scenarios and exit without booting anything.
--worker	run: worker	Report exclusively as JSONL v1 events on stdout; chatter goes to stderr.
--classes <A,B>	run: worker	Run only these scenario classes (fully qualified names, exact match).
--parallel [N]	run: parallel	Run the classes on N worker subprocesses; N defaults to min(cores / 2, class count).
--worker-timeout <s>	run: parallel	Kill a worker stuck on one class for more than <s> seconds (default 600) and fail the class.
--trx <path>	run: parallel	Write one aggregated VSTest-style TRX report covering every class.
--scenario <substring>	fixture	Required: display-name substring selecting the builder scenario; must match exactly one.
--out <path>	fixture	Required: where to write the .vcdbs fixture; parent directories created as needed.
--force	fixture	Overwrite an existing --out file.
--version	all	Print the atlas version and exit (no assembly, no VINTAGE_STORY).
-h, --help	all	Show usage.