jussi/DotTiled
1
0
Fork 0
mirror of https://github.com/dcronqvist/DotTiled.git synced 2025-05-08 15:56:04 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Remove .Model namespace as it is unnecessary

Browse source
This commit is contained in:
Daniel Cronqvist 2024-08-30 20:11:33 +02:00
parent 8a1da18dfd
commit d85494e7a9
98 changed files with 111 additions and 170 deletions
Download patch file Download diff file Expand all files Collapse all files

74
docs/docs/essentials/custom-properties.md
View file

@ -4,40 +4,40 @@
## All classes that can contain properties
All classes that can contain custom properties implement the interface <xref:DotTiled.Model.IHasProperties> in some way. Below is an exhaustive list of all classes that can contain custom properties:
All classes that can contain custom properties implement the interface <xref:DotTiled.IHasProperties> in some way. Below is an exhaustive list of all classes that can contain custom properties:
- <xref:DotTiled.Model.BaseLayer>
- <xref:DotTiled.Model.TileLayer>
- <xref:DotTiled.Model.ObjectLayer>
- <xref:DotTiled.Model.ImageLayer>
- <xref:DotTiled.Model.Group>
- <xref:DotTiled.Model.ClassProperty> (allows for recursive property objects)
- <xref:DotTiled.Model.CustomClassDefinition> (used to define custom Tiled property types)
- <xref:DotTiled.Model.Object>
- <xref:DotTiled.Model.EllipseObject>
- <xref:DotTiled.Model.PointObject>
- <xref:DotTiled.Model.PolygonObject>
- <xref:DotTiled.Model.PolylineObject>
- <xref:DotTiled.Model.RectangleObject>
- <xref:DotTiled.Model.TextObject>
- <xref:DotTiled.Model.TileObject>
- <xref:DotTiled.Model.Tileset>
- <xref:DotTiled.Model.Tile>
- <xref:DotTiled.Model.WangTile>
- <xref:DotTiled.Model.WangColor>
- <xref:DotTiled.BaseLayer>
- <xref:DotTiled.TileLayer>
- <xref:DotTiled.ObjectLayer>
- <xref:DotTiled.ImageLayer>
- <xref:DotTiled.Group>
- <xref:DotTiled.ClassProperty> (allows for recursive property objects)
- <xref:DotTiled.CustomClassDefinition> (used to define custom Tiled property types)
- <xref:DotTiled.Object>
- <xref:DotTiled.EllipseObject>
- <xref:DotTiled.PointObject>
- <xref:DotTiled.PolygonObject>
- <xref:DotTiled.PolylineObject>
- <xref:DotTiled.RectangleObject>
- <xref:DotTiled.TextObject>
- <xref:DotTiled.TileObject>
- <xref:DotTiled.Tileset>
- <xref:DotTiled.Tile>
- <xref:DotTiled.WangTile>
- <xref:DotTiled.WangColor>
## How to access properties
To access the properties on one of the classes listed above, you will make use of the <xref:DotTiled.Model.IHasProperties> interface.
To access the properties on one of the classes listed above, you will make use of the <xref:DotTiled.IHasProperties> interface.
In situations where you know that a property must exist, and you simply want to retrieve it, you can use the <xref:DotTiled.Model.IHasProperties.GetProperty``1(System.String)> method like so:
In situations where you know that a property must exist, and you simply want to retrieve it, you can use the <xref:DotTiled.IHasProperties.GetProperty``1(System.String)> method like so:
```csharp
var map = LoadMap();
var propertyValue = map.GetProperty<BoolProperty>("boolPropertyInMap").Value;
```
If you are unsure whether a property exists, or you want to provide some kind of default behaviour if the property is not present, you can instead use the <xref:DotTiled.Model.IHasProperties.TryGetProperty``1(System.String,``0@)> method like so:
If you are unsure whether a property exists, or you want to provide some kind of default behaviour if the property is not present, you can instead use the <xref:DotTiled.IHasProperties.TryGetProperty``1(System.String,``0@)> method like so:
```csharp
var map = LoadMap();
@ -56,17 +56,17 @@ For both methods, you can replace `BoolProperty` with any of the property types
## All types of properties
Tiled supports a variety of property types, which are represented in the DotTiled library as classes that implement the <xref:DotTiled.Model.IProperty`1> interface. Below is a list of all property types that Tiled supports and their corresponding classes in DotTiled:
Tiled supports a variety of property types, which are represented in the DotTiled library as classes that implement the <xref:DotTiled.IProperty`1> interface. Below is a list of all property types that Tiled supports and their corresponding classes in DotTiled:
- `bool` - <xref:DotTiled.Model.BoolProperty>
- `color` - <xref:DotTiled.Model.ColorProperty>
- `float` - <xref:DotTiled.Model.FloatProperty>
- `file` - <xref:DotTiled.Model.FileProperty>
- `int` - <xref:DotTiled.Model.IntProperty>
- `object` - <xref:DotTiled.Model.ObjectProperty>
- `string` - <xref:DotTiled.Model.StringProperty>
- `bool` - <xref:DotTiled.BoolProperty>
- `color` - <xref:DotTiled.ColorProperty>
- `float` - <xref:DotTiled.FloatProperty>
- `file` - <xref:DotTiled.FileProperty>
- `int` - <xref:DotTiled.IntProperty>
- `object` - <xref:DotTiled.ObjectProperty>
- `string` - <xref:DotTiled.StringProperty>
In addition to these primitive property types, [Tiled also supports more complex property types](https://doc.mapeditor.org/en/stable/manual/custom-properties/#custom-types). These custom property types are defined in Tiled according to the linked documentation, and to work with them in DotTiled, you *must* define their equivalences as a <xref:DotTiled.Model.ICustomTypeDefinition>. You must then provide a resolving function to a defined type given a custom type name, as it is defined in Tiled.
In addition to these primitive property types, [Tiled also supports more complex property types](https://doc.mapeditor.org/en/stable/manual/custom-properties/#custom-types). These custom property types are defined in Tiled according to the linked documentation, and to work with them in DotTiled, you *must* define their equivalences as a <xref:DotTiled.ICustomTypeDefinition>. You must then provide a resolving function to a defined type given a custom type name, as it is defined in Tiled.
## Custom types
@ -74,7 +74,7 @@ Tiled allows you to define custom property types that can be used in your maps.
### Class properties
Whenever DotTiled encounters a property that is of type `class` in a Tiled file, it will use the supplied custom type resolver function to retrieve the custom type definition. It will then use that definition to know the default values of the properties of that class, and then override those defaults with the values found in the Tiled file when populating a <xref:DotTiled.Model.ClassProperty> instance. `class` properties allow you to create hierarchical structures of properties.
Whenever DotTiled encounters a property that is of type `class` in a Tiled file, it will use the supplied custom type resolver function to retrieve the custom type definition. It will then use that definition to know the default values of the properties of that class, and then override those defaults with the values found in the Tiled file when populating a <xref:DotTiled.ClassProperty> instance. `class` properties allow you to create hierarchical structures of properties.
For example, if you have a `class` property in Tiled that looks like this:
@ -98,7 +98,7 @@ var monsterSpawnerDefinition = new CustomClassDefinition
### Enum properties
Tiled also allows you to define custom property types that work as enums. Similarly to `class` properties, you must define the equivalent in DotTiled as a <xref:DotTiled.Model.CustomEnumDefinition>. You can then return the corresponding definition in the resolving function.
Tiled also allows you to define custom property types that work as enums. Similarly to `class` properties, you must define the equivalent in DotTiled as a <xref:DotTiled.CustomEnumDefinition>. You can then return the corresponding definition in the resolving function.
For example, if you have a custom property type in Tiled that looks like this:
@ -125,9 +125,9 @@ var entityTypeDefinition = new CustomEnumDefinition
In the future, DotTiled will support automatically mapping custom property `class` types to C# classes. This will allow you to define a C# class that matches the structure of the `class` property in Tiled, and DotTiled will automatically map the properties of the `class` property to the properties of the C# class. This will make working with `class` properties much easier and more intuitive.
The idea is to expand on the <xref:DotTiled.Model.IHasProperties> interface with a method like `GetMappedProperty<T>(string propertyName)`, where `T` is a class that matches the structure of the `class` property in Tiled.
The idea is to expand on the <xref:DotTiled.IHasProperties> interface with a method like `GetMappedProperty<T>(string propertyName)`, where `T` is a class that matches the structure of the `class` property in Tiled.
This functionality would be accompanied by a way to automatically create a matching <xref:DotTiled.Model.ICustomTypeDefinition> given a C# class or enum. Something like this would then be possible:
This functionality would be accompanied by a way to automatically create a matching <xref:DotTiled.ICustomTypeDefinition> given a C# class or enum. Something like this would then be possible:
```csharp
class MonsterSpawner
@ -156,6 +156,6 @@ var monsterSpawner = map.GetMappedProperty<MonsterSpawner>("monsterSpawnerProper
var entityType = map.GetMappedProperty<EntityType>("entityTypePropertyInMap");
```
Finally, it might be possible to also make some kind of exporting functionality for <xref:DotTiled.Model.ICustomTypeDefinition>. Given a collection of custom type definitions, DotTiled could generate a corresponding `propertytypes.json` file that you then can import into Tiled. This would make it so that you only have to define your custom property types once (in C#) and then import them into Tiled to use them in your maps.
Finally, it might be possible to also make some kind of exporting functionality for <xref:DotTiled.ICustomTypeDefinition>. Given a collection of custom type definitions, DotTiled could generate a corresponding `propertytypes.json` file that you then can import into Tiled. This would make it so that you only have to define your custom property types once (in C#) and then import them into Tiled to use them in your maps.
Depending on implementation this might become something that can inhibit native AOT compilation due to potential reflection usage. Source generators could be used to mitigate this, but it is not yet clear how this will be implemented.

10
docs/docs/essentials/loading-maps.md
View file

@ -1,9 +1,9 @@
# Loading maps
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.
Loading maps with DotTiled is straightforward and easy. The <xref:DotTiled.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.
> [!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.
> Using the `.tmj` file format will result in <xref:DotTiled.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
@ -13,7 +13,7 @@ Loading a map, tileset, or template will require you to specify **three** resolv
### `Func<string, Tileset>` - Tileset resolver
This function is used to resolve external tilesets by their source path. The function should return a <xref:DotTiled.Model.Tileset> 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:
This function is used to resolve external tilesets by their source path. The function should return a <xref:DotTiled.Tileset> 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)
@ -38,11 +38,11 @@ Tileset ResolveTileset(string source)
### `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>.
This function is used to resolve external object templates by their source path. The function should return a <xref:DotTiled.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.
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.ICustomTypeDefinition> instance given the custom type's name.
## Putting it all together