bevy_ecs_tiled

Version 0.12 introduced support for Tiled text objects and hierarchical group layers:

• Text Objects: Tiled text objects are spawned with TiledObjectText and TiledObjectTextBox components.
• Group Layers: Hierarchical organization is supported. When working with layers or objects, use the get_layer_from_map() and get_object_from_map() helper functions, as they are designed to traverse group layers automatically.

In bevy_ecs_tiled, the rendering order of layers is determined by an incremental Z offset applied to the layer hierarchy. This ensures that layers higher in the Tiled stack appear in front of lower layers in Bevy.

The Z transform is calculated as follows:

• Topmost layer (Tiled): Z transform = 0
• Next layer down: Z transform = -1 × OFFSET
• Subsequent layers: Z transform = -n × OFFSET

By default, the OFFSET is 100. Using a sufficiently large offset is important to avoid rendering conflicts with bevy_ecs_tilemap chunks, which also apply small Z offsets.

Objects placed on a Tiled layer inherit the Z offset of their parent layer. To prevent "Z-fighting" (flickering caused by identical Z values), bevy_ecs_tiled automatically applies a small, unique additional Z offset to each individual object within that layer.

If you require precise Z-positioning for specific objects (e.g., for custom sorting or gameplay-driven depth), you should:

1. Listen to map events to detect when objects are spawned.
2. Manually adjust the Z transform of the object after spawning.
3. Implement custom logic to set Z values based on object properties.

The plugin uses an Entity-Based Architecture to represent Tiled data within Bevy.

• Hierarchy: Every Tiled item is a Bevy entity. Layers are children of the Map entity, while tiles and objects are children of their respective layers.
• Automatic Propagation: Visibility and Transform properties are automatically propagated through this hierarchy.
• Data-Driven Components: You can use Tiled custom properties to automatically insert custom Bevy components onto objects, tiles, or layers, allowing you to drive game logic directly from the Tiled editor.
• Physics Integration: The plugin can automatically spawn colliders for tiles and objects using Rapier or Avian physics engines.

All bevy_ecs_tiled events are wrapped in a TiledEvent<E> structure. This wrapper provides essential context about the event's origin and includes helper methods to access related Tiled data. For instance, an event for a specific object will also provide access to the layer and map containing that object, allowing you to traverse the hierarchy easily.

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

fn handle_event(
    mut object_events: MessageReader<TiledEvent<ObjectCreated>>,
) {
    // Even though we receive an event for a Tiled object,
    // we can retrieve information about the Tiled map
    for e in object_events.read() {
        let object_entity = e.origin;
        if let Some(map_asset) = e.get_map_asset() {
            info!("Received TiledEvent<ObjectCreated> for: '{:?}'", map_asset);
        }
    }
}

The bevy_ecs_tiled ecosystem allows for automatic physics collider spawning based on map data. In the platformer example, this is used for:

• Static Colliders: Spawning colliders for platform tiles and static objects.
• Dynamic Colliders: Spawning colliders for moving entities like enemies and the player character.

When using physics engines like Avian, you can leverage these colliders to trigger game logic events (such as teleportation or dead zones) when a player enters a specific zone defined in the map.

When deciding whether to use bevy_ecs_tiled (which uses Tiled maps) or an alternative like bevy_ecs_ldtk, consider your map requirements:

Use Tiled (bevy_ecs_tiled) if you need:

• Isometric or Hexagonal maps: Tiled has native support for isometric layouts and hexagonal grids (including both "pointy-top" and "flat-top" orientations).
• Animated tiles: Tiled includes built-in support for tile animations.
• Advanced features: Like auto-tiling, custom properties for gameplay data, and multi-map world layouts.

Use LDTK (bevy_ecs_ldtk) if you need:

• Orthogonal maps only: If your project is strictly grid-based/orthogonal and you prefer a more modern editor interface, LDTK is a strong alternative.

You can define game logic directly in the Tiled editor by attaching custom properties to objects. bevy_ecs_tiled automatically instantiates Bevy components on map load based on these properties.

Workflow:

1. Add marker components to objects in the Tiled editor (e.g., PlayerSpawnPoint, Enemy, PatrolRoute, or Trigger).
2. The plugin automatically instantiates these components on the corresponding Bevy entities when the map is loaded.
3. Implement game logic by using Bevy On<Add> observers or standard Query systems to react to these components.

When using custom properties, keep these constraints in mind:

• Tiles: To add properties to tiles, you must edit the tileset directly. You cannot add properties to the tileset itself.
• Layers/Objects/Maps: Properties can be added to these elements normally.
• Resources: You can define types that load as Bevy Resources, but they must be added as properties to the Map level. If you add a resource-type property to a layer or object, it will be ignored because resources are global and not attached to specific entities.