Make sure you are actually using a "diamond" map and not a "staggered" one (which are not supported).
+
Also, for isometric maps, you may want to tweak the TilemapRenderSettings Component from bevy_ecs_tilemap.
+More information in the isometric maps example
When a map is loaded, it spawns a lot of entities: for the map, for layers, for tiles, for objects, for colliders, ...
+These entites are organized in a parent / child hierarchy.
+
It notably brings the capability to inherit some of the component down the tree.
+For instance, if you change the Visibility of an entity, it will automatically apply to all entities below in the hierarchy.
At the top of the tree, there is the map.
+It notably holds the TiledMapHandle pointing to your .TMX file and all the settings that apply to it.
+It can be easily identified using a dedicated marker component: TiledMapMarker.
For tiles, it's a little more complicated.
+Below the TiledMapTileLayer, we first have one TiledMapTileLayerForTileset per tileset in the map.
+Finally, below these, we find the actual TiledMapTile which correspond to every tiles in the layer, for a given tileset.
At the end of the hierarchy, we find physics colliders.
+They are spawned below they "source", ie. either a tile or an object and can be identified using their marker component: TiledColliderMarker.
When designing your map under Tiled, you expect that a layer will hide another one which is below in the layer hierarchy.
+This is very useful when using isometric tiles for instance.
+
To reproduce this behaviour under Bevy, we add an arbitrary offset on the Z transform to each layers of the hierarchy.
+
If we call this offset OFFSET:
+
+
the top-level layer will have a Z transform of 0
+
the second one will have a Z transform of - OFFSET
+
the next one of - 2*OFFSET
+
etc...
+
+
By default this offset has a value of +100.
+It can be changed by tweaking the TiledMapSettings component.
+Since bevy_ecs_tilemap also play with the Z-transform to adjust how tiles from a given layers are rendered, you probably don't want to have a "too low" value.
To do so, in Tiled, navigate to View -> Custom Types Editor:
-
-
From this panel, you will be able to define your own custom type (think of it as a struct) and describe which fields it has.
-For more information see the official documentation.
-
-
For instance, in the example above, we created a TileBundle custom type which has a single BiomeInfos field.
-This BiomeInfos field is another custom type which has two fields: a boolean BlockLineOfSight and an enum Type.
-
We support all types except :
-
-
the "enum as int" type: you should use instead the "enum as string"
-
the "object" type: you cannot (yet) reference another object
Please note that we do not support adding directly custom properties and you must use a custom type.
-
First, you need to update the "class" property and set the custom type you want.
-
-
For objects you can just select the object you want from the map. Only the selected object will have custom properties.
-
For tiles, you need to edit the tileset then select the tile you want. All tiles of this kind will get custom properties.
-
-
-
Once the class is set, it will automatically add the custom type fields (with their default value) corresponding to this custom type to the "custom properties" tab.
-You can then edit the properties you want, as it fits your game.
-
For instance, in the picture above, we declared our tile to be a TileBundle:
-
-
we left BiomeInfos.BlockLineOfSight to its default value (which happens to be false)
To actually retrieve these custom properties in your game, you need to do three things:
-
-
Enable the user_properties feature
-
Define your custom type
-
Register your custom type
-
-
First, to enable the user_properties feature, you need to update your Cargo.toml file:
-
[dependencies]
-bevy_ecs_tiled = { version = "XXX", features = [ "user_properties" ] }
-
-
Then, you can define your custom type:
-
-#![allow(unused)]
-fn main() {
-// If declaring a custom type for an objet,
-// you should use instead the TiledObject derive
-#[derive(TiledCustomTile, Bundle, Default, Debug, Reflect)]
-struct TileBundle {
- #[tiled_rename = "BiomeInfos"]
- infos: BiomeInfos,
-}
-}
-
Your Tiled map, layer, tile or object will be represented by a Bevy Entity.
+So, it makes sense that if you want to add custom properties to them, these properties should either be a Component or a Bundle.
+
Also, Tiled custom properties use Bevy Reflect mechanism.
+So, in order to be usable in Tiled, your custom types must be "Reflectable".
+To do, these types must derive the Reflect trait and get registered with Bevy.
+
use bevy::prelude::*;
+
+// Declare a component that is "reflectable"
+#[derive(Component, Reflect, Default)]
+#[reflect(Component, Default)]
+struct SpawnInfos {
+ has_spawned: bool,
+ ty: SpawnType,
}
-#[derive(TiledEnum, Default, Reflect, Debug)]
-enum BiomeType {
+// Any 'sub-type' which is part of our component must also be "reflectable"
+#[derive(Default, Reflect)]
+#[reflect(Default)]
+enum SpawnType {
#[default]
Unknown,
- Plain,
- Desert,
- Forest,
- Mountain,
+ Player,
+ Enemy,
}
-}
-
-
Note that these custom types definitions should match what you have declared in Tiled custom types editor.
-
Finally, you can register your custom type before starting the app:
-
fn main() {
+
+// Register our type with Bevy
+fn main() {
App::new()
- // If registering an object, use register_tiled_object() instead
- .register_tiled_custom_tile::<TileBundle>("TileBundle")
- .run();
+ .register_type::<SpawnInfos>();
}
-
When loading a map which has tiles with the TileBundle custom type, corresponding components will be automatically inserted on the tile entity and have their value based upon the properties you set in Tiled.
-
-
Note that you only see the BiomeInfos type and not TileBundle.
-That's because TileBundle is a Bundle, which is actually a collection of Components.
This may change in the future, but bevy_ecs_tiled currently allows you to either use a Bevy Component or a Bevy Bundle to represent your tiles and objects.
-
It means that your custom type can either be:
-
-
a set of "standard type" fields (ie. no nested custom type), in that case it should be a Component.
-
a set of "custom type" fiels, in that case it should be a Bundle and additional CustomClass structs should be declared.
-
-
Note that it's an "all or nothing" mode.
-If you have a nested custom type, your struct must be a Bundle and it cannot contains an additional "standard type".
Note that in the above example, our custom type also derive the Default trait.
+It is particulary useful to do so: if you don't, you would have to fill all the fields of your custom type when you use it in Tiled.
+
Finally, note that you can also add Resource to your map.
+They won't be attached to a particular entity and as such are only allowed on Tiled maps.
Before you can add custom properties to your map, you will need to export them from Bevy then import them in Tiled.
+
When running with the user_properties feature, your app will automatically produce an export of all types registered with Bevy.
+By default, this file will be produced in your workspace with the name tiled_types_export.json.
+You can change this file name or even disable its production by tweaking the TiledMapPlugin configuration (see TiledMapPluginConfig).
+
You can then import this file to Tiled.
+To do so, in Tiled, navigate to View -> Custom Types Editor:
+
+
Click on the Import button and load your file:
+
+
Once it is done, you will be able to see all the custom types that you have imported from your application.
+Note that it concerns all the types that derive the Reflect trait: there can be quite a lot !
+
+
You can now add them to different elements of your map, like tiles objects, layers or the map itself.
+For more information on how to do add custom properties, see the official TIled documentation.
+You should only add properties imported from Bevy: adding ones that you created only in Tiled will not be loaded.
Version 0.4 was initially motivated by an update to the way we handle user properties but ended as a major overhaul of the plugin to provide a better API and to give more control to the user.
The plugin now has an associated configuration, which you need to provide when you add it to your application.
+
The easiest way is to use the default configuration value :
+
use bevy::prelude::*;
+use bevy_ecs_tiled::prelude::*;
+
+fn main() {
+ App::new()
+ // You still need the bevy_ecs_tilemap plugin
+ .add_plugins(TilemapPlugin)
+ // And now, you have to provide a configuration for bevy_ecs_tiled plugin
+ .add_plugins(TiledMapPlugin::default())
+ .run();
+}
+
+
The plugin configuration is described in the API reference
The plugin entry point, ie. the TiledMapBundle bundle is gone.
+It was cumbersome and did not allow for a proper separation of concerns (for instance, for physics).
+
Also, the Handle<TiledMap> type is not a Bevy component anymore.
+It was done in order to anticipate expected changes in Bevy where Handle<T> won't be able to derive the Component trait anymore.
+
Anyway, the new way to spawn a map is now easier: you just have to spawn a TiledMapHandle referencing your .TMX file asset:
+
+#![allow(unused)]
+fn main() {
+use bevy::prelude::*;
+use bevy_ecs_tiled::prelude::*;
+
+fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
+ // Load the map: ensure any tile / tileset paths are relative to assets/ folder
+ let map_handle: Handle<TiledMap> = asset_server.load("map.tmx");
+
+ // Spawn the map with default options
+ commands.spawn(TiledMapHandle(map_handle));
+}
+}
+
+
You can customize various settings about how to load the map by inserting the TiledMapSettings component on the map entity.
Before this change, you had to define your custom types both in Tiled and in your rust code.
+It was not user-friendly and error-prone.
+
Now, we take advantage of bevy_reflect to generate a file containing all the types known to Bevy.
+This file can be imported in Tiled so you can use these types directly in the editor.
+
Migrating from the old implementation should be straight-forward.
+
First, you need need to update your custom types so they actually implement the Reflect trait :
+
+
remove #[derive(TiledObject)], #[derive(TiledCustomTile)], #[derive(TiledClass)] and #[derive(TiledEnum)] derived traits. Make sure to also remove associated attributes.
+
add #[derive(Reflect)] derive trait on the types you want to use in Tiled.
+
make sure your components have the #[reflect(Component)] attribute
+
+
Then, in your main / in your plugin setup, you then need to register your types with Bevy :
+
+
replace calls to register_tiled_object::<T>() with calls to register_type::<T>().
+
replace calls to register_tiled_custom_tile::<T>() with calls to register_type::<T>().
+
+
The final step is to actually generate the types import file (run your game once) and import the types to Tiled.
+Note that you may have to update your map / your tilesets to use the new types you just imported.
