Crate ldtk[−][src]

A crate for reading the LDtk tile map format.

This crate implements the Rust structures necessary to Serialize and Deserialize the LDtk map format using serde.

Example

Cargo.toml:

# Note: We must specify the version of LDtk we want to support in a feature flag
ldtk = { version = "0.4.0", features = ["ldtk-v0-9-3"] }

main.rs:

use ldtk::Project;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load the map
    let map: Project =
        serde_json::from_slice(include_bytes!("../examples/full-features.ldtk"))?;

    // Debug print the map
    dbg!(map);

    Ok(())
}

Extra Documentation

For more information on using the LDtk project structure inside of games see the LDtk docs.

Naming Conventions

This crate uses the same struct field names as the raw JSON format in almost all cases. The exception to this rule is for fields that are named type. In this case the name of the field will be prefixed with the name of it’s struct, converted to snake case, for instance field_def_type.

The `__field_name` Convention

It is a convention of the LDtk map format to prefix certain convenience fields with two underscores, such as __tile_src_rect. These fields are redundant, as the information in them is also present elsewhere in the project structure, but they are provided in some cases where it may make traversing the project structure much more convenient.

The double underscore prefix does not indicate that the field is a private field or an implementation detail.

Build Configuration & Features

This entire crate is automatically generated from the JSON Schema from the LDtk repo and can be automatically updated with LDtk releases.

By default the crate requires that you pass a feature indicating a version of the JSON schema that is built into the crate so that it doesn’t require network access to build, but you can also supply the download-schema cargo feature to make the crate download the JSON schema from the LDtk repo instead ( See “Downloading the Schema” below ).

This crate currently has the schema for the following versions of LDtk built-in:

v0.9.3
v0.8.1 ( patched, see note below )
v0.7.0

The format of the feature flags for specific versions is like this: ldtk-v0-9-3. Note that the periods in the version have been replaced with dashes to be conformat with cargo’s feature naming conventions.

Note: In version 0.8.1 there was a field that was marked as non-null in the JSON schema, but in one of the LDtk sample maps the field was null. We patched the JSON schema to make the field nullable so that the map would load correctly.

As newer LDtk versions are released we may add new built-in schemas. These will each be under new feature flags so that updates to the schema do not need to be breaking changes.

Downloading the Schema

When the download-schema feature is provided, you can specify which version of LDtk you want to build this crate for by setting the LDTK_VERSION environment variable at build time. LDTK_VERSION will default to master which will pull the latest schema from the master branch of the LDtk git repo.

License

LDtk-rs is licensed under the Katharos License which places certain restrictions on what you are allowed to use it for. Please read and understand the terms before using LDtk-rs for your project.

Structs

AutoLayerRuleGroup
AutoRuleDef	This complex section isn’t meant to be used by game devs at all, as these rules are completely resolved internally by the editor before any saving. You should just ignore this part.
Definitions	If you’re writing your own LDtk importer, you should probably just ignore most stuff in the `defs` section, as it contains data that are mostly important to the editor. To keep you away from the `defs` section and avoid some unnecessary JSON parsing, important data from definitions is often duplicated in fields prefixed with a double underscore (eg. `__identifier` or `__type`). The 2 only definition types you might need here are Tilesets and Enums.
EntityDef
EntityInstance
EntityInstanceTile	Tile data in an Entity instance
EnumDef
EnumDefValues
FieldDef	This section is mostly only intended for the LDtk editor app itself. You can safely ignore it.
FieldInstance
IntGridValueDef	IntGrid value definition
IntGridValueInstance	IntGrid value instance
LayerDef
LayerInstance
Level	This section contains all the level data. It can be found in 2 distinct forms, depending on Project current settings: - If “Separate level files” is disabled (default): full level data is embedded inside the main Project JSON file, - If “Separate level files” is enabled: level data is stored in separate standalone `.ldtkl` files (one per level). In this case, the main Project JSON file will still contain most level data, except heavy sections, like the `layerInstances` array (which will be null). The `externalRelPath` string points to the `ldtkl` file. A `ldtkl` file is just a JSON file containing exactly what is described below.
LevelBgPosInfos	Level background image position info
NeighbourLevel	Nearby level info
Project	This is the root of any Project JSON file. It contains: - the project settings, - an array of levels, - a group of definitions (that can probably be safely ignored for most users).
Tile	This structure represents a single tile from a given Tileset.
TileFlip	Whether or not the tile is flipped on the x and/or y axes.
TilesetDef	The `Tileset` definition is the most important part among project definitions. It contains some extra informations about each integrated tileset. If you only had to parse one definition section, that would be the one.

Crate ldtk⎘[−][src]

Crate ldtk[−][src]