DotTiled/README.md

📚 DotTiled

DotTiled is a simple and easy-to-use library for loading, saving, and managing Tiled maps and tilesets in your .NET projects. After TiledCS unfortunately became unmaintained (since 2022), I aimed to create a new library that could fill its shoes. DotTiled is the result of that effort.

DotTiled is designed to be a lightweight and efficient library that provides a simple API for loading and managing Tiled maps and tilesets. It is built with performance in mind and aims to be as fast and memory-efficient as possible. Targeting netstandard2.0 and net8.0 allows DotTiled to be used in popular game engines like Unity and Godot, as well as in popular game development frameworks like MonoGame.

• Alternative libraries and comparison + benchmarks
• Feature coverage comparison
• Quickstart
  • Installing DotTiled

Alternative libraries and comparison

Other similar libraries exist, and you may want to consider them for your project as well:

Comparison	DotTiled	TiledLib	TiledCSPlus	TiledSharp	TiledCS	TiledNet
Actively maintained	✅	✅	✅	❌	❌	❌
Benchmark (time)*	1.00	1.81	2.12	-	-	-
Benchmark (memory)*	1.00	1.42	2.03	-	-	-
.NET Targets	net8.0 netstandard2.0	net6.0 net7.0	netstandard2.1	netstandard2.0	netstandard2.0	net45
Docs	Usage, XML Docs	Usage	Usage, API, XML Docs	Usage, API	Usage, XML Docs	Usage, XML Docs
License	MIT	MIT	MIT	Apache-2.0	MIT	BSD 3-Clause
Feature coverage comparison below	✅/❌	✅/❌	✅/❌	✅/❌	✅/❌	✅/❌

Note

*Both benchmark time and memory ratios are relative to DotTiled. Lower is better. Benchmark (time) refers to the execution time of loading the same map from an in-memory string that contains XML data in the .tmx format. Benchmark (memory) refers to the memory allocated during that loading process. For further details on the benchmark results, see the collapsible section below.

Benchmark details

The following benchmark results were gathered using the DotTiled.Benchmark project which uses BenchmarkDotNet to compare the performance of DotTiled with other similar libraries. The benchmark results are grouped by category and show the mean execution time, memory consumption metrics, and ratio to DotTiled.

BenchmarkDotNet v0.13.12, Windows 10 (10.0.19045.4651/22H2/2022Update)
12th Gen Intel Core i7-12700K, 1 CPU, 20 logical and 12 physical cores
.NET SDK 8.0.202
  [Host]     : .NET 8.0.3 (8.0.324.11423), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.3 (8.0.324.11423), X64 RyuJIT AVX2

Method	Categories	Mean	Ratio	Gen0	Gen1	Allocated	Alloc Ratio
DotTiled	MapFromInMemoryTmjString	4.292 μs	1.00	0.4349	-	5.62 KB	1.00
DotTiled	MapFromInMemoryTmxString	3.075 μs	1.00	1.2817	0.0610	16.4 KB	1.00
TiledLib	MapFromInMemoryTmxString	5.574 μs	1.81	1.8005	0.0916	23.32 KB	1.42
TiledCSPlus	MapFromInMemoryTmxString	6.546 μs	2.13	2.5940	0.1831	33.16 KB	2.02

MonoGame users may also want to consider using MonoGame.Extended for loading Tiled maps and tilesets. Like MonoGame.Extended, DotTiled also provides a way to properly import Tiled maps and tilesets with the MonoGame content pipeline (with the DotTiled.MonoGame.Pipeline NuGet). However, unlike MonoGame.Extended, DotTiled does not include any kind of rendering capabilities, and it is up to you as a developer to implement any kind of rendering for your maps when using DotTiled. The feature coverage by MonoGame.Extended is less than that of DotTiled, so you may want to consider using DotTiled if you need access to more Tiled features and flexibility.

Feature coverage comparison

Below is a comparison of the feature coverage of DotTiled and other similar libraries. This comparison is based on the features provided by the Tiled map editor and the support for those features in each library. The comparison is not exhaustive, and you may want to refer to the respective library's documentation or implementation for details. Due to some libraries not having obvious documentation or feature lists, some features may be incorrectly marked as not supported. If you find any inaccuracies, please let me know.

Comparison	DotTiled	TiledLib	TiledCSPlus	TiledSharp	TiledCS	TiledNet
XML format .tmx	✅	⚠️	⚠️	⚠️	⚠️	⚠️
JSON format .tmj	✅	⚠️	❌	❌	❌	❌
External tileset callback	✅	✅	❌	✅	❌	❌
Object templates	✅	❌	❌	❌	❌	❌
Custom types (properties)	✅	❌	❌	❌	❌	❌
Hierarchical layers (groups)	✅	❌	❌	✅	❌	✅
Infinite maps	✅	❌	✅	✅	✅	❌
Wangsets	✅	❌	⚠️	⚠️	❌	⚠️

Note

✅ Full support. ⚠️ Partial support, see respective library for details about supported features. ❌ No support.

Quickstart

Installing DotTiled

DotTiled is available as a NuGet package. You can install it by using the NuGet Package Manager UI in Visual Studio, or equivalent, or using the following command for the .NET CLI:

dotnet add package DotTiled