Expand description
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.VisibilityandTransformare 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.
§Documentation
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 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.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.