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.9.0, published on NuGet. This release lowers the supported game-version floor from 1.22 to 1.21 (1.20.x compatible best-effort) through the boot-validated EngineCompat runtime shim, with 1.21.7 tested on every push. It adds [AtlasTheory], the theory-style counterpart to [AtlasScenario] (contributed by Seggr, Atlas's first external contribution): each [InlineData]/[MemberData] row runs as its own scenario. Test players now reach the engine's Playing client state by default, so server systems that filter or count Playing players finally see them. The per-class isolation summaries are richer (FreshWorld-only classes report their recycle cost, and a rollback class's first capture is its own line item). Two fixes round it out: rollback database access now runs inside the engine's own suspend window instead of racing the chunk thread, and an engine-initiated shutdown fails the scenario fast with ServerCrashedException instead of hanging until the watchdog. Earlier releases 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
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, 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.