Migration to `bevy_ecs_tiled` v0.12

This guide outlines the steps required to migrate your project to version 0.12 of bevy_ecs_tiled.

Main Changes

TiledAnimation API redesign for non-consecutive frame support
Physics colliders spawning rework with simplified geometry control
Support for Text Objects and Group Layer

Migration Steps

1. Update Dependencies

Update your Cargo.toml to use version 0.12 and compatible physics backends:

bevy = "0.18"
bevy_ecs_tiled = "0.12"
avian2d = "0.6"      # if using Avian physics
bevy_rapier2d = "0.34" # if using Rapier physics

2. Update `TiledAnimation` Usage

The animation API has been completely redesigned to support non-consecutive frame IDs and per-frame durations:

Before (v0.11):

#![allow(unused)]
fn main() {
pub struct TiledAnimation {
    pub start: usize,
    pub end: usize,
    pub frame_duration: f32,
}
}

After (v0.12):

#![allow(unused)]
fn main() {
pub struct TiledAnimation {
    pub frames: Vec<(usize, f32)>, // (atlas_index, duration_in_seconds)
    pub current_frame: usize,
}
}

Impact: Update any code that creates or manipulates TiledAnimation components to use the new frames vector format. Each tuple contains the atlas frame index and its duration in seconds.

Important: Tile-layer animations via bevy_ecs_tilemap::AnimatedTile still require consecutive IDs and uniform durations. Violations will now emit warnings instead of silently dropping frames.

3. Update Physics Colliders Spawning

Physics collider handling has been significantly reworked. This change should allow to better handle most physics use cases (for instance #169)

Key Changes:

One event per object: Only a single ColliderCreated event is sent per physics object, not per collider
Backend control: Physics backends now decide the ECS hierarchy structure (colliders may be directly attached to the physics object rather than as child entities)
Geometry simplification control: Two new options for controlling collider aggregation:
- Global setting: TiledPhysicsSettings::<T>::simplify_geometry
- Per-item override: TiledPhysicsDisableGeometrySimplification component

Update your physics event handlers:

#![allow(unused)]
fn main() {
// Old: Could receive multiple ColliderCreated events per object
fn on_collider_created(mut events: EventReader<ColliderCreated>) {
    for event in events.read() {
        // Handle each collider individually
    }
}

// New: Single event per object, check the collider structure in physics backend
fn on_collider_created(mut events: EventReader<ColliderCreated>) {
    for event in events.read() {
        // Event now provides direct reference to parent entity
        let parent = event.parent_entity;
    }
}
}

Disable geometry simplification per-object when needed:

#![allow(unused)]
fn main() {
// Prevent merging colliders for a specific object
commands.entity(object_entity)
    .insert(TiledPhysicsDisableGeometrySimplification);
}

4. Support for Text Objects and Group Layers (Optional)

Version 0.12 adds support for text objects and group layers:

Text objects: Tiled text objects are now spawned with TiledObjectText and TiledObjectTextBox components
Group layers: Hierarchical layer organization is now fully supported. Use get_layer_from_map() and get_object_from_map() helpers which now traverse group layers

No migration action required unless you're explicitly working with these features.

bevy_ecs_tiled Documentation