LDtk Entities

The Problem

LDtk entities are the game objects you place in your levels. They contain position, size, pivot, tags, and custom field data. Most LDtk integrations give you raw JSON data and force you to manually parse entity fields into your own game objects.

What Void Does

Void provides a fully typed LDtkEntityInstance class that contains all entity data with strongly typed access. You can access entity properties directly and retrieve custom fields using type-safe methods.

LDtkEntityInstance

The LDtkEntityInstance class represents a single entity placed in a level. It contains the entity's name, ID, position, size, pivot, tags, and custom settings.

public sealed class LDtkEntityInstance : ILDtkInstance
{
    public string Name { get; }
    public Vect2 Pivot { get; }
    public string Id { get; }
    public Vect2 Size { get; }
    public Vect2 Coords { get; }
    public List<string> Tags { get; }
    public Dictionary<uint, LDtkSetting> Settings { get; }
    public Vect2 Location { get; }
    public Vect2 Position { get; }
    public float Width { get; }
    public float Height { get; }
}

Accessing Entities

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

// Get a specific entity by ID
var entity = map.GetEntityById("abc-123-def-456");

// Or iterate through all entities in a layer
foreach (var entity in entities)
{
    Console.WriteLine($"Entity: {entity.Name} at {entity.Position}");
}

Entity Properties

Property	Description
Name	The name of the entity type
Id	Unique identifier of this specific entity instance
Position	Pixel position in world space
Location	Grid location in tile coordinates
Size	Width and height in pixels
Pivot	Pivot point (0-1) relative to the entity
Coords	World coordinates
Tags	List of tags associated with the entity
Settings	Custom field settings dictionary
Width	Width in pixels
Height	Height in pixels

Entity Settings

Entities can have custom fields defined in LDtk. Access them using the LDtkSetting helper class.

var entity = map.GetEntityById("abc-123-def-456");

// Get a boolean setting
if (LDtkSetting.TryGetBoolSetting(entity.Settings, "IsActive", out bool isActive))
{
    // Use isActive
}

// Get an integer setting
if (LDtkSetting.TryGetIntSetting(entity.Settings, "Health", out int health))
{
    // Use health
}

// Get an enum setting
if (LDtkSetting.TryGetEnumSetting<EnemyType>(entity.Settings, "Type", out var type))
{
    // Use type
}

// Get a Vect2 point setting
if (LDtkSetting.TryGetPointSetting(entity.Settings, "SpawnPoint", out Vect2 spawnPoint))
{
    // Use spawnPoint
}

For more information on accessing entity settings, see the LDtk Settings page.

Entity Tags

Entities can have tags that are useful for grouping and filtering.

var entity = map.GetEntityById("abc-123-def-456");

// Check if the entity has a specific tag
if (entity.Tags.Contains("boss"))
{
    // Handle boss entity
}

// Get tags as enums
var tags = entity.TagsAs<EntityTag>();

Creating Game Objects from Entities

A common pattern is to use the entity name to create the appropriate game object.

In the example below, MapEntity is your game's own base class or interface; it is not a built-in VOID type.

foreach (var entity in entities)
{
    // Use InstanceHelper to create the correct game object type
    if (InstanceHelper.TryCreateInstance<MapEntity>(entity.Name, true, [entity], out var instance))
    {
        // Add the instance to your game world
        _manager.Add(instance);
    }
}

Entity Lookup

Entities can be looked up by ID from anywhere in the map.

// Get an entity by ID
var entity = map.GetEntityById("entity_id");

// Or try get with fallback
if (map.TryGetEntityById("entity_id", out var entity))
{
    // Use the entity
}

Quick Example

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

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

// Find all entities in the level
foreach (var layer in level.Layers)
{
    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))
            {
                Console.WriteLine($"  Health: {health}");
            }

            // Get entity tags
            if (entity.Tags.Contains("boss"))
            {
                Console.WriteLine($"  This is a boss entity");
            }
        }
    }
}

---

Back to Home