Introduction

bevy_ecs_tiled is a Bevy plugin for working with 2D tilemaps created with the Tiled map editor.

It relies upon the official Tiled Rust bindings to parse and load Tiled map files and the bevy_ecs_tilemap crate to perform rendering.

It aims to provide a simple and ergonomic workflow by using Tiled as an editor when working on Bevy 2D games.

Features

  • Support for several kind of maps: orthogonal, isometric or hexagonal maps, finite or infinite layers, with external or embedded tilesets, using atlases or several images.
  • Support various Tiled features: animated tiles, images layers, tile objects or Tiled world when a single map is not enough.
  • Each Tiled item, such as layer, tile or object, is represented by a Bevy entity and everything is organized under a Bevy hierarchy: layers are children of the Tiled map entity, tiles and objects are children of these layers. Visibility and Transform are automatically propagated down the hierarchy.
  • Easily control how to spawn and despawn maps. Use Bevy events and observers to customize how your scene is spawned or notify you when the map is actually loaded and ready to use.
  • Build your map in Tiled and let the plugin take care of the rest:
    • Automatically spawn Rapier or Avian physics colliders on tiles or objects.
    • Use Tiled custom properties to automatically insert your own components on objects, tiles or layers.
  • Hot-reloading: work on your map in Tiled and see it update in Bevy without having to re-compile / restart your game.

Disclaimer: both this book and the whole crate have been heavilly inspired by the bevy_ecs_ldtk crate, which is basically the equivalent of bevy_ecs_tiled but for the LDTK map editor. Thanks for the inspiration! :)

Purpose of this book

This book aims to give you a better understanding of how bevy_ecs_tiled works, what you can achieve with it and how you can do it.

It will focus on high-level concepts, design concerns and basic tutorials. If you need an API reference, please have a look at the bevy_ecs_tiled API reference. The examples directory is also a good place to start.

Finally, this book assume you already have some sort of knowledge about Bevy and Tiled map editor. There are already some good documentations available on these topics and some resources are referenced in the dedicated section.

Architecture of this book

This book is divided in several categories:

  • Design and explanation: how does the plugin work and why some technical choices have been made;
  • How-To's: in-depth tutorials about a specific aspect of the plugin;
  • Migration guides: migration guides for specific versions;
  • Miscellaneous: other topics that did not fit in other categories.

Good reading ! :)