LDtk Map Loading

The Problem

Loading an LDtk map involves more than just reading a JSON file. You need to parse the data, build lookup caches, handle tilesets, and provide fast access to levels, layers, and entities. Most implementations force you to write this code yourself, or they give you raw JSON data and leave you to figure out the rest.

What Void Does

Void handles everything for you. The LDtkMap class is an IAsset, which means it loads through the AssetManager like any other asset. It parses the JSON once, builds all the necessary caches, and gives you strongly typed access to everything.

Loading a Map

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

That's it. One line. The AssetManager finds the file, loads the data, parses the JSON, and builds the caches.

What Happens When You Load

Step	What Happens
1	AssetManager finds the .ldtk file in the mount system
2	File data is read as bytes
3	JSON is parsed once
4	Tilesets are extracted and cached by ID and name
5	Levels are extracted and cached by ID and name
6	Layers are extracted and cached by ID
7	Entities are extracted and cached by ID
8	The map is added to the AssetManager cache

The LDtkMap Class

The LDtkMap class is the main entry point for LDtk data. It provides methods for accessing everything in the map.

public sealed class LDtkMap : IAsset
{
    public uint Id { get; }
    public string Tag { get; }
    public bool IsValid { get; }
    public DateTime LastAccessTime { get; set; }
    public byte[] Data { get; }

    // Level lookups
    public LDtkLevel GetLevelById(string id);
    public bool TryGetLevelById(string id, out LDtkLevel level);
    public LDtkLevel GetLevelByName(string name);
    public bool TryGetLevelByName(string name, out LDtkLevel level);

    // Layer lookups
    public MapLayer GetLayerById(string id);
    public bool TryGetLayerById(string id, out MapLayer layer);

    // Entity lookups
    public LDtkEntityInstance GetEntityById(string id);
    public bool TryGetEntityById(string id, out LDtkEntityInstance entity);

    // Tileset lookups
    public LDtkTileset GetTilesetById(uint id);
    public bool TryGetTilesetById(uint id, out LDtkTileset tileset);
    public LDtkTileset GetTilesetByName(string name);
    public bool TryGetTilesetByName(string name, out LDtkTileset tileset);
}

Caching

All lookups are cached by hash. When you request a level by name, the string is hashed once and used as a key into the dictionary. Subsequent lookups are O(1).

// First access: loads and caches the map
var map = AssetManager.Instance.Load<LDtkMap>("levels/world.ldtk");

// These are all O(1) lookups
var level = map.GetLevelByName("Level_01");
var layer = map.GetLayerById("layer_entities");
var entity = map.GetEntityById("abc-123-def-456");
var tileset = map.GetTilesetByName("Tileset_01");

Try Methods

Void provides Try methods for safe access when you're not sure if something exists.

if (map.TryGetLevelByName("Level_01", out var level))
{
    // Level exists, use it
}
else
{
    // Level doesn't exist, handle gracefully
}

if (map.TryGetEntityById("entity_id", out var entity))
{
    // Entity exists, use it
}

Tileset Loading

Tilesets are loaded through the AssetManager. The LDtkMap stores tileset metadata, and you load the actual texture separately.

var map = AssetManager.Instance.Load<LDtkMap>("levels/world.ldtk");
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. These methods handle path remapping and normalization automatically.

// 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 are useful because they:

• 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

File Location

LDtk files are stored in your Content folder. The AssetManager finds them through the mount system.

Content/
└── levels/
    └── world.ldtk

Supported File Formats

Format	Extension	Load Method
LDtk project	.ldtk	Load<LDtkMap>()
LDtk JSON	.json	Load<LDtkMap>()

Both formats are supported. Use the .ldtk extension for the project file, or .json for exported level data.

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");

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

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

---

Back to Home