Entity Queries

Lookup by UUID

EntityStore entityStore = world.getEntityStore();

// get entity by UUID
Ref<EntityStore> ref = entityStore.getRefFromUUID(uuid);
if (ref != null && ref.isValid()) {
    // found entity
}

Lookup by Network ID

// get entity by client network ID
Ref<EntityStore> ref = entityStore.getRefFromNetworkId(networkId);

Iterating Entities

forEachChunk

Iterate archetype chunks containing entities with specific components:

Store<EntityStore> store = world.getEntityStore().getStore();

// ComponentType implements Query, so pass it directly
store.forEachChunk(Player.getComponentType(), (archetypeChunk, commandBuffer) -> {
    for (int index = 0; index < archetypeChunk.size(); index++) {
        Player player = archetypeChunk.getComponent(index, Player.getComponentType());
        TransformComponent transform = archetypeChunk.getComponent(index, TransformComponent.getComponentType());
        // process each player
    }
});

forEachEntityParallel

For parallel processing with index provided:

store.forEachEntityParallel(Player.getComponentType(), (index, archetypeChunk, commandBuffer) -> {
    Player player = archetypeChunk.getComponent(index, Player.getComponentType());
    // process player (thread-safe operations only)
});

Query Combinators

Combine component requirements with Query.and() and Query.or():

// entities with both Player AND Health components
Query<EntityStore> query = Query.and(Player.getComponentType(), Health.getComponentType());
store.forEachChunk(query, (archetypeChunk, commandBuffer) -> { ... });

// entities with Player OR NPC components
Query<EntityStore> query = Query.or(Player.getComponentType(), NPC.getComponentType());

EntityUtils

Helper methods for working with entities:

// get Entity component from ref
Entity entity = EntityUtils.getEntity(ref, store);

// check if archetype contains an Entity component
boolean hasEntity = EntityUtils.hasEntity(archetype);

// convert archetype chunk index to Holder
Holder<EntityStore> holder = EntityUtils.toHolder(index, archetypeChunk);

ECS Events

Dispatch events to specific entities using invoke():

// dispatch to single entity
Damage damageEvent = new Damage(source, amount, causeIndex);
store.invoke(targetRef, damageEvent);

// check if cancelled
if (damageEvent.isCancelled()) {
    return;
}

To listen to ECS events, create an EntityEventSystem or WorldEventSystem and register it on the store. The getQuery() method on EntityEventSystem uses the same query system described above to filter which entities receive the event.

See ECS Events for the full guide on listening, dispatching, query filtering, and cancellation.