Skip to content

Entity Framework

Entities represent all interactive, physical, or visual objects living within a game Environment. The entity system provides spatial indexing, life cycles, message dispatching, and declarative metadata configuration.

Entity System Documentation Sections

  • Default Entity Types

    Complete overview of built-in classes: Creature, Prop, Trigger, Spawnpoint, CollisionBox, and LightSource.

  • Annotations & Matrix

    Declarative metadata (@EntityInfo, @CollisionInfo, @MovementInfo, @CombatInfo) and the Entity Architecture Matrix.

  • Custom Entities

    Subclassing base entities, registering custom XML loaders, and binding specialized behaviors.

  • Entity Events & Listeners

    Lifecycle callbacks: onMoved, onHit, onDeath, onCollision, and custom message dispatching.

Spatial Entity Queries (EntityQuery)

To find, filter, and sort entities within an environment without writing repetitive stream filters or distance calculations, use environment.query(Class):

// Find closest living enemy within 250px
Optional<Creature> target = Game.world().environment()
    .query(Creature.class)
    .alive()
    .enemyOf(player)
    .within(player.getCenter(), 250)
    .nearestTo(player.getCenter())
    .first();

See Fluent Entity Queries in the Game World guide for a complete method reference.