LDtk Tilesets

The Problem

LDtk tilesets define the tile textures used in your levels. Each tileset has metadata: tile size, spacing, padding, and a path to the image file. Loading tileset textures and using them correctly requires parsing this metadata and loading the texture files.

What Void Does

Void provides a fully typed LDtkTileset class that contains all tileset metadata. Tilesets are loaded as part of the LDtk map and cached by ID and name. Helper methods make it easy to load the actual texture files.

LDtkTileset

The LDtkTileset class represents a tileset definition from an LDtk project. It contains all the metadata needed to work with the tileset.

public sealed class LDtkTileset
{
    public uint Id { get; }
    public string Name { get; }
    public Vect2 CellSize { get; }
    public Vect2 Size { get; }
    public string Path { get; }
    public int TileSize { get; }
    public int Spacing { get; }
    public int Padding { get; }
    public List<string> Tags { get; }
}

Accessing Tilesets

// Get a tileset by ID
var tileset = map.GetTilesetById(1);

// Get a tileset by name
var tileset = map.GetTilesetByName("Tileset_01");

// Or iterate through all tilesets in the map
// (Tilesets are stored in the map's caches)
if (map.TryGetTilesetByName("Tileset_01", out var tileset))
{
    // Use the tileset
}

Tileset Properties

Property	Description
Id	Unique identifier of the tileset
Name	Display name of the tileset
CellSize	Number of tiles in each dimension
Size	Size of the tileset texture in pixels
Path	Relative path to the tileset image file
TileSize	Size of each tile in pixels
Spacing	Spacing between tiles in the texture
Padding	Padding around tiles in the texture
Tags	List of tags associated with the tileset

Loading Tileset Textures

Tileset textures are loaded through the AssetManager.

// Get the tileset
var tileset = map.GetTilesetByName("Tileset_01");

// Load the tileset texture
var texture = AssetManager.Instance.LoadTexture(tileset.Path);

Helper Methods

Void provides helper methods to load tileset textures directly from the LDtk map.

// Load tileset texture for a specific tileset ID
var texture = AssetManager.Instance.LoadTilesetTexture(map, tilesetId);

// Or use the try pattern
if (AssetManager.Instance.TryLoadTilesetTexture(map, tilesetId, out var texture))
{
    // Use the texture
}

The helper methods:

• Handle path remapping from LDtk to your content root
• Normalize paths for cross-platform compatibility
• Use the AssetManager cache so textures are only loaded once

Tile References

Tiles are referenced by their tileset ID and source rectangle. The LDtkTile struct represents a tile reference.

public readonly struct LDtkTile
{
    public int TilesetId { get; }
    public Rect2 Source { get; }
}

// Get a tile from a setting
var tile = LDtkSetting.GetTileSetting(settings, "TileName");

// Access tile properties
int tilesetId = tile.TilesetId;
Rect2 source = tile.Source;

// Get the tileset from the map
var tileset = map.GetTilesetById((uint)tile.TilesetId);

// Load the tile texture
var texture = AssetManager.Instance.LoadTilesetTexture(map, (uint)tile.TilesetId);

Quick Example

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

// Get a tileset by name
var tileset = map.GetTilesetByName("Tileset_01");

// Access tileset properties
int tileSize = tileset.TileSize;
string texturePath = tileset.Path;

// Load the tileset texture
var texture = AssetManager.Instance.LoadTexture(tileset.Path);

// Or use the helper
var texture = AssetManager.Instance.LoadTilesetTexture(map, tileset.Id);

// Get tile references from a setting
if (LDtkSetting.TryGetTileSetting(settings, "TileName", out var tile))
{
    var source = tile.Source;
    // Draw the tile using the source rectangle
}

---

Back to Home