Home

Atlas

Atlas is an in-process integration-test harness for Vintage Story mods. It boots a real, headless Vintage Story server inside your dotnet test process, drives it tick by tick, and lets you write deterministic scenarios in plain C# with xUnit.

Atlas is generic: any Vintage Story mod is testable, with no dependency on any particular mod.

Current version: v0.11.0, published on NuGet. This small release completes the differential-CI toolkit, both pieces from StratumParity field feedback: atlas diff --json-tests adds a per-test tests array (outcome, duration, stdout) to the diff's JSON document, so a differential pipeline's markdown summary or history dashboard can read it straight from atlas diff --json instead of a hand-rolled TRX parser. And atlas stage <dir-or-dll> explicitly pre-stages the engine assembly ahead of a --no-build run, so a one-shot cross-install script (atlas stage out/ && VINTAGE_STORY=... dotnet test --no-build) boots green on the first try instead of needing the fail-then-rerun cycle that plain auto-staging still pays on the first switch to a new install. Earlier releases made differential testing first class (atlas diff, exit codes gating CI directly), exposed the embedded server's real entity-simulation tick count (IWorldSession.EntitySimulationTicks), added engine-assembly auto-staging so a prebuilt test assembly runs against whichever install VINTAGE_STORY points at without a rebuild, lowered the supported floor to 1.21 (1.20.x best-effort) through the EngineCompat shim, added [AtlasTheory] (contributed by Seggr), brought test players to the Playing client state, made world rollback universal (joined players, mini-dimensions, the atlas:rollback:* mod-cooperation hooks), completed the isolation trilogy (FreshWorld/RollbackWorld/RestartWorld), and added atlas fixture world-fixture authoring, IWorldSession.PlaceSchematic, multi-process parallel execution (atlas run --parallel), the machine-readable worker mode (--worker, JSONL events), the atlas CLI itself and pre-boot data file seeding ([AtlasDataFiles]). See the changelog for the full history.

15-line example

using Atlas.Api;
using Atlas.XUnit;
using Vintagestory.API.MathTools;
using Xunit;

public class MarkerScenarios : AtlasScenarioBase
{
    [AtlasScenario]
    public async Task Chest_Should_BePlaceable_When_WorldIsReady()
    {
        BlockPos pos = World.Spawn.Offset(1, 1, 0);
        World.SetBlock("game:chest-east", pos);
        await World.Ticks(5);
        Assert.Equal("game:chest-east", World.BlockAt(pos).Code.ToString());
    }
}

Run it with dotnet test. No client, no window, no manual server setup.

Documentation

Page	Covers
Getting Started	Requirements, quickstart, first scenario, run
Writing Scenarios	Attribute reference, parameterized scenarios ([AtlasTheory]), time model, the world-isolation trilogy (fresh, rollback, restart), world fixtures and schematics, data file seeding, dimensions, test players, command results, the Api escape hatch
Mod Staging	Folder/zip/dll staging, AtlasMods, the MSBuild AtlasMod sugar
CLI	The atlas run reference, filtering and listing, worker mode and the JSONL protocol, multi-process --parallel execution, authoring world fixtures with atlas fixture, differential TRX comparison with atlas diff
Architecture	The three layers, the game-thread pump, the bridge rendezvous
CI Recipes	GitHub Actions recipe, version matrix, TRX output, parallel execution
Compatibility	Supported Vintage Story versions, multi-install auto-staging (build newest, run older), the weekly sweep
Troubleshooting	Common exceptions and how to resolve them
Roadmap	Open issues and what's next

Community

• Mod DB page: follow releases and leave feedback.
• NuGet package.
• Issue tracker: bug reports and feature requests.