Update README

This commit is contained in:
Daniel Cronqvist 2024-08-03 21:36:07 +02:00
parent 2799fe1fd8
commit e190da7cdf

View file

@ -4,18 +4,9 @@
DotTiled is a simple and easy-to-use library for loading, saving, and managing [Tiled maps and tilesets](https://mapeditor.org) in your .NET projects. After [TiledCS](https://github.com/TheBoneJarmer/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 a simple and easy-to-use library for loading, saving, and managing [Tiled maps and tilesets](https://mapeditor.org) in your .NET projects. After [TiledCS](https://github.com/TheBoneJarmer/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.
- [Feature coverage](#feature-coverage)
- [Alternative libraries and comparison + benchmarks](#alternative-libraries-and-comparison) - [Alternative libraries and comparison + benchmarks](#alternative-libraries-and-comparison)
- [Quickstart](#quickstart) - [Quickstart](#quickstart)
- [Installing DotTiled](#installing-dottiled) - [Installing DotTiled](#installing-dottiled)
- [Constructing a `TmxSerializer`](#constructing-a-tmxserializer)
- [Loading a `.tmx` map](#loading-a-tmx-map)
- [Loading a `.tsx` tileset](#loading-a-tsx-tileset)
- [Constructing a `TmjSerializer`](#constructing-a-tmjserializer)
- [Loading a `.tmj` map](#loading-a-tmj-map)
- [Loading a `.tsj` tileset](#loading-a-tsj-tileset)
# Feature coverage
# Alternative libraries and comparison # Alternative libraries and comparison
@ -24,17 +15,24 @@ Other similar libraries exist, and you may want to consider them for your projec
|**Comparison**|**DotTiled**|[TiledLib](https://github.com/Ragath/TiledLib.Net)|[TiledCSPlus](https://github.com/nolemretaWxd/TiledCSPlus)|[TiledSharp](https://github.com/marshallward/TiledSharp)|[TiledCS](https://github.com/TheBoneJarmer/TiledCS)|[TiledNet](https://github.com/napen123/Tiled.Net)| |**Comparison**|**DotTiled**|[TiledLib](https://github.com/Ragath/TiledLib.Net)|[TiledCSPlus](https://github.com/nolemretaWxd/TiledCSPlus)|[TiledSharp](https://github.com/marshallward/TiledSharp)|[TiledCS](https://github.com/TheBoneJarmer/TiledCS)|[TiledNet](https://github.com/napen123/Tiled.Net)|
|---------------------------------|:-----------------------:|:--------:|:-----------:|:----------:|:-------:|:------:| |---------------------------------|:-----------------------:|:--------:|:-----------:|:----------:|:-------:|:------:|
| Actively maintained | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | Actively maintained | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Docs | Usage,<br>XML Docs | Usage | Usage, API,<br>XML Docs | Usage, API | Usage, XML Docs | Usage, XML Docs |
| License | MIT | MIT | MIT | Apache-2.0 | MIT | BSD 3-Clause | | License | MIT | MIT | MIT | Apache-2.0 | MIT | BSD 3-Clause |
| Benchmark (time)* | 1.00 | 1.81 | 2.12 | - | - | - | | Benchmark (time)* | 1.00 | 1.81 | 2.12 | - | - | - |
| Benchmark (memory)* | 1.00 | 1.42 | 2.03 | - | - | - | | Benchmark (memory)* | 1.00 | 1.42 | 2.03 | - | - | - |
| *Feature coverage<br>comparison*|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | Docs |Usage,<br>XML Docs|Usage|Usage, API,<br>XML Docs|Usage, API|Usage, XML Docs|Usage, XML Docs|
| `.tmx` (Map XML format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | *Feature coverage<br>comparison below*|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| `.tsx` (Tileset XML format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| `.tx` (Template XML format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| > [!NOTE]
| `.tmj` (Map JSON format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| > *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.
| `.tsj` (Tileset JSON format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| `.tj` (Template JSON format) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| <details>
<summary>
Feature coverage comparison
</summary>
| **Comparison**|**DotTiled**|[TiledLib](https://github.com/Ragath/TiledLib.Net)|[TiledCSPlus](https://github.com/nolemretaWxd/TiledCSPlus)|[TiledSharp](https://github.com/marshallward/TiledSharp)|[TiledCS](https://github.com/TheBoneJarmer/TiledCS)|[TiledNet](https://github.com/napen123/Tiled.Net)|
|---------------------------------|:-:|:-:|:-:|:-:|:-:|:-:|
| Full XML support `.tmx` |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| Full JSON support `.tmj` |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| Load from string (implies file) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | Load from string (implies file) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| Load from file |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | Load from file |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| External tilesets |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | External tilesets |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
@ -43,16 +41,13 @@ Other similar libraries exist, and you may want to consider them for your projec
| Hierarchical layers (groups) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | Hierarchical layers (groups) |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
| Infinite maps |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌| | Infinite maps |✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|✅/❌|
> [!NOTE] </details>
> *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.
<details> <details>
<summary> <summary>
Benchmark details Benchmark details
</summary> </summary>
#### Benchmark results
The following benchmark results were gathered using the `DotTiled.Benchmark` project which uses [BenchmarkDotNet](https://benchmarkdotnet.org/) 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. The following benchmark results were gathered using the `DotTiled.Benchmark` project which uses [BenchmarkDotNet](https://benchmarkdotnet.org/) 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.
``` ```