More docs

docs/docs/essentials/loading-maps.md

@@ -2,14 +2,14 @@
 
 Loading maps with DotTiled is straightforward and easy. The <xref:DotTiled.Model.Map> 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 <xref:DotTiled.Model.ImageLayer.Image> 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.
+> [!NOTE]
+> Using the `.tmj` file format will result in <xref:DotTiled.Model.ImageLayer.Image> not having the same amount of information as for the `.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.
+Tiled maps may consist of several external files, such as tilesets or object templates. In Tiled map files, they 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 (which is how some other similar libraries work), 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
+Loading a map, tileset, or template will require you to specify **three** resolver functions. We'll go through each of them below.
 
 ### `Func<string, Tileset>` - Tileset resolver
 
@@ -18,26 +18,69 @@ This function is used to resolve external tilesets by their source path. The fun
 ```csharp
 Tileset ResolveTileset(string source)
 {
-    
+  using var tilesetFileReader = new StreamReader(source);
+  var tilesetString = tilesetReader.ReadToEnd();
+  using var tilesetReader = new TilesetReader(tilesetString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return tilesetReader.ReadTileset();
 }
 ```
 
-- `Func<string, Template>` - Template resolver, which resolves a template by its source path
-- `Func<string, CustomType>` - 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<string, Tileset>` 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.
+But, DotTiled is designed this way so you can retrieve your external resources from anywhere, such as a database or a custom file format, by implementing your own resolver function however you like. If you have some other means of accessing resources, you can use that instead of the file system.
 
 ```csharp
 Tileset ResolveTileset(string source)
 {
-  var xmlStringReader = CustomContentManager.ReadString(source);
-  var xmlReader = XmlReader.Create(xmlStringReader);
-  var tilesetReader = new TmxTilesetReader(xmlReader, ResolveTileset, ResolveTemplate, ResolveCustomType);
-}
+  var tilesetString = ContentManager.GetString($"tilesets/{source}");
+  using var tilesetReader = new TilesetReader(tilesetString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return tilesetReader.ReadTileset();
+}
+```
+
+### `Func<string, Template>` - Template resolver
+
+This function is used to resolve external object templates by their source path. The function should return a <xref:DotTiled.Model.Template> instance given the source path of the template. If you just want to load templates from the file system, you can use something very similar to the tileset resolver by replacing <xref:DotTiled.Serialization.TilesetReader> with <xref:DotTiled.Serialization.TemplateReader>.
+
+### `Func<string, CustomType>` - Custom type resolver
+
+This 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. The function should return a <xref:DotTiled.Model.ICustomTypeDefinition> instance given the custom type's name.
+
+## Putting it all together
+
+The following classes are the readers that you will need to use to read the map, tileset, and template: <xref:DotTiled.Serialization.MapReader>, <xref:DotTiled.Serialization.TilesetReader>, and <xref:DotTiled.Serialization.TemplateReader>.
+
+Here is an example of how you can load a map with DotTiled:
+
+```csharp
+string mapPath = "path/to/map.tmx";
+string mapDirectory = Path.GetDirectoryName(mapPath);
+
+Tileset ResolveTileset(string source)
+{
+  string tilesetPath = Path.Combine(mapDirectory, source);
+  using var tilesetFileReader = new StreamReader(tilesetPath);
+  var tilesetString = tilesetReader.ReadToEnd();
+  using var tilesetReader = new TilesetReader(tilesetString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return tilesetReader.ReadTileset();
+}
+
+Template ResolveTemplate(string source)
+{
+  string templatePath = Path.Combine(mapDirectory, source);
+  using var templateFileReader = new StreamReader(templatePath);
+  var templateString = templateReader.ReadToEnd();
+  using var templateReader = new TemplateReader(templateString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return templateReader.ReadTemplate();
+}
+
+ICustomTypeDefinition ResolveCustomType(string name)
+{
+  var allDefinedTypes = [ ... ];
+  return allDefinedTypes.FirstOrDefault(type => type.Name == name);
+}
+
+using var mapFileReader = new StreamReader(mapPath);
+var mapString = mapFileReader.ReadToEnd();
+using var mapReader = new MapReader(mapString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+
+var map = mapReader.ReadMap();
+```

docs/docs/quickstart.md

@@ -1 +1,46 @@
-# Quick Start
+# Quick Start
+
+Install DotTiled from NuGet:
+
+```bash
+dotnet add package DotTiled
+```
+
+Load a map from file system:
+
+```csharp
+string mapPath = "path/to/map.tmx";
+string mapDirectory = Path.GetDirectoryName(mapPath);
+
+Tileset ResolveTileset(string source)
+{
+  string tilesetPath = Path.Combine(mapDirectory, source);
+  using var tilesetFileReader = new StreamReader(tilesetPath);
+  var tilesetString = tilesetReader.ReadToEnd();
+  using var tilesetReader = new TilesetReader(tilesetString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return tilesetReader.ReadTileset();
+}
+
+Template ResolveTemplate(string source)
+{
+  string templatePath = Path.Combine(mapDirectory, source);
+  using var templateFileReader = new StreamReader(templatePath);
+  var templateString = templateReader.ReadToEnd();
+  using var templateReader = new TemplateReader(templateString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+  return templateReader.ReadTemplate();
+}
+
+ICustomTypeDefinition ResolveCustomType(string name)
+{
+  var allDefinedTypes = [ ... ];
+  return allDefinedTypes.FirstOrDefault(type => type.Name == name);
+}
+
+using var mapFileReader = new StreamReader(mapPath);
+var mapString = mapFileReader.ReadToEnd();
+using var mapReader = new MapReader(mapString, ResolveTileset, ResolveTemplate, ResolveCustomType);
+
+var map = mapReader.ReadMap();
+```
+
+If the above looks intimidating, don't worry! DotTiled is designed to be flexible and allow you to load maps from any source, such as a database or a custom file format. The above example is just one way to load a map from a file system. Please look at [Loading Maps](essentials/loading-maps.md) for more information on how to load maps from different sources.