LDtk Levels Layers

The Problem

LDtk levels contain multiple layers of different types. Each layer holds different kinds of data: entities, tiles, or integer grid values. Accessing this data efficiently requires understanding the layer types and knowing how to extract the information you need.

What Void Does

Void provides strongly typed access to levels and layers. Each level contains a list of layers, and each layer contains instances of the appropriate type. You can filter layers by type and access their data directly.

LDtkLevel

The LDtkLevel class represents a single level in an LDtk project. It contains metadata about the level and a list of layers.

public sealed class LDtkLevel
{
    public string Name { get; }
    public string Id { get; }
    public Vect2 Coords { get; }
    public int WorldDepth { get; }
    public Vect2 Size { get; }
    public Vect2 GridSize { get; }
    public Color Color { get; }
    public string BgPath { get; }
    public Vect2 BgPosition { get; }
    public Vect2 BgPivot { get; }
    public MapNeighbour Neighbours { get; }
    public IReadOnlyList<MapLayer> Layers { get; }
    public IReadOnlyDictionary<uint, LDtkSetting> Settings { get; }
}

Accessing Levels

// Get a level by name
var level = map.GetLevelByName("Level_01");

// Get a level by ID
var level = map.GetLevelById("abc-123-def-456");

// Access level properties
Vect2 size = level.Size;
Vect2 gridSize = level.GridSize;
Color bgColor = level.Color;

MapLayer

The MapLayer class represents a single layer within a level. It contains metadata about the layer and a list of instances.

public sealed class MapLayer
{
    public string Name { get; }
    public LDtkLayerType Type { get; }
    public Vect2 GridSize { get; }
    public int TileSize { get; }
    public float Opacity { get; }
    public Vect2 TotalOffset { get; }
    public uint TilesetId { get; }
    public string TilesetPath { get; }
    public string Id { get; }
    public int LevelId { get; }
    public Vect2 Offset { get; }
    public bool Visible { get; }
    public IReadOnlyList<ILDtkInstance> Instances { get; }
}

Layer Types

Type	Description
IntGrid	Integer grid layer containing cell values
Entities	Entity layer containing entity instances
Tiles	Tile layer containing tile instances
AutoLayer	Auto-layer containing automatically placed tiles

Accessing Layers

// Get a layer by ID
var layer = map.GetLayerById("layer_id");

// Or iterate through a level's layers
foreach (var layer in level.Layers)
{
    Console.WriteLine($"Layer: {layer.Name} ({layer.Type})");

    // Check if the layer is visible
    if (layer.Visible)
    {
        // Render the layer
    }
}

Filtering Layers

Use the InstanceAs<T> method to get instances of a specific type.

// Get all entity instances in a layer
var entities = layer.InstanceAs<LDtkEntityInstance>();

// Get all tile instances in a layer
var tiles = layer.InstanceAs<LDtkTileInstance>();

// Get all int grid instances in a layer
var grid = layer.InstanceAs<LDtkIntGridInstance>();

Layer Types in Detail

IntGrid Layers

IntGrid layers store integer values in a grid. Each cell contains an integer that can represent terrain types, collision data, or other grid-based information.

if (layer.Type == LDtkLayerType.IntGrid)
{
    var gridValues = layer.InstanceAs<LDtkIntGridInstance>();

    foreach (var cell in gridValues)
    {
        // Check if the cell is solid (value > 0)
        if (cell.IsSolid)
        {
            // Handle solid cell
        }

        // Get the index as an enum
        var terrainType = cell.IndexAsEnum<TerrainType>();
    }
}

Entity Layers

Entity layers contain entity instances. Each entity has a name, position, size, pivot, tags, and custom settings.

if (layer.Type == LDtkLayerType.Entities)
{
    var entities = layer.InstanceAs<LDtkEntityInstance>();

    foreach (var entity in entities)
    {
        Console.WriteLine($"Entity: {entity.Name} at {entity.Position}");

        // Access entity settings
        if (LDtkSetting.TryGetIntSetting(entity.Settings, "Health", out int health))
        {
            // Use health value
        }
    }
}

Tile Layers

Tile layers contain tile instances. Each tile has a source rectangle, flip effects, and an alpha value.

if (layer.Type == LDtkLayerType.Tiles || layer.Type == LDtkLayerType.AutoLayer)
{
    var tiles = layer.InstanceAs<LDtkTileInstance>();

    foreach (var tile in tiles)
    {
        // Get the source rectangle in the tileset
        Rect2 source = tile.Source;

        // Check if the tile is flipped
        if (tile.Effects.HasFlag(TextureEffects.Horizontal))
        {
            // Render flipped horizontally
        }

        // Get position
        Vect2 position = tile.Position;
    }
}

Quick Example

// Load the map
var map = AssetManager.Instance.Load<LDtkMap>("levels/world.ldtk");

// Get a level by name
var level = map.GetLevelByName("Level_01");

// Iterate through all layers
foreach (var layer in level.Layers)
{
    switch (layer.Type)
    {
        case LDtkLayerType.IntGrid:
            var grid = layer.InstanceAs<LDtkIntGridInstance>();
            // Process grid data
            break;

        case LDtkLayerType.Entities:
            var entities = layer.InstanceAs<LDtkEntityInstance>();
            // Process entities
            break;

        case LDtkLayerType.Tiles:
        case LDtkLayerType.AutoLayer:
            var tiles = layer.InstanceAs<LDtkTileInstance>();
            // Process tiles
            break;
    }
}

---

Back to Home