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.5.0, published on NuGet. Recent releases added pre-boot data file seeding ([AtlasDataFiles]), prebuilt world saves ([AtlasWorld(SaveFile = ...)]), ITestPlayer.IsConnected, headless test players (several per world, each with its own connection and inventory), entity stats, and command results (ExecuteCommand returns the command's outcome). 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, world isolation and fixtures, data file seeding, dimensions, test players, command results, the Api escape hatch
Mod Staging	Folder/zip/dll staging, AtlasMods, the MSBuild AtlasMod sugar
Architecture	The three layers, the game-thread pump, the bridge rendezvous
CI Recipes	GitHub Actions recipe, version matrix, TRX output
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.