From 6349471a583a0b83dbdd277144a6630397cf8985 Mon Sep 17 00:00:00 2001 From: Daniel Cronqvist Date: Sat, 27 Jul 2024 23:53:05 +0200 Subject: [PATCH] Further README updates --- .../TmxSerializer/TestData/TestData.cs | 10 ++++ .../TmxSerializer/TmxSerializer.MapTests.cs | 5 ++ DotTiled/TmxSerializer/TmxSerializer.cs | 8 ++++ README.md | 46 +++++++++++++------ 4 files changed, 56 insertions(+), 13 deletions(-) diff --git a/DotTiled.Tests/TmxSerializer/TestData/TestData.cs b/DotTiled.Tests/TmxSerializer/TestData/TestData.cs index e2e36c9..7dbc2ad 100644 --- a/DotTiled.Tests/TmxSerializer/TestData/TestData.cs +++ b/DotTiled.Tests/TmxSerializer/TestData/TestData.cs @@ -15,4 +15,14 @@ public static class TmxSerializerTestData var xmlStringReader = new StringReader(xml); return XmlReader.Create(xmlStringReader); } + + public static string GetRawStringFor(string testDataFile) + { + var fullyQualifiedTestDataFile = $"DotTiled.Tests.{testDataFile}"; + using var stream = typeof(TmxSerializerTestData).Assembly.GetManifestResourceStream(fullyQualifiedTestDataFile) + ?? throw new ArgumentException($"Test data file '{fullyQualifiedTestDataFile}' not found"); + + using var stringReader = new StreamReader(stream); + return stringReader.ReadToEnd(); + } } diff --git a/DotTiled.Tests/TmxSerializer/TmxSerializer.MapTests.cs b/DotTiled.Tests/TmxSerializer/TmxSerializer.MapTests.cs index ec3f0e8..ceeefe4 100644 --- a/DotTiled.Tests/TmxSerializer/TmxSerializer.MapTests.cs +++ b/DotTiled.Tests/TmxSerializer/TmxSerializer.MapTests.cs @@ -54,14 +54,19 @@ public partial class TmxSerializerMapTests { // Arrange using var reader = TmxSerializerTestData.GetReaderFor(testDataFile); + var testDataFileText = TmxSerializerTestData.GetRawStringFor(testDataFile); Func externalTilesetResolver = (string s) => throw new NotSupportedException("External tilesets are not supported in this test"); var tmxSerializer = new TmxSerializer(externalTilesetResolver); // Act var map = tmxSerializer.DeserializeMap(reader); + var raw = tmxSerializer.DeserializeMap(testDataFileText); // Assert Assert.NotNull(map); AssertMap(map, expectedMap); + + Assert.NotNull(raw); + AssertMap(raw, expectedMap); } } diff --git a/DotTiled/TmxSerializer/TmxSerializer.cs b/DotTiled/TmxSerializer/TmxSerializer.cs index 9ced612..a2ae79e 100644 --- a/DotTiled/TmxSerializer/TmxSerializer.cs +++ b/DotTiled/TmxSerializer/TmxSerializer.cs @@ -1,4 +1,5 @@ using System; +using System.IO; using System.Xml; namespace DotTiled; @@ -17,4 +18,11 @@ public partial class TmxSerializer reader.ReadToFollowing("map"); return ReadMap(reader); } + + public Map DeserializeMap(string xml) + { + using var stringReader = new StringReader(xml); + using var reader = XmlReader.Create(stringReader); + return DeserializeMap(reader); + } } diff --git a/README.md b/README.md index f5692b5..9151f6f 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,46 @@ # 📚 DotTiled -DotTiled is a simple, lightweight, and easy-to-use library for loading, saving, and managing Tiled maps and tilesets 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. + +Other similar libraries exist, and you may want to consider them as well: +| Library | Active | Formats | Docs | License | Benchmark* Rank | +| --- | --- | --- | --- | --- | --- | +| **DotTiled** | ✅ | `.tmx`, `.tsx` | Usage, API, XML docs | MIT | 1 | +| [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) | ❌ | | | | | ## Quickstart -### Loading a map with external tilesets +Here are a few examples to get you started with DotTiled. + +### Loading a `.tmx` map ```csharp -using DotTiled; +var tmxSerializer = new TmxSerializer(); -TmxSerializer tmxSerializer; - -// Tiled can store tilesets in external files or in a map itself -// When they are stored externally, you need to provide a way -// to resolve them given their source path +// A map may or may not contain tilesets that are stored in external +// files. To deserialize a map, you must provide a way to resolve such +// tilesets. Func externalTilesetResolver = (string path) => { - // Load the tileset from however you want - var tilesetXml = fileSystem.ReadAllText(path); - var xmlStringReader = new StringReader(tilesetXml); - var xmlReader = XmlReader.Create(xmlStringReader); - var tmxSerializer = tmxSerializer.DeserializeTileset(xmlReader); + string tilesetXml = fileSystem.ReadAllText(path); + return tmxSerializer.DeserializeTileset(tilesetXml); }; +string mapXml = fileSystem.ReadAllText("path/to/map.tmx"); +Map map = tmxSerializer.DeserializeMap(mapXml, externalTilesetResolver); +``` + +### Loading a `.tsx` tileset + +```csharp +var tmxSerializer = new TmxSerializer(); + +string tilesetXml = fileSystem.ReadAllText("path/to/tileset.tsx"); +Tileset tileset = tmxSerializer.DeserializeTileset(tilesetXml); ``` \ No newline at end of file