JST.LevelGen 1.0.0-beta.0

LevelGen

LevelGen is a .NET 10 library for assembling 2D tile-based dungeon layouts from reusable prefab blocks.

It includes:

• src\LevelGen: core generator library
• src\LevelGen.Playground: console playground for rerolling maps
• tests\LevelGen.Tests: xUnit tests for parser and generator behavior

Requirements

• .NET SDK 10.0+

Build

dotnet build LevelGen.slnx

Run the playground

From the repository root:

dotnet run --project src\LevelGen.Playground -- --once

The playground will auto-discover blocks.txt (included at src\LevelGen.Playground\blocks.txt), generate a level, print the ASCII map, and exit.

Useful options:

• --blocks <path>: use a specific blocks file
• --seed <int>: deterministic generation
• --max-prefabs <int>: target number of room placements
• --max-corridor-length <int>: generated corridor max length
• --no-loops: disallow extra loop connections
• --no-corridors: disable generated corridors
• --no-mirror: disable mirrored prefab variants
• --once: generate once and exit

Generation model

• Generation is deterministic for a fixed Seed and identical inputs.
• Prefabs are expanded from connectors using backtracking search.
• Open connectors with fewer valid candidates are expanded first to reduce dead-end branching.
• Candidate placements are shuffled with a seeded Fisher-Yates shuffle before recursion.
• Finalization enforces a contiguous walkable floor region and resolves connectors to floor/wall based on whether they were linked.

Use as a library

using LevelGen;
using LevelGen.Blocks;

var text = File.ReadAllText(@"src\LevelGen.Playground\blocks.txt");
var prefabSet = BlocksPrefabParser.Parse(text);

var result = LevelGenerator.Generate(
    prefabSet,
    new GenerationOptions
    {
        Seed = 12345,
        MaxPrefabCount = 6,
        AllowLoops = true,
        AllowGeneratedCorridors = true,
        AllowMirrorTransforms = true,
        MaxCorridorLength = 8
    });

LevelMap map = result.Map;
IReadOnlyList<PlacedPrefab> placements = result.Placements;

blocks.txt format

Prefabs are defined in sections:

• Section header starts with > (for example > Square)
• Tile rows follow the header
• Blank line ends the prefab
• Lines starting with / are comments

Supported tokens:

• # wall
• . floor
• * connector
• ? optional doodad marker (stored as doodad, tile is floor)
• A-P doodad marker (stored as doodad, tile is floor)
• space = empty tile

Test

dotnet test tests\LevelGen.Tests\LevelGen.Tests.csproj

Generate a Cobertura coverage report:

dotnet test tests\LevelGen.Tests\LevelGen.Tests.csproj --collect:"XPlat Code Coverage" --settings coverage.runsettings --results-directory .\TestResults\Coverage

Troubleshooting prefab input

• FormatException during parse typically means a malformed section header (>), unsupported token, or tiles before a prefab header.
• Connectors (*) should represent boundary openings. Ambiguous connector orientation can trigger validation errors during variant generation.