Crate bevy_ecs_ldtk

bevy_ecs_ldtk

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:

• Tile-based Game tutorial
• Level Selection explanation
• Game Logic Integration explanation

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.

Re-exports

pub use crate::ldtk::EntityInstance;

Modules

app

Types and traits for hooking into the ldtk loading process via bevy::app::App.

assets

Assets and related items for loading LDtk files.

ldtk

Contains all the types for serializing/deserializing an LDtk file.

prelude

use bevy_ecs_ldtk::prelude::*; to import commonly used items.

systems

System functions used by the plugin for processing ldtk files.

utils

Utility functions used internally by the plugin that have been exposed to the public api.

Structs

EntityIid

Component added to all LdtkEntitys by default.

GridCoords

Component that stores grid-based coordinate information.

IntGridCell

Component added to any IntGrid tile by default.

LayerMetadata

Component for storing some LDtk layer information on layer entities.

LdtkPlugin

Adds the default systems, assets, and resources used by bevy_ecs_ldtk.

LdtkProjectHandle

Component storing the LDtk project asset handle, marking the root entity for the plugin to spawn levels in.

LdtkSettings

Settings resource for the plugin. Check out the documentation for each field type to learn more.

LdtkWorldBundle

Bundle for spawning LDtk worlds and their levels. The main bundle for using this plugin.

LevelIid

Component that stores a level’s instance identifier.

LevelSet

Component that determines the desired levels to be spawned in an LdtkWorldBundle.

ProcessLdtkApi

Schedule for processing this plugin’s ECS API, inserted after Update.

Respawn

Component that indicates that an LDtk level or world should respawn.

SpawnExclusions

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.

TileEnumTags

Component for storing user-defined, enum-based tags for a particular tile in an LDtk tileset definition.

TileMetadata

Component for storing user-defined custom data for a paticular tile in an LDtk tileset definition.

Worldly

Component that indicates that an ldtk entity should be a child of the world, not their layer.

Enums

IntGridRendering

Option in LdtkSettings that determines the visual representation of IntGrid layers when they don’t have AutoTile rules.

LevelBackground

Option in LdtkSettings that dictates how the plugin handles level backgrounds.

LevelEvent

Events fired by the plugin related to level spawning/despawning.

LevelSelection

Resource for choosing which level(s) to spawn.

LevelSpawnBehavior

Option in LdtkSettings that determines level spawn behavior.

SetClearColor

Option in LdtkSettings that determines clear color behavior.

Derive Macros

LdtkEntity

LdtkIntCell