docs/plugins/bevy_ecs_ldtk.md

bevy_ecs_ldtk

---

Customizing LDtk entities

---

The spawning of entities can be customized by registering a bundle that will be used for spawning the entity. The bundle struct must implement the LdtkEntity trait:

#[derive(Clone, Default, Bundle, LdtkEntity)]
pub struct PlayerBundle {
    #[sprite_bundle("player.png")]
    pub sprite_bundle: SpriteBundle,
    #[from_entity_instance]
    pub collider_bundle: ColliderBundle,
    pub player: Player,
    #[worldly]
    pub worldly: Worldly,
}

fn my_plugin(app: &mut App) {
    // Registers PlayerBundle to be spawned for a given Entity identifier
    app.register_ldtk_entity::<PlayerBundle>("Player");
}

The LdtkEntity trait can either be derived manually or using the derive macro as in the above example. Using derive, the fields can be components or bundles. Their instantiation can be customized using:

Default trait

---

All fields must implement the Default trait. Implementing it manually lets you configure the initialization. This approach is relevant when:

• All usages of the component/bundle should have the same initial value,
• The initial value doesn't depend on the LDtk data of the instance.

#[with(...)] and #[from_entity_instance]

---

These allow the field to be constructed from an &EntityInstance, enabling access to the data of the instance (e.g., identifier, fields, pivot, etc.). #[with(...)] allows specifying a fn (entity: &EntityInstance) -> T user function that will construct the field T from the &EntityInstance. #[from_entity_instance] is similar but uses the From<&EntityInstance> trait of the field, which should provide a fn from(entity: &EntityInstance) -> T function for constructing the field.

Special components

---

Some sprite and LDtk components have predefined instantiation methods:

• SpriteBundle can be initialized using the #[sprite_bundle(...)] tag. See the player example.
• Similarly, SpriteSheetBundle can be initialized by specifying the #[sprite_sheet_bundle("path/to/asset.png", tile_width, tile_height, columns, rows, padding, offset, index)] tag.
• Both of the above tags will use data from the visual editor if no path or sheet coordinate are specified: #[sprite_bundle] and #[sprite_sheet_bundle].
• #[worldly] worldly: Worldly, will attach a special component specifying that the entity should not be despawned when their level despawns.
• #[grid_coords] grid_coords: GridCoords, attach a component containing the initial grid position of the component.

Manually implementing LdtkEntity

---

For advanced usage, the LdtkEntity trait can be manually implemented, defining the constructor function:

impl LdtkEntity for MyComponentOrBundle {
    fn bundle_entity(
        entity_instance: &EntityInstance,
        layer_instance: &LayerInstance,
        tileset: Option<&Handle<Image>>,
        tileset_definition: Option<&TilesetDefinition>,
        asset_server: &AssetServer,
        texture_atlases: &mut Assets<TextureAtlas>
    ) -> Self
    { Self { ... } }
}

The arguments provide everything needed for inspecting the entity (&EntityInstance, tile sets), the level layer (&LayerInstance), and loading assets (&AssetServer and &mut Assets<TextureAtlas>).