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.10.0, published on NuGet. This release makes differential testing first class: atlas diff baseline.trx candidate.trx compares two TRX runs and buckets new failures, fixed, vanished, new and still-failing tests plus notable duration shifts, with exit codes that gate CI directly (0 clean, 1 a regression, 2 unreadable input) and a versioned --json shape. IWorldSession.EntitySimulationTicks exposes the embedded server's real entity-simulation tick count, so entity-tick-frequency probes assert exact counts instead of ratios (the release also pins, for the first time, what await World.Ticks(n) does and does not guarantee: Vintage Story has no fixed simulation step). And a prebuilt test assembly now runs against whichever install VINTAGE_STORY points at without a rebuild: Atlas auto-stages the engine assembly at launch, so a suite built once on the newest engine you target runs everywhere older (the full E2E suite built on 1.22.3 runs 105/105 on 1.21.7 and 1.20.12), proven by a new per-push CI lane. Two compatibility fixes round it out: EngineCompat now resolves EnumClientState.Playing and Entity.Pos/ServerPos from the loaded engine by name, so a prebuilt Atlas reads the join lifecycle and spawned-entity positions correctly on the other engine line. Earlier releases 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.