Default Entity Types¶

Master Entity Blueprint Matrix¶

Choose the optimal entity type for your game objects:

Icon	Entity Type	Purpose / Use Case	Default Collision	Key Annotations	utiLITI Object Type	Key Behaviors & Hooks
	Creature	Living characters, NPCs, enemies, players	Yes (Dynamic box)	@EntityInfo, @MovementInfo, @CombatInfo, @CollisionInfo	CREATURE	onMoved, onHit, onDeath, onResurrect
	Prop	Interactive/static map objects (chests, trees, pots)	Configurable	@EntityInfo, @CollisionInfo	PROP	onHit, onDeath, PropState
	CollisionBox	Static physics obstacle barrier / wall	Static collider	None	COLLISIONBOX	isObstructingLight(), pathfinding blocking
	Trigger	Invisible event zones (doors, cutscenes, teleporters)	Sensor only	@EntityInfo	TRIGGER	addActivatedListener, addDeactivatedListener
	Spawnpoint	Level entry points and entity spawn markers	None	@EntityInfo	SPAWNPOINT	onSpawned, spawn(IEntity)
	LightSource	Dynamic/static ambient lights & torches	None	@EntityInfo	LIGHTSOURCE	activate(), deactivate(), setColor()
	SoundSource	Ambient or looping positional audio emitters	None	@EntityInfo	SOUNDSOURCE	play(), setLoop(boolean), setRange(int)
	StaticShadow	Baked directional drop shadows	None	None	STATICSHADOW	getShadowType(), setOffset()
	Emitter	Particle sources (fire, weather, explosions)	None	@EntityInfo	EMITTER	onFinished, data().setEmitterDuration(...)
	MapArea	Named spatial zones, boundary detection, scripts	Sensor / None	@EntityInfo	AREA	Zone boundary queries, getArea(name)

LITIENGINE provides a hierarchy of built-in entity types. Each type builds upon the previous, adding more functionality.

Entity Hierarchy¶

graph TD
    IE["<b>IEntity</b><br/><i>Core entity interface</i>"]
    E["<b>Entity</b><br/><i>Base game object (position, size, tags, actions)</i>"]
    CE["<b>CollisionEntity</b><br/><i>Collision box & physics interaction</i>"]
    CB["<b>CollisionBox</b><br/><i>Static obstacle barrier</i>"]
    CBE["<b>CombatEntity</b><br/><i>Hit points, combat states, hit/death hooks</i>"]
    CR["<b>Creature</b><br/><i>Animations, movement controllers, facing direction</i>"]
    PR["<b>Prop</b><br/><i>Static/dynamic destructible map objects</i>"]
    MA["<b>MapArea</b><br/><i>Named spatial zone & boundary</i>"]
    SSH["<b>StaticShadow</b><br/><i>Baked directional shadow</i>"]
    SS["<b>SoundSource</b><br/><i>Ambient spatial audio</i>"]
    TR["<b>Trigger</b><br/><i>Collision/interaction sensor</i>"]
    SP["<b>Spawnpoint</b><br/><i>Entity spawn marker</i>"]
    EM["<b>Emitter</b><br/><i>Particle effect source</i>"]
    LS["<b>LightSource</b><br/><i>Dynamic illumination</i>"]

    IE --> E
    E --> CE
    E --> MA
    E --> SS
    E --> TR
    E --> SP
    E --> EM
    E --> LS
    MA --> SSH
    CE --> CB
    CE --> CBE
    CBE --> CR
    CBE --> PR

Entity¶

The base class for all game objects.

public class MyEntity extends Entity {
  public MyEntity() {
    super("my-entity");
    setLocation(100, 100);
    setSize(32, 32);
  }
}

Key Properties¶

• Name: Unique identifier
• Location: X/Y position in the world
• Size: Width and height
• MapId: ID from map object
• Tags: String tags for categorization
• RenderType: Rendering layer (NONE, BACKGROUND, GROUND, SURFACE, NORMAL, OVERLAY, UI)

CollisionEntity¶

Extends Entity with collision detection capabilities.

@EntityInfo(width = 32, height = 32)
@CollisionInfo(collisionBoxWidth = 28, collisionBoxHeight = 28, collision = true, collisionType = Collision.STATIC)
public class Wall extends CollisionEntity {
  public Wall() {
    super("wall");
  }
}

Collision Types (Collision)¶

• DYNAMIC (default): Collides with static geometry and other dynamic entities (used for actors, creatures, moving obstacles).
• STATIC: Immovable geometry that dynamic entities collide against (used for walls, map boundaries).
• NONE: Disables collision resolution for this entity.
• ANY: Special filter flag used exclusively for PhysicsEngine spatial queries and raycasts (cannot be assigned directly to an entity's collisionType).

Key Properties¶

• Collision box dimensions and offset
• Collision type (DYNAMIC, STATIC, NONE)

CombatEntity¶

Extends CollisionEntity with health and combat mechanics.

@EntityInfo(width = 32, height = 32)
@CombatInfo(hitpoints = 100, team = 1)
public class Destructible extends CombatEntity {
  public Destructible() {
    super("destructible");
  }
}

Key Properties¶

• Hitpoints: Current and maximum health
• Team: For friend/foe identification
• Indestructible: Cannot be damaged
• Target: Can be targeted by abilities

Events¶

combatEntity.onHit(hitEvent -> { /* took damage */ });
combatEntity.onDeath((victim, hitEvent) -> { /* died */ });
combatEntity.onResurrect(resurrected -> { /* revived */ });

Creature¶

The most feature-rich entity type for living characters. Extends CombatEntity with movement, directional facing, and state animation controllers.

@EntityInfo(width = 18, height = 18)
@MovementInfo(velocity = 70, acceleration = 10)
@CombatInfo(hitpoints = 50)
@CollisionInfo(collisionBoxWidth = 14, collisionBoxHeight = 16, collision = true)
public class Player extends Creature {
  public Player() {
    super("player"); // Spritesheet name
  }
}

Features¶

• Automatic animation controller from spritesheets
• Movement controller integration
• Facing direction tracking (Direction.UP, DOWN, LEFT, RIGHT)
• State management (idle, walk, dead)

Key Methods¶

creature.getFacingDirection(); // Current facing direction
creature.setSpritesheetName("player-alt"); // Change spritesheet animation source
creature.isIdle(); // Check if not moving
creature.isDead(); // Check if dead

Prop¶

Static or interactive objects in the game world. Extends CombatEntity directly (does NOT inherit creature movement).

@EntityInfo(width = 32, height = 32)
@CollisionInfo(collision = true)
public class Barrel extends Prop {
  public Barrel() {
    super("barrel"); // Spritesheet name
  }
}

Prop States¶

• INTACT: More than 50% health or indestructible
• DAMAGED: Less than 50% health
• DESTROYED: Zero health

State-based Spritesheets¶

prop-barrel-intact.png
prop-barrel-damaged.png
prop-barrel-destroyed.png

Other Entity Types¶

Trigger¶

Area-based event triggers activated on collision or user interaction.

Trigger trigger = new Trigger(TriggerActivation.COLLISION, "door_sensor", "open_door");
trigger.addActivatedListener(event -> {
    IEntity entity = event.getEntity();
    // Action triggered when entity enters zone
});
trigger.addDeactivatedListener(event -> {
    // Action triggered when entity leaves zone
});

LightSource¶

Dynamic lighting entities.

LightSource light = new LightSource(150, Color.ORANGE, LightSource.Type.ELLIPSE, true);
light.setLocation(100, 100);
Game.world().environment().add(light);

Emitter¶

Particle effect sources.

Emitter emitter = new Emitter(100, 100);
emitter.data().setEmitterDuration(5000);
Game.world().environment().add(emitter);
emitter.activate();

Spawnpoint¶

Entity spawn locations and player start markers.

Spawnpoint spawn = new Spawnpoint(Direction.RIGHT);
spawn.setName("player_start");
spawn.setLocation(100, 100);
spawn.spawn(new Player());

CollisionBox¶

Static collision obstacles that block physical movement and pathfinding.

// Create an immovable collision barrier (e.g. wall, boundary)
CollisionBox wall = new CollisionBox(0, 0, 320, 16);
wall.setObstructingLight(true); // Optionally cast dynamic lighting shadows
Game.world().environment().add(wall);

SoundSource¶

Positional ambient audio emitters with automatic 2D distance falloff.

SoundSource waterfall = new SoundSource("waterfall.ogg");
waterfall.setLocation(250, 180);
waterfall.setLoop(true);
waterfall.setRange(300); // Audible within 300px radius
Game.world().environment().add(waterfall);
waterfall.play();

StaticShadow¶

Baked directional drop shadows for buildings, trees, and large scenery.

StaticShadow shadow = new StaticShadow(100, 100, 64, 32, StaticShadowType.DOWN);
shadow.setOffset(12);
Game.world().environment().add(shadow);

MapArea¶

Named spatial boundary zones for script triggers, camera bounds, and room queries.

MapArea bossArena = new MapArea(500, 200, 400, 300);
bossArena.setName("boss_arena");
Game.world().environment().add(bossArena);

// Query if an entity is inside the area
if (bossArena.getBoundingBox().contains(player.getCenter())) {
  // Trigger boss phase or room containment
}

Choosing the Right Type¶

Icon	Use Case	Entity Type	utiLITI Object Type
	Player characters, enemies, companions, NPCs	Creature	CREATURE
	Interactive/destructible scenery (chests, barrels, levers)	Prop	PROP
	Invisible static barriers, walls, level boundaries	CollisionBox	COLLISIONBOX
	Collision/interaction event sensors (doors, traps, portals)	Trigger	TRIGGER
	Player spawn positions, enemy respawn points	Spawnpoint	SPAWNPOINT
	Torches, lanterns, campfires, dynamic lighting	LightSource	LIGHTSOURCE
	Positional waterfalls, crackling fires, ambient soundscapes	SoundSource	SOUNDSOURCE
	Directional drop shadows underneath static obstacles	StaticShadow	STATICSHADOW
	Particle bursts, weather effects, fire, smoke	Emitter	EMITTER
	Spatial triggers, cutscene zones, camera boundaries	MapArea	AREA
	Lightweight decorative entity without physics	Entity	-

See Also¶

• Map Objects - Learn how map objects are placed, configured, and loaded from utiLITI and Tiled maps
• Entity Framework Overview - Entity lifecycle and management
• Annotations - Declarative configuration with @EntityInfo, @CollisionInfo, and @CombatInfo
• Props - Deep dive into prop states and destructible objects