From a9ad1840b022e018750b3239889cb63b1b7a583a Mon Sep 17 00:00:00 2001 From: Daniel Cronqvist Date: Wed, 28 Aug 2024 16:53:49 +0200 Subject: [PATCH] Add some docs --- .../{ => essentials}/custom-properties.md | 4 +- docs/docs/essentials/loading-maps.md | 43 +++++++++++++++++++ docs/docs/loading-a-map.md | 1 - docs/docs/toc.yml | 4 +- 4 files changed, 47 insertions(+), 5 deletions(-) rename docs/docs/{ => essentials}/custom-properties.md (96%) create mode 100644 docs/docs/essentials/loading-maps.md delete mode 100644 docs/docs/loading-a-map.md diff --git a/docs/docs/custom-properties.md b/docs/docs/essentials/custom-properties.md similarity index 96% rename from docs/docs/custom-properties.md rename to docs/docs/essentials/custom-properties.md index 78cbd00..934882c 100644 --- a/docs/docs/custom-properties.md +++ b/docs/docs/essentials/custom-properties.md @@ -78,7 +78,7 @@ Whenever DotTiled encounters a property that is of type `class` in a Tiled file, For example, if you have a `class` property in Tiled that looks like this: -![MonsterSpawner class in Tiled UI](../images/monster-spawner-class.png) +![MonsterSpawner class in Tiled UI](../../images/monster-spawner-class.png) The equivalent definition in DotTiled would look like the following: @@ -102,7 +102,7 @@ Tiled also allows you to define custom property types that work as enums. Simila For example, if you have a custom property type in Tiled that looks like this: -![EntityType enum in Tiled UI](../images/entity-type-enum.png) +![EntityType enum in Tiled UI](../../images/entity-type-enum.png) The equivalent definition in DotTiled would look like the following: diff --git a/docs/docs/essentials/loading-maps.md b/docs/docs/essentials/loading-maps.md new file mode 100644 index 0000000..d9db195 --- /dev/null +++ b/docs/docs/essentials/loading-maps.md @@ -0,0 +1,43 @@ +# Loading maps + +Loading maps with DotTiled is straightforward and easy. The class is a representation of a Tiled map, mimicking the structure of a Tiled map file. Map files can either be in the [`.tmx`/XML](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/) or [`.tmj`/json](https://doc.mapeditor.org/en/stable/reference/json-map-format/) format. DotTiled supports **both** formats fully. + +> [!TIP] +> Using the `.tmj` file format will result in not having the same amount of information as for `.tmx` format. This is due to the fact that the `.tmj` format does not include the full information that the `.tmx` format does. This is not a problem with DotTiled, but rather a limitation of the `.tmj` format. + +## External resolution + +Tiled maps may consist of several external files, such as tilesets and object templates. In Tiled map files, these are typically referenced by their path relative to the map file. It would be annoying to have to first load all these external resources before loading a map, so loading a map with DotTiled is designed in a way that you only have to provide a function that resolves these external resources. This way, DotTiled will figure out which external resources are needed and will invoke the corresponding resolver function to load them. + +Loading a map, tileset, or template will require you to specify **three** resolver functions + +### `Func` - Tileset resolver + +This function is used to resolve external tilesets by their source path. The function should return a instance given the source path of the tileset. If you just want to load tilesets from the file system, you can use something like this: + +```csharp +Tileset ResolveTileset(string source) +{ + +} +``` + +- `Func` - Template resolver, which resolves a template by its source path +- `Func` - Custom type resolver, which resolves a custom type by its name + +The first two resolver functions are used to resolve external tilesets and object templates. The third resolver function is used to resolve custom types that are defined in Tiled maps. Please refer to the [custom properties](custom-properties.md) documentation for more information on custom types. + + +------------- + +### [OLD] + +To be completely agnostic about how you may store/retrieve your tilesets, DotTiled will invoke a supplied `Func` where you can resolve the tileset by its source path. This is useful for scenarios where you may want to load tilesets in custom ways, such as from a database or a custom file format. + +```csharp +Tileset ResolveTileset(string source) +{ + var xmlStringReader = CustomContentManager.ReadString(source); + var xmlReader = XmlReader.Create(xmlStringReader); + var tilesetReader = new TmxTilesetReader(xmlReader, ResolveTileset, ResolveTemplate, ResolveCustomType); +} \ No newline at end of file diff --git a/docs/docs/loading-a-map.md b/docs/docs/loading-a-map.md deleted file mode 100644 index 9a7dc64..0000000 --- a/docs/docs/loading-a-map.md +++ /dev/null @@ -1 +0,0 @@ -# Loading a map \ No newline at end of file diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml index 62d2c9d..6a04547 100644 --- a/docs/docs/toc.yml +++ b/docs/docs/toc.yml @@ -3,5 +3,5 @@ - href: quickstart.md - name: Essentials -- href: loading-a-map.md -- href: custom-properties.md \ No newline at end of file +- href: essentials/loading-maps.md +- href: essentials/custom-properties.md \ No newline at end of file