Introduction

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

It leverages the official Tiled Rust bindings for parsing and loading Tiled map files, and uses the bevy_ecs_tilemap crate for efficient rendering.

This plugin aims to provide a simple and ergonomic workflow for integrating Tiled into your Bevy 2D games, letting you focus on game design while handling the technical details of map loading, rendering, and entity management.

Features

• Comprehensive Map Support:
  Load orthogonal, isometric, or hexagonal maps, with finite or infinite layers, using either external or embedded tilesets, atlases, or multiple images.
• Rich Tiled Feature Integration:
  Supports animated tiles, image layers, tile objects, and Tiled worlds for multi-map projects.
• Entity-Based Architecture:
  Every Tiled item (layer, tile, object, etc.) is represented as a Bevy entity, organized in a clear hierarchy: layers are children of the map entity, tiles and objects are children of their respective layers. Visibility and Transform are automatically propagated.
• Flexible Map Lifecycle:
  Control how maps are spawned and despawned. Use Bevy events and observers to customize scene setup or react when a map is loaded and ready.
• Automatic Physics Integration:
  Automatically spawn Rapier or Avian physics colliders for tiles and objects, with support for custom backends.
• Custom Properties as Components:
  Use Tiled custom properties to automatically insert your own components on objects, tiles, or layers, enabling powerful data-driven workflows.
• Hot-Reloading:
  Edit your maps in Tiled and see updates reflected live in your Bevy game, without recompiling or restarting.

Disclaimer:
Both this book and the whole crate have been heavily inspired by the bevy_ecs_ldtk crate, which is essentially the equivalent of bevy_ecs_tiled but for the LDTK map editor.
A big thank you to the authors and contributors of bevy_ecs_ldtk for their inspiration and ideas!

Purpose of this Book

This book is designed to help you understand how bevy_ecs_tiled works, what you can achieve with it, and how to use it effectively in your projects.

You’ll find:

• High-level concepts and design explanations
• Step-by-step tutorials and practical guides
• Migration guides for upgrading between versions
• Miscellaneous tips and advanced topics

If you need detailed API documentation, please refer to the bevy_ecs_tiled API reference.
The examples directory is also a great place to see the plugin in action.

Note:
This book assumes you already have some familiarity with Bevy and the Tiled map editor.
If you’re new to these tools, check out their official documentation and the useful links section for recommended resources.

Book Structure

This book is organized into several sections:

• Design & Explanation:
  Learn how the plugin works internally and the reasoning behind key technical choices.
• How-To Guides:
  In-depth tutorials covering specific features and workflows.
• Migration Guides:
  Step-by-step instructions for upgrading between major versions.
• Miscellaneous:
  Additional topics and tips that don’t fit elsewhere.

Happy reading, and enjoy building your games with Bevy and Tiled!