Entities and EntityRef

Find existing Runtime entities and control them safely through EntityRef.

Use api.entities() when you want to find an entity that already exists and control it from your game code.

EntityRef player = api.entities().requireTag("player");

player.transform().moveBy(4f, 0f);
player.animation().play("run");

The usual workflow is simple: find an entity, keep its EntityRef, and use the entity’s facades.

What EntityRef provides

EntityRef is the normal handle for an existing Runtime entity. It lets you check the entity, remove it, and reach its common capabilities without using Artemis directly.

The current entity facades are:

• transform()
• sprite()
• animation()
• particles()
• shader()
• light()
• spatial()
• renderOrder()

See Entity Facades for practical examples.

ecs() is a separate advanced escape hatch. Ordinary gameplay should normally use the dedicated facades first.

Finding an entity

Use a strict lookup when your game expects the entity to exist:

EntityRef player = api.entities().requireTag("player");
EntityRef enemy = api.entities().requireName("Enemy");
EntityRef savedEntity = api.entities().requireStableId(42);
EntityRef runtimeEntity = api.entities().requireEntityId(7);

require... throws if the entity cannot be found when you call it.

Use a tolerant lookup when a missing entity is an expected result:

EntityRef target = api.entities().ofStableId(42);

if (target.exists()) {
    target.transform().moveBy(8f, 0f);
}

ofStableId(...) and ofEntityId(...) always return an EntityRef. When no matching entity exists, exists() is false and the reference can be handled safely.

stableId and entityId

Both ID types are Java int values, but they serve different purposes.

stableId

Use stableId when you need an identity that belongs to the Pixscape scene/runtime model and may need to be found again.

int stableId = player.stableId();
EntityRef samePlayer = api.entities().requireStableId(stableId);

entityId

entityId is the entity’s current ECS/runtime ID. It is useful when integrating with lower-level Artemis code, but it may be short-lived and can eventually be recycled.

int entityId = player.entityId();

A stable ID does not make an EntityRef permanent. The reference still represents the particular entity it originally found.

Converting IDs

Most gameplay code can keep an EntityRef and avoid manual ID conversion. When integration code needs the bridge, EntitiesAPI provides it:

EntitiesAPI entities = api.entities();

int stableId = entities.ensureStableId(player.entityId());
int entityId = entities.entityIdOf(stableId);
int sameStableId = entities.stableIdOf(entityId);

entityIdOf(...) returns -1 when the stable ID is missing. findEntityId(...) lets you choose a different fallback. You can also probe with existsStableId(...) and existsEntityId(...).

If the entity is removed

An EntityRef stays attached to the particular entity it originally resolved. If that entity is removed, or a new scene replaces the Runtime World:

• exists() returns false
• stableId() returns -1
• entityId() still returns the captured runtime ID for diagnostics
• facades obtained from the reference remain attached to the original entity
• facade changes do nothing, and facade queries return their documented safe defaults

An EntityRef never jumps to another entity just because Artemis reuses the same numeric ID.

You do not need to constantly look up a live reference again during normal gameplay. After loading a different scene, look up the entities you need from that new scene.

Removing an entity

The simplest removal path is:

player.remove();

You can also remove through EntitiesAPI when you have a reference or an ID:

api.entities().destroy(player);

When all you have is an ID, use destroyEntityId(...) or destroyStableId(...).

Removal is scheduled and becomes visible through normal Runtime processing, such as the next rendered frame. Pixscape does not force an immediate World process just because one of these methods was called. Calling remove() on an inactive reference has no effect.

Direct ECS access

If a custom system or component really needs direct Artemis access, use api.ecs() or the escape hatch exposed by entity.ecs().

Most gameplay code can stay with EntityRef and its facades. See Expert ECS Access when lower-level integration is necessary.