feat(tiled): load maps made in the Tiled editor (TILE-1)

.gitignore

@@ -98,3 +98,8 @@ dist/
 ## Experimental mobile hosts (platforms/)
 
 platforms/android/native/out/
+
+# Local promotional media (trailers, channel art): kept on the maintainer's machine, never in the repository
+/trailer/
+/trailer-*/
+/channel-art/

AGENTS.md

@@ -20,8 +20,9 @@ sufficient without previous chats or agent memory.
 - The active rebuild record (specs, tasks, log) is [`odd/tasks/engine-rebuild.md`](odd/tasks/engine-rebuild.md); the latest
   feature records are [`odd/tasks/docs-1.md`](odd/tasks/docs-1.md), [`odd/tasks/sdk-1.md`](odd/tasks/sdk-1.md),
   [`odd/tasks/input-1.md`](odd/tasks/input-1.md), [`odd/tasks/product-1.md`](odd/tasks/product-1.md),
-  [`odd/tasks/asset-1.md`](odd/tasks/asset-1.md) (the asset pipeline, ADR 0025) and
-  [`odd/tasks/demo-refresh.md`](odd/tasks/demo-refresh.md) (the four demos modernized, new art for the two hybrids).
+  [`odd/tasks/asset-1.md`](odd/tasks/asset-1.md) (the asset pipeline, ADR 0025),
+  [`odd/tasks/demo-refresh.md`](odd/tasks/demo-refresh.md) (the four demos modernized, new art for the two hybrids) and
+  [`odd/tasks/tile-1.md`](odd/tasks/tile-1.md) (maps from the Tiled editor, the optional `MicroEngine.Tiled` package, ADR 0052).
 - CI ([docs/ci.md](docs/ci.md), ADR 0013): `ci.yml` runs the checks a change needs, once per content (evidence),
   the SDK check included; `validate.yml` runs everything on demand; `platforms.yml` holds the monthly and manual
   macOS, Android and iOS experiments of [`platforms/`](platforms/README.md), which are not supported platforms. Demos

MicroEngine.slnx

@@ -16,6 +16,7 @@
     <Project Path="src/MicroEngine.Saves/MicroEngine.Saves.csproj" />
     <Project Path="src/MicroEngine.Text/MicroEngine.Text.csproj" />
     <Project Path="src/MicroEngine.Text.Shaping/MicroEngine.Text.Shaping.csproj" />
+    <Project Path="src/MicroEngine.Tiled/MicroEngine.Tiled.csproj" />
     <Project Path="src/MicroEngine.Achievements/MicroEngine.Achievements.csproj" />
     <Project Path="src/MicroEngine.UI/MicroEngine.UI.csproj" />
     <Project Path="src/MicroEngine/MicroEngine.csproj" />
@@ -34,6 +35,7 @@
   </Folder>
   <Folder Name="/benchmarks/">
     <Project Path="benchmarks/AssetBench/AssetBench.csproj" />
+    <Project Path="benchmarks/MapBench/MapBench.csproj" />
     <Project Path="benchmarks/PerfBench/PerfBench.csproj" />
     <Project Path="benchmarks/PhysicsBench/PhysicsBench.csproj" />
     <Project Path="benchmarks/WorldBench/WorldBench.csproj" />
@@ -44,6 +46,7 @@
     <Project Path="samples/AssetGallery/AssetGallery.csproj" />
     <Project Path="samples/Slice3D/Slice3D.csproj" />
     <Project Path="samples/PhysicsSubstitution/PhysicsSubstitution.csproj" />
+    <Project Path="samples/TiledLevel/TiledLevel.csproj" />
   </Folder>
   <Folder Name="/samples/GemGarden/part1-scenes/">
     <Project Path="samples/GemGarden/part1-scenes/GemGarden.csproj" />
@@ -63,6 +66,7 @@
   <Folder Name="/tests/">
     <Project Path="tests/MicroEngine.Tests/MicroEngine.Tests.csproj" />
     <Project Path="tests/MicroEngine.Physics.Box2D.Tests/MicroEngine.Physics.Box2D.Tests.csproj" />
+    <Project Path="tests/MicroEngine.Tiled.Tests/MicroEngine.Tiled.Tests.csproj" />
     <Project Path="tests/MicroEngine.Graphics.Tests/MicroEngine.Graphics.Tests.csproj" />
     <Project Path="tests/MicroEngine.Graphics3D.Tests/MicroEngine.Graphics3D.Tests.csproj" />
     <Project Path="tests/MicroEngine.Raylib.Tests/MicroEngine.Raylib.Tests.csproj" />

THIRD-PARTY-NOTICES.md

@@ -73,6 +73,14 @@ Games that add the optional `MicroEngine.Physics.Box2D` package also ship Box2D,
 | --- | --- | --- | --- |
 | Box2D 3.2.0 | 2D rigid-body physics: dynamic bodies, collision, queries and the character mover | MIT | Copyright (c) 2022 Erin Catto |
 
+## Optional Tiled maps
+
+Games that add the optional `MicroEngine.Tiled` package also ship DotTiled, a managed library, inside their build.
+
+| Component | Use | Licence | Copyright |
+| --- | --- | --- | --- |
+| DotTiled 1.0.0 | Reading maps, tilesets and templates saved by the Tiled editor (TMX, TMJ, TSX, TSJ, TX, TJ) | MIT | Copyright (c) 2025 Daniel Cronqvist |
+
 ## Browser builds of the demos
 
 Each browser package also contains the .NET runtime compiled to WebAssembly and code generated by Emscripten. The

benchmarks/MapBench/MapBench.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <RootNamespace>MapBench</RootNamespace>
+    <Description>Times large Tiled maps: loading and parsing, and drawing what a camera shows at zoom 1 and 0.5.</Description>
+    <!-- It writes its maps into a temporary folder; it ships no files. -->
+    <MicroEngineContentItems>false</MicroEngineContentItems>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../../src/MicroEngine.Tiled/MicroEngine.Tiled.csproj" />
+  </ItemGroup>
+</Project>

benchmarks/MapBench/Program.cs

@@ -0,0 +1,121 @@
+using System.Diagnostics;
+using System.Globalization;
+using System.IO.Compression;
+using System.Numerics;
+using System.Text.Json;
+using MicroEngine;
+using MicroEngine.Core;
+using MicroEngine.Graphics;
+using MicroEngine.Tiled;
+
+// Times large Tiled maps (TILE-1's measurements):
+//
+//   MapBench [--size N] [--layers L] [--runs R]
+//
+// Writes an N × N map of 16-pixel tiles (1000 × 1000 by default) with L tile layers (3), each base64 and zlib
+// compressed as Tiled saves it, then times loading it through the asset cache (parsing, decompressing, building the
+// layers) and one frame of drawing every layer with a 320 × 180 camera at zoom 1 and zoom 0.5, on the headless
+// renderer: the CPU cost of culling and submitting, not the GPU's. Each timing is the median of R runs (5) after one
+// warm-up run; allocations are measured on this thread.
+int size = 1000, layers = 3, runs = 5;
+for (int i = 0; i < args.Length; i++)
+    switch (args[i])
+    {
+        case "--size": size = int.Parse(args[++i], CultureInfo.InvariantCulture); break;
+        case "--layers": layers = int.Parse(args[++i], CultureInfo.InvariantCulture); break;
+        case "--runs": runs = int.Parse(args[++i], CultureInfo.InvariantCulture); break;
+    }
+
+var folder = Directory.CreateTempSubdirectory("microengine-mapbench");
+try
+{
+    long fileBytes = WriteMap(folder.FullName, size, layers);
+    Console.WriteLine($"# MapBench: {size} × {size} tiles, {layers} layers, file {fileBytes / 1024.0:0} KB, .NET {Environment.Version}, {runs} runs (median)");
+    Console.WriteLine();
+    Console.WriteLine("| Measurement | Median | Allocated |");
+    Console.WriteLine("| --- | ---: | ---: |");
+
+    var device = new HeadlessGraphicsDevice();
+    TiledMap map = null!;
+    Row("Load the map (parse, decompress, build layers)", () =>
+    {
+        using var assets = new AssetCache(device, folder.FullName);
+        map = assets.TiledMap("map.tmj");
+    });
+    var keep = new AssetCache(device, folder.FullName);
+    map = keep.TiledMap("map.tmj");
+    var sprites = new TiledSprites(map, keep);
+    var renderer = new HeadlessRenderer(320, 180);
+    foreach (float zoom in new[] { 1f, 0.5f })
+    {
+        var camera = new Camera2D(320, 180) { Zoom = zoom };
+        camera.CenterOn(new Vector2(map.PixelWidth / 2f, map.PixelHeight / 2f));
+        renderer.Reset();
+        sprites.DrawAll(renderer, camera);
+        int draws = renderer.DrawCalls;
+        Row(string.Create(CultureInfo.InvariantCulture, $"Draw one frame at zoom {zoom} ({draws} tiles)"), () =>
+        {
+            renderer.Reset();
+            sprites.DrawAll(renderer, camera);
+        }, "µs", 1000);
+    }
+    long cells = (long)size * size * layers;
+    Console.WriteLine();
+    Console.WriteLine(string.Create(CultureInfo.InvariantCulture, $"Layer memory: {cells * (sizeof(int) + 1) / (1024.0 * 1024):0.0} MB ({cells:N0} cells: an id and an orientation each)."));
+}
+finally { folder.Delete(recursive: true); }
+
+void Row(string name, Action action, string unit = "ms", double scale = 1)
+{
+    action();
+    var times = new List<double>();
+    long allocated = 0;
+    for (int i = 0; i < runs; i++)
+    {
+        long before = GC.GetAllocatedBytesForCurrentThread();
+        var watch = Stopwatch.StartNew();
+        action();
+        times.Add(watch.Elapsed.TotalMilliseconds * scale);
+        allocated = GC.GetAllocatedBytesForCurrentThread() - before;
+    }
+    times.Sort();
+    Console.WriteLine(string.Create(CultureInfo.InvariantCulture, $"| {name} | {times[times.Count / 2]:0.##} {unit} | {allocated / 1024.0:0} KB |"));
+}
+
+// A map as Tiled saves it: one embedded tileset over a 64 × 64 image of four tiles, and every layer filled with a
+// pattern of all four (empty cells included), base64 over zlib.
+static long WriteMap(string folder, int size, int layers)
+{
+    var image = new PixelImage(64, 64);
+    for (int y = 0; y < 64; y++)
+        for (int x = 0; x < 64; x++) image[x, y] = new Color((byte)(x * 4), (byte)(y * 4), 128);
+    File.WriteAllBytes(Path.Combine(folder, "tiles.png"), PngEncoder.Encode(image.ToRgba(), image.Width, image.Height));
+    var layerList = new List<object>();
+    for (int l = 0; l < layers; l++)
+    {
+        var raw = new byte[size * size * 4];
+        for (int i = 0; i < size * size; i++) BitConverter.TryWriteBytes(raw.AsSpan(i * 4), (uint)((i * 7 + l * 3) % 17 % 5));
+        using var packed = new MemoryStream();
+        using (var z = new ZLibStream(packed, CompressionLevel.Fastest)) z.Write(raw);
+        layerList.Add(new Dictionary<string, object>
+        {
+            ["type"] = "tilelayer", ["id"] = l + 1, ["name"] = $"layer{l}", ["x"] = 0, ["y"] = 0, ["width"] = size, ["height"] = size,
+            ["opacity"] = 1, ["visible"] = true, ["encoding"] = "base64", ["compression"] = "zlib", ["data"] = Convert.ToBase64String(packed.ToArray()),
+        });
+    }
+    var map = new Dictionary<string, object>
+    {
+        ["type"] = "map", ["version"] = "1.10", ["tiledversion"] = "1.11.0", ["orientation"] = "orthogonal", ["renderorder"] = "right-down",
+        ["width"] = size, ["height"] = size, ["tilewidth"] = 16, ["tileheight"] = 16, ["infinite"] = false, ["compressionlevel"] = -1,
+        ["nextlayerid"] = layers + 1, ["nextobjectid"] = 1,
+        ["tilesets"] = new object[] { new Dictionary<string, object>
+        {
+            ["firstgid"] = 1, ["name"] = "tiles", ["tilewidth"] = 16, ["tileheight"] = 16, ["tilecount"] = 16, ["columns"] = 4,
+            ["image"] = "tiles.png", ["imagewidth"] = 64, ["imageheight"] = 64, ["margin"] = 0, ["spacing"] = 0,
+        } },
+        ["layers"] = layerList,
+    };
+    string path = Path.Combine(folder, "map.tmj");
+    File.WriteAllText(path, JsonSerializer.Serialize(map));
+    return new FileInfo(path).Length;
+}

docs/api/MicroEngine.Tiled.TiledAssets.md

@@ -0,0 +1,99 @@
+# Class TiledAssets
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Tiled](MicroEngine.Tiled.md)  
+Assembly: MicroEngine.Tiled.dll  
+Guide: [Maps from Tiled](../manual/world.md#maps-from-tiled)  
+
+The <code>tiled map</code> asset kind: a Tiled map (<code>.tmx</code> or <code>.tmj</code>) with the tilesets (<code>.tsx</code>,
+<code>.tsj</code>) and templates (<code>.tx</code>, <code>.tj</code>) it references, read through the store's content source so it
+loads from folders, archives and browser packages alike. The asset is data ([TiledMap](MicroEngine.Tiled.TiledMap.md)); its
+tile images become textures with [TiledSprites](MicroEngine.Tiled.TiledSprites.md).
+
+```csharp
+public static class TiledAssets
+```
+
+#### Inheritance
+
+[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
+[TiledAssets](MicroEngine.Tiled.TiledAssets.md)
+
+## Fields
+
+### <a id="MicroEngine_Tiled_TiledAssets_Kind"></a> Kind
+
+The asset kind.
+
+```csharp
+public const string Kind = "tiled map"
+```
+
+#### Field Value
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Properties
+
+### <a id="MicroEngine_Tiled_TiledAssets_Loader"></a> Loader
+
+The loader of the <code>tiled map</code> kind (extensions <code>.tmx</code> and <code>.tmj</code>).
+
+```csharp
+public static IAssetLoader<TiledMap> Loader { get; }
+```
+
+#### Property Value
+
+ [IAssetLoader](MicroEngine.Content.IAssetLoader.md)<[TiledMap](MicroEngine.Tiled.TiledMap.md)\>
+
+## Methods
+
+### <a id="MicroEngine_Tiled_TiledAssets_AddTiledMaps_MicroEngine_Content_AssetLoaderRegistry_"></a> AddTiledMaps\(AssetLoaderRegistry\)
+
+Registers the <code>tiled map</code> kind on <code class="paramref">loaders</code>.
+
+```csharp
+public static AssetLoaderRegistry AddTiledMaps(this AssetLoaderRegistry loaders)
+```
+
+#### Parameters
+
+`loaders` [AssetLoaderRegistry](MicroEngine.Content.AssetLoaderRegistry.md)
+
+#### Returns
+
+ [AssetLoaderRegistry](MicroEngine.Content.AssetLoaderRegistry.md)
+
+<code class="paramref">loaders</code>, for chaining.
+
+### <a id="MicroEngine_Tiled_TiledAssets_TiledMap_MicroEngine_Core_AssetCache_System_String_"></a> TiledMap\(AssetCache, string\)
+
+The map at <code class="paramref">path</code>, loaded once per scope like any asset (the kind is registered on first use).
+
+```csharp
+public static TiledMap TiledMap(this AssetCache assets, string path)
+```
+
+#### Parameters
+
+`assets` [AssetCache](MicroEngine.Core.AssetCache.md)
+
+The game's assets (<code>Game.Assets</code>) or one of its scopes.
+
+`path` [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+The map's content path.
+
+#### Returns
+
+ [TiledMap](MicroEngine.Tiled.TiledMap.md)
+
+#### Exceptions
+
+ [AssetLoadException](MicroEngine.Core.AssetLoadException.md)
+
+The map, or a file it references, is missing or not a map Tiled saves; or the map is not orthogonal.
+
+</div>