README.md

bevy_ecs_tiled

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 load Tiled map files
• the bevy_ecs_tilemap crate to perform rendering

Each tile or object is represented by a Bevy entity:

• layers are children of the tilemap entity
• tiles and objects are children of layers

Visibility and Transform are inherited: map -> layer -> tile / object

Features

• Orthogonal, isometric and hexagonal maps
• Finite and infinite maps
• Embedded and separate tileset
• Easily spawn / despawn maps
• Animated tiles
• Rapier and Avian colliders added from tilesets and object layers (rapier or avian feature flag)
• Tiled custom properties mapped to Bevy components (user_properties feature flag)

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.

Good reading!

Getting started

Add dependencies to your Cargo.toml file:

[dependencies]
bevy = "0.15"
bevy_ecs_tiled = "0.5"
bevy_ecs_tilemap = "0.15"

Then add the plugin to your app and spawn a map:

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

fn main() {
    App::new()
        // Add Bevy default plugins
        .add_plugins(DefaultPlugins)
        // Add bevy_ecs_tilemap plugin
        .add_plugins(TilemapPlugin)
        // Add bevy_ecs_tiled plugin
        .add_plugins(TiledMapPlugin::default())
        // Add our startup function to the schedule 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 the map: ensure any tile / tileset paths are relative to assets/ folder
    let map_handle: Handle<TiledMap> = asset_server.load("map.tmx");

    // Spawn the map with default options
    commands.spawn(TiledMapHandle(map_handle));
}

Basically, all you have to do is to spawn a TiledMapHandle with the map asset you want to load (the map.tmx file). Note that this map asset should be in your local assets/ folder, as well as required dependencies (for instance, associated tilesets).

You can tweak how to load the map by adding various components on the map entity, notably:

• TiledMapSettings
• TilemapRenderSettings
• Transform
• Visibility

You can browse the examples for more advanced use cases.

Bevy Compatibility

bevy	bevy_ecs_tilemap	bevy_ecs_tiled
0.15	0.15	0.5
0.14	0.14	0.3 - 0.4
0.13	main@e4f3cc6	branch 0.2
0.12	0.12	0.1

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

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