Custom Properties¶

Custom properties allow you to attach arbitrary data to map objects in the Tiled editor or utiLITI. These properties are then accessible at runtime to configure entity behavior.

Adding Custom Properties¶

In utiLITI¶

Select a map object on your map
In the Properties panel, find the Custom Properties section
Click + to add a new property
Enter the property name and value

In Tiled Editor¶

Select an object
In the Properties view, click + Add Property
Choose the property type (string, int, float, bool, color, etc.)
Set the name and value

Built-in Property Names¶

LITIENGINE recognizes several built-in property names that configure entity behavior:

Property	Type	Description
`sprite`	String	Spritesheet name for the entity
`collision`	Boolean	Enable/disable collision
`collisionBoxWidth`	Int	Collision box width in pixels
`collisionBoxHeight`	Int	Collision box height in pixels
`align`	String	Horizontal alignment (LEFT, CENTER, RIGHT)
`valign`	String	Vertical alignment (TOP, MIDDLE, BOTTOM)
`velocity`	Float	Movement velocity
`acceleration`	Float	Movement acceleration
`deceleration`	Float	Movement deceleration
`hp`	Int	Hit points for combat entities

Reading Properties at Runtime¶

From MapObject¶

@Override
public Collection<IEntity> load(Environment environment, IMapObject mapObject) {
  // Read string property
  String customValue = mapObject.getStringValue("myProperty");

  // Read with default value
  String value = mapObject.getStringValue("optional", "default");

  // Read typed properties
  int intValue = mapObject.getIntValue("count", 0);
  float floatValue = mapObject.getFloatValue("speed", 1.0f);
  boolean boolValue = mapObject.getBoolValue("enabled", true);

  // ...
}

From Entity¶

// Get entity's custom property
IEntity entity = Game.world().environment().get("my-entity");
String customValue = entity.getStringValue("customProp");

Using MapObjectProperty Constants¶

import de.gurkenlabs.litiengine.environment.tilemap.MapObjectProperty;

// Use constants for built-in properties
String sprite = mapObject.getStringValue(MapObjectProperty.SPRITE);
int hp = mapObject.getIntValue(MapObjectProperty.COMBAT_HITPOINTS, 100);

Property Types¶

Custom properties support various data types:

String¶

name: "playerName"
value: "Hero"

Integer¶

name: "maxHealth"
value: 100

Float¶

name: "moveSpeed"
value: 2.5

Boolean¶

name: "isInvulnerable"
value: true

Color¶

name: "tintColor"
value: #FF5500

File Path¶

name: "configFile"
value: "config/enemy.json"

Common Use Cases¶

Enemy Configuration¶

type=enemy
sprite=goblin
hp=50
damage=10
speed=1.5
patrol=true

Interactive Objects¶

type=interactable
dialogue=npc_villager_01
questId=village_main

Trigger Zones¶

type=trigger
onEnter=spawn_enemies
target=wave1
once=true

Using Properties in Custom Loaders¶

public class EnemyLoader extends MapObjectLoader {

  @Override
  public Collection<IEntity> load(Environment environment, IMapObject mapObject) {
    Enemy enemy = new Enemy();

    // Configure from properties
    enemy.setHealth(mapObject.getIntValue("hp", 100));
    enemy.setDamage(mapObject.getIntValue("damage", 10));
    enemy.setSpeed(mapObject.getFloatValue("speed", 1.0f));
    enemy.setPatrols(mapObject.getBoolValue("patrol", false));

    return List.of(enemy);
  }
}