Migration to bevy_ecs_tiled v0.8

This guide outlines the steps required to migrate your project to version 0.8 of bevy_ecs_tiled.

Main Changes

• Improved TiledEvent API: Provides an unified way to handle events and access underlying Tiled data.
• Attach shape information to TiledObject: Direct access to Tiled objects shape information through ECS.
• Reworked physics colliders spawning: Integrate with the geo crate to define and aggregate colliders together.
• Reworked name filter API: The filter API have been extended to use regex and is now also used for selecting which types are exported as Tiled custom properties.
• Simplify TiledMapStorage usage: Add helpers functions to the TiledMapStorage component so it's easier to work with.
• Explicit SystemSet: Allow precise systems ordering for user applications.
• Rationalize naming: Several types or functions have been renamed to better reflect what they actually do.
• Source code re-organization: Several files have been moved around or renamed.

Migration Steps

1. Update the dependency in Cargo.toml:

   bevy_ecs_tiled = "0.8"
   

2. Adjust your types:

   Some types have been renamed, without any functional change, or not much.

   It should be safe to simply run a "search and replace" command, in the following order (make sure to match whole words):

   Old name	New name	Functional changes ?
   TiledMap	TiledMapAsset
   TiledWorld	TiledWorldAsset
   TiledMapHandle	TiledMap
   TiledWorldHandle	TiledWorld
   TiledMapPlugin	TiledPlugin
   TiledColliderSpawnInfos		This one was actually removed
   TiledMapMarker	TiledMap	This one was actually removed
   TiledWorldMarker	TiledWorld	This one was actually removed
   TiledMapLayer	TiledLayer	TiledLayer now holds the layer kind
   TiledMapTileLayer	TiledLayer	TiledLayer now holds the layer kind
   TiledMapObjectLayer	TiledLayer	TiledLayer now holds the layer kind
   TiledMapGroupLayer	TiledLayer	TiledLayer now holds the layer kind
   TiledMapImageLayer	TiledLayer	TiledLayer now holds the layer kind
   TiledMapTileLayerForTileset	TiledTilemap
   TiledMapTile	TiledTile
   TiledMapObject	TiledObject
   TiledMapImage	TiledImage

3. Adjust your functions:

   Some functions have been renamed, without changing their behaviour, or not much.

   It should be safe to simply run a "search and replace" command:

   Old name	New name
   get_map_type	tilemap_type_from_map
   get_grid_size	grid_size_from_map
   get_tile_size	tile_size_from_map
   tile_size_from_grid	tile_size_from_grid_size

   The following functions are now methods of the TiledMapAsset struct:

   • for_each_tile
   • world_space_from_tiled_position (renamed from from_tiled_position_to_world_space)

4. Adjust your imports:

   Some modules or types have changed names or locations. If you import types using their defining path you may need to adjust.

   An easy way to get past this is to import the whole prelude: bevy_ecs_tiled::prelude::* or to use the type prelude path, such as bevy_ecs_tiled::prelude::TiledPlugin.

5. Adjust Event API usage

   The event API has been reworked and now revolves around a generic TiledEvent<E> structure. This provides more context for each event, including the origin of each particular event E and helper methods to access Tiled data.

   See the dedicated guide on events for details.

6. Update custom physics backend

   Most of the work that was done in the physics backend is now done by the crate itself which should simplify any custom physics backend implementation. As a result, the spawn_colliders function from the TiledPhysicsBackend trait have changed: you should refer to its documentation for more information.

7. Update filter API usage

   The filter API used to revolve around two enums: TiledName for creating filters and TiledNameFilter for matching them. It felt a bit cumbersome.
   Now, everything is done via the new TiledFilter enum for doing both operations and we added support for regular expresions using the regex crate.

   We also added a new parameter to TiledPluginConfig to control which properties are exported from Bevy at startup.

8. Adjust TiledMapStorage component usage

   Fields in TiledMapStorage are now private. You should use the provided methods instead of accessing fields directly.

Resources

• Main documentation
• API Reference
• Examples
• Full CHANGELOG