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.8.0, published on NuGet. This release makes world rollback universal: RollbackWorld = true now also rolls back joined test players (position, inventories, stats, per-player moddata; post-capture joiners removed cleanly) and every mini-dimension (boot-time pregenerated ones included), and mods keep their own SaveGame-keyed in-memory state in sync through the new atlas:rollback:captured / atlas:rollback:restored event-bus hooks (VintagestoryAPI types only, validated against a real consumer's dimension registry). Isolation costs are first-class too: restart and degrade costs land in the scenario's own test output and in the per-class isolation summaries, which atlas run --parallel now aggregates into its output and TRX report. Earlier releases 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, 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.