17 releases (4 breaking)
0.6.0 | Mar 15, 2025 |
---|---|
0.5.0 | Dec 22, 2024 |
0.4.1 | Nov 25, 2024 |
0.3.2 |
|
#40 in Game dev
306 downloads per month
Used in bevy_northstar
220KB
4.5K
SLoC
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
andTransform
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.
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.
Good reading!
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:
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.
Bevy Compatibility
bevy | bevy_ecs_tilemap | bevy_ecs_tiled |
---|---|---|
0.15 | 0.15 | 0.5 - 0.6 |
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
- Magic Market: an orthogonal tileset from GFragger
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
Dependencies
~47–82MB
~1.5M SLoC