bevy_ecs_ldtk

bevy_ecs_ldtk is an ECS-friendly plugin for the Bevy game engine that integrates LDtk projects. It allows you to use LDtk projects as assets, spawn levels, and map LDtk entities or tiles to Bevy components and bundles.

Key capabilities include:

• Support for all LDtk layer types.
• Loading external levels and implementing hot reloading.
• Strategies for loading/unloading levels and managing level neighbors.
• Low-boilerplate spawning of bundles for LDtk Entities and IntGrid tiles using derive macros.
• serde types for LDtk data with quality-of-life improvements.
• Wasm support (including tile spacing) via the atlas feature.

bevy_ecs_ldtk_macros provides procedural macros to simplify the implementation of LDtk-related data structures in Bevy. It allows you to automatically derive the necessary traits for entities and integer cells defined in your LDtk levels.

Supported derives:

• #[derive(LdtkEntity)]: Use this on structs representing entities defined in your LDtk file to enable automatic spawning and component management.
• #[derive(LdtkIntCell)]: Use this on structs representing integer cells (tiles) to facilitate their integration with the LDtk level data.

Because bevy_ecs_tilemap only allows one tile per position, bevy_ecs_ldtk supports LDtk layers with colliding tiles (multiple tiles in one location) by spawning multiple tilemaps.

Important: Each of these tilemaps will have its own LayerMetadata component. Therefore, you cannot assume there is only one LayerMetadata entity per LDtk layer.

In 0.9, fields on a bundle derived with #[derive(LdtkEntity)] or #[derive(LdtkIntCell)] are constructed from the bundle's Default implementation, not the field's own Default implementation.

If your bundle's Default provides a different value than the field's Default, the bundle's value will be used. Additionally, you may need to explicitly implement Default for your LdtkEntity bundles if they didn't have it before.

#[derive(Component)]
struct MyComponent(usize);

impl Default for MyComponent {
    fn default() -> MyComponent {
        MyComponent(1)
    }
}

#[derive(Bundle, LdtkEntity)]
struct MyBundle {
    component: MyComponent,
}

impl Default for MyBundle {
    fn default() -> MyBundle {
        MyBundle {
            component: MyComponent(2),
        }
    }
}

// In 0.9, the plugin spawns the entity with MyComponent(2)

For complex level-spawning needs, use the LevelSet component instead of the global LevelSelection resource. LevelSet allows you to select a specific set of levels by their iids.

Key Characteristics:

• Per-World Selection: If you have multiple LdtkWorldBundle instances, LevelSet allows you to select different levels for each world, whereas LevelSelection is global.
• Declarative/Idempotent Updates: When the LevelSet is updated, the plugin performs change detection. It only spawns levels that are in the set but not yet spawned, and despawns levels that are currently spawned but no longer in the set.
• Limitations: You cannot use load_level_neighbors with this workflow. However, LevelSpawnBehavior::UseWorldTranslation still works.
• Constraint: For LevelSet to function correctly, the LevelSelection resource must not exist in the world.

The 'Explanation' section provides deep dives into the mental models required to use the library effectively, including:

• Level Selection: How to manage and switch between different levels.
• Game Logic Integration: How to bridge LDtk data with Bevy game logic.
• Anatomy of the World: Understanding the structural hierarchy of the loaded world.
• Plugin Schedule: How the plugin interacts with the Bevy schedule.
• Asset Model: How LDtk assets are represented within Bevy.
• Limitations: Known constraints of the current implementation.

Using the LdtkEntity derive macro allows you to define "worldly" entities. These are entities designed to persist and traverse between levels (e.g., a player character).

Key behaviors of worldly entities:

1. Hierarchy Shift: Instead of being children of an Entity layer, worldly entities become children of the world entity (after one update). This makes them independent of their origin level, allowing them to persist even if the level that spawned them is unloaded.
2. Persistence: A worldly entity will not be spawned if it already exists. This prevents duplicate entities (like two players) when an origin level is despawned and subsequently respawned.

To implement tile-based mechanics, you need to track an entity's position in grid-space rather than just its Bevy Transform.

bevy_ecs_ldtk provides the GridCoords component for this purpose. You can integrate it with the LdtkEntity derive macro by adding the #[grid_coords] attribute to your bundle. When the entity is spawned from LDtk, it will automatically receive a GridCoords component matching its position in the grid.

It is recommended to also add a marker component (e.g., struct Player;) and derive Default so bevy_ecs_ldtk can use the default implementation during spawning.

#[derive(Component, Default)]
struct Player;

#[derive(LdtkEntity)]
struct PlayerBundle {
    #[grid_coords]
    grid_coords: GridCoords,
    player: Player,
    // ... other components
}

To determine the physical area a level occupies in the world, you must combine its spatial transform with its dimensions from the LDtk asset data:

1. Access Asset Data: Query for the LdtkProjectHandle and look up the LdtkProject in the asset store.
2. Get Level Data: Use the level entity's LevelIid component to retrieve the raw level data.
3. Compute Bounds:
   • The lower-left bound is the x and y values from the level's GlobalTransform.
   • The upper-right bound is calculated by adding the level's px_wid (pixel width) and pix_hei (pixel height) to the lower-left coordinates.
4. Result: This creates a Rect representing the level's bounds in world space.