Crate bevy_ecs_ldtk

source ·
Expand description


bevy_ecs_ldtk is an ECS-friendly LDtk plugin for Bevy. It allows you to use LDtk projects as an asset, spawn levels, and insert bevy components/bundles on LDtk entities/tiles. This plugin is ECS-friendly, partly for its internal usage of ECS that provides extra functionality to users, and partly for its usage of bevy_ecs_tilemap for rendering tilemaps. This is all behind an ergonomic API, providing low-boilerplate solutions to common use cases. For less common use cases, strategies that leverage this plugin’s ECS constructs are also available.

§This API Reference

The purpose of this API reference is to describe the API provided by this plugin. More explanation-oriented documentation, tutorials, and guides are available in the bevy_ecs_ldtk book.

The following chapters are good jumping-off points for beginners:

Cargo examples are also available in this plugin’s github repository.

§Feature flags

This crate uses the following set of feature flags:

  • internal_levels: Enable support for projects that store levels internally. I.e., projects that store level data within the main project file.
  • external_levels: Enable support for projects that store levels externally. I.e., projects that store data for each level in files separate from the main project file.
  • derive: Enables the derive macros for LdtkEntity and LdtkIntCell.
  • render: Enables rendering via bevy_ecs_tilemap’s render feature. Disable it if you want to run in headless mode.
  • atlas: Enables the atlas feature of bevy_ecs_tilemap. This is required for WASM support and also for tile spacing to work on Tile and AutoTile layers.

The derive, render, and internal_levels features are enabled by default. Furthermore, one or both of internal_levels and external_levels must be enabled.



  • Types and traits for hooking into the ldtk loading process via [bevy::app::App].
  • Assets and related items for loading LDtk files.
  • Contains all the types for serializing/deserializing an LDtk file.
  • use bevy_ecs_ldtk::prelude::*; to import commonly used items.
  • System functions used by the plugin for processing ldtk files.
  • Utility functions used internally by the plugin that have been exposed to the public api.


  • [Component] added to all LdtkEntitys by default.
  • [Component] that stores grid-based coordinate information.
  • [Component] added to any IntGrid tile by default.
  • [Component] for storing some LDtk layer information on layer entities.
  • Adds the default systems, assets, and resources used by bevy_ecs_ldtk.
  • Settings resource for the plugin. Check out the documentation for each field type to learn more.
  • Bundle for spawning LDtk worlds and their levels. The main bundle for using this plugin.
  • Component that stores a level’s instance identifier.
  • Component that determines the desired levels to be spawned in an LdtkWorldBundle.
  • Schedule for processing this plugin’s ECS API, inserted after [Update].
  • [Component] that indicates that an LDtk level or world should respawn.
  • Specifies data that should be ignored completely when spawning levels. Excluded items will still be present in the LdtkProject but will not cause any entities to be spawned in the world.
  • [Component] for storing user-defined, enum-based tags for a particular tile in an LDtk tileset definition.
  • [Component] for storing user-defined custom data for a paticular tile in an LDtk tileset definition.
  • [Component] that indicates that an ldtk entity should be a child of the world, not their layer.


Derive Macros§