bevy_ecs_tiled

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.

Showcases

Update your Bevy components directly from Tiled editor:

Use several maps to build a huge world:

Documentation

This crate is documented in three places:

• The bevy_ecs_tiled book with design explanations, how-to guides and migrations guides.
• The API reference
• The examples folders, for concrete use cases.

There is notably a FAQ that will hopefully answer most of your questions.

Getting started

Add the required dependencies to your Cargo.toml file:

[dependencies]
bevy = "0.16"
bevy_ecs_tiled = "0.9"

Basic Usage

To get started, add the plugin to your app and spawn a map entity. All you need to do is spawn a TiledMap component with the map asset you want to load (e.g., your map.tmx file). Make sure this map asset, along with any required dependencies (such as images or tilesets), is present in your local assets folder (by default, ./assets/).

use bevy::prelude::*;
use bevy_ecs_tiled::prelude::*;

fn main() {
    App::new()
        // Add Bevy's default plugins
        .add_plugins(DefaultPlugins)
        // Add the bevy_ecs_tiled plugin.
        // bevy_ecs_tilemap::TilemapPlugin will be added automatically if needed
        .add_plugins(TiledPlugin::default())
        // Add your startup system and run the app
        .add_systems(Startup, startup)
        .run();
}

fn startup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
) {
    // Spawn a 2D camera
    commands.spawn(Camera2d);

    // Load a map asset and retrieve its handle
    let map_handle: Handle<TiledMapAsset> = asset_server.load("map.tmx");

    // Spawn a new entity with the TiledMap component
    commands.spawn(TiledMap(map_handle));
}

This simple example will load a map using the default settings.

Customizing Map Loading

You can customize how the map is loaded by listening to specific TiledEvent or adding various components to the map entity, such as:

• TilemapAnchor — Controls the anchor point of the tilemap.
• TiledMapLayerZOffset — Adjusts the Z offset between map layers.
• TiledMapImageRepeatMargin — Control the margin for repeated images.
• TilemapRenderSettings — Configures rendering options.
• Transform — Sets the position, rotation, and scale of the map.
• Visibility — Controls the visibility of the map entity.

use bevy::prelude::*;
use bevy_ecs_tiled::prelude::*;

fn spawn_map(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
) {
    commands
        // Load a map and set its anchor point to the
        // center instead of the default bottom-left
        .spawn((
            TiledMap(asset_server.load("map.tmx")),
            TilemapAnchor::Center,
        ))
        // Add an "in-line" observer to detect when
        // the map has finished loading
        .observe(
            |trigger: Trigger<TiledEvent<MapCreated>>,
             assets: Res<Assets<TiledMapAsset>>,
             query: Query<(&Name, &TiledMapStorage), With<TiledMap>>| {
                // We can access the map components via a regular query
                let Ok((name, storage)) = query.get(trigger.event().origin) else {
                    return;
                };
                info!("=> Observer TiledMapCreated was triggered for map '{name}'");

                // Or directly the underneath raw tiled::Map data
                let Some(map) = trigger.event().get_map(&assets) else {
                    return;
                };
                info!("Loaded map: {:?}", map);

                // Additionally, we can access Tiled items using the TiledMapStorage
                // component: we can retrieve Tiled items entity and access
                // their own components with another query (not shown here).
                // This can be useful if you want for instance to create a resource
                // based upon tiles or objects data but make it available only when
                // the map is actually spawned.
                for (id, entity) in storage.objects() {
                    info!(
                        "(map) Object ID {:?} was spawned as entity {:?}",
                        id, entity
                    );
                }
            }
        );
}

More Examples

For more advanced use cases, such as loading worlds, chunking, custom properties, or integrating with physics, see the examples directory in the repository.

You can also refer to the API documentation for details on all available components and configuration options.

Bevy Compatibility

Assets credits

• colored tiles: orthogonal tileset from Steve Pryde, licensed under CC0 1.0
• drjamgo_hex_16x16: an hexagonal "pointy-top" tileset from Dr. Jango, licensed under CC0 1.0
• simple hex flat top: an hexagonal "flat-top" tileset from All things hex, licensed under CC0 1.0
• kenney-sketch-desert: an isometric tileset from Kenney, licensed under CC0 1.0
• bevy_logo: an alternative Bevy logo from Steam Ed Duck, licensed under CC BY 4.0

Contributing

If you can contribute, please do!

If you would like to contribute but don't know where to start, read this section in the book.

License

This work is licensed under the MIT license.

SPDX-License-Identifier: MIT