Getting started

Add the required dependencies to your Cargo.toml file:

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

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.
• TilemapRenderSettings — Configures rendering options.
• Transform — Sets the position, rotation, and scale of the map.
• Visibility — Controls the visibility of the map entity.

#![allow(unused)]
fn main() {
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.