Loading Tilemaps

TmjLoader reads Tiled JSON maps (.tmj) and returns a Tilemap ready for use. It's injected via ITilemapLoader once you call AddTilemapServices().

Setup

Register the tilemap services in your game builder:

builder.Services.AddTilemapServices();

This registers:

• ITilemapLoader → TmjLoader (singleton)
• TilemapAnimator (transient)
• TilemapSystem (transient)

Loading a Map

Inject ITilemapLoader and call LoadAsync in your scene's OnLoadAsync:

public class GameScene : Scene
{
    private readonly ITilemapLoader _loader;

    public GameScene(ITilemapLoader loader)
    {
        _loader = loader;
    }

    protected override async Task OnLoadAsync(CancellationToken ct)
    {
        var tilemap = await _loader.LoadAsync("assets/maps/level1.tmj", ct);

        World.CreateEntity()
            .AddComponent<TilemapComponent>(c => c.Tilemap = tilemap);
    }
}

LoadAsync throws on invalid files — it never returns null. If the file is missing, malformed, or uses an unsupported map type, you'll get a descriptive exception.

Tilesets

Embedded tilesets

Tilesets defined directly in the .tmj file are loaded automatically — no extra configuration needed.

External tilesets (.tsj)

Tilesets saved as separate .tsj files are also supported. Brine2D resolves the .tsj path relative to the .tmj file, exactly as Tiled stores it.

Tile Data Encodings

Brine2D supports all tile data formats Tiled can export:

Encoding	Supported
CSV (array)
Base64 (uncompressed)
Base64 + zlib
Base64 + gzip
Base64 + zstd

You can choose any of these in Tiled under Map → Map Properties → Tile Layer Format.

Supported Map Types

Layer Types

All Tiled layer types are handled:

Group layers are never surfaced directly. Their visibility, opacity, tint, offset, and parallax are composed into each child layer.

Copying Assets to Output

Make sure your map and tileset files are copied during build. Add this to your .csproj:

<ItemGroup>
  <None Update="assets\**\*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

What Gets Loaded

After LoadAsync returns, the Tilemap object contains:

Next: Rendering