Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Migration to bevy_ecs_tiled v0.9

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

Main Changes

  • Improved Isometric Map Support:
    Isometric maps are now much better supported, including correct physics collider shapes and placement.
  • Accurate Physics Colliders for Isometric Maps:
    Physics colliders are now generated with the correct geometry and position for isometric maps.
  • Clear Distinction Between grid_size and tile_size:
    Previously, tile_size (the actual size of a tile) and grid_size (the space a tile occupies on the grid) were treated as equivalent. This is not always true, especially for isometric maps. The API now enforces a clear distinction.
  • API Renaming for Clarity:
    Several functions and methods have been renamed to improve clarity and expressiveness.

Migration steps

  1. Update the dependency in Cargo.toml:

    bevy_ecs_tiled = "0.9"

  2. Adjust function usage:

  • Removed:
    tile_size_from_grid_size() has been removed.
    Reason: Avoids confusion between tile_size and grid_size.

    tile_size_from_map() has been removed.
    Reason: You should use TiledMapAsset::largest_tile_size instead.

  • Added:
    A new tile_size() helper function is available to retrieve the tile_size from a Tile.

  • Changed:

    • TiledMapAsset::world_space_from_tiled_position() is now private to the crate.
      Reason: This is a low-level function and should not be used directly.
    • TiledMapAsset::object_world_position() → Renamed to TiledMapAsset::object_relative_position()
      Signature remains the same.
    • TiledMapAsset::tile_world_position() → Renamed to TiledMapAsset::tile_relative_position()
      Now takes an extra TilemapTileSize argument instead of relying on the map's TilemapGridSize.

  • Updated Geometry Methods:
    The following methods on TiledObject now take 4 additional arguments to properly handle isometric maps:

    • center()
    • vertices()
    • line_string()
    • polygon()

Resources