Crate 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 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.

API reference

As the name implies, this API reference purpose is to describe the API provided by bevy_ecs_tiled.

For a more use-cases oriented documentation please have a look to the bevy_ecs_tiled book and notably the FAQ that will hopefully answer most of your questions.

Getting started

Add required dependencies to your Cargo.toml file:

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

Then add the plugin to your app and spawn a map. 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 (such as images or tilesets). By default, this is the ./assets/ folder.

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

fn main() {
    App::new()
        // Add Bevy default plugins
        .add_plugins(DefaultPlugins)
        // Add bevy_ecs_tiled plugin: note that bevy_ecs_tilemap::TilemapPlugin
        // will be automatically added as well if it's not already done
        .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 Bevy 2D camera
    commands.spawn(Camera2d);

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

    // Spawn a new entity with this handle
    commands.spawn(TiledMapHandle(map_handle));
}

This simplistic example will load a map using default settings. You can tweak how to load the map by adding various components on the map entity, notably:

• TiledMapAnchor
• TiledMapLayerZOffset
• TilemapRenderSettings
• Transform
• Visibility

For instance, here’s how you load a map but change its anchor point to be at center instead of bottom-left :

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

fn spawn_map(
  mut commands: Commands,
  asset_server: Res<AssetServer>
) {
    // You can also spawn your map and associated settings as a single bundle
    commands.spawn((
      TiledMapHandle(asset_server.load("map.tmx")),
      TiledMapAnchor::Center,
    ));
}

You can browse the examples for more advanced use cases.

Modules

cache

This module contains an implementation for tiled::ResourceCache

debug

This module contains some tools to help you debug your application.

map

This module handles all the logic related to loading and spawning Tiled maps

names

This module contains utilities to work with Tiled names.

physics

This module handles all things related to physics.

prelude

bevy_ecs_tiled public exports.

properties

This module handles all things related to Tiled custom properties.

reader

This module contains an implementation for tiled::ResourceReader

world

This module handles all the logic related to loading and spawning Tiled worlds.

Structs

TiledMapPlugin

bevy_ecs_tiled main Plugin.

TiledMapPluginConfig

TiledMapPlugin Plugin global configuration.