Expert ECS Access

Use api.ecs() for supported low-level Artemis integration when the normal Runtime APIs are not enough.

api.ecs() is Pixscape’s low-level Artemis escape hatch. Use it for custom ECS systems, direct component access, advanced tooling, specialized diagnostics, or performance-sensitive integration—not because every advanced game eventually needs it.

Entry point

ECSAPI ecs = api.ecs();

The supported expert operations are:

• world() for the current Artemis World
• mapper(ComponentType.class) for direct component access
• system(SystemType.class) for Runtime system lookup
• identityRegistry() and tagRegistry() for low-level identity bridging

For ordinary entity lookup and gameplay mutation, prefer api.entities() and EntityRef facades.

Reacquire objects after scene changes

The Artemis World, component mappers, systems, registries, and related Runtime objects returned here are borrowed from the current Runtime World. They are not thread-safe and must be reacquired after a scene or World replacement. Do not keep them in permanent global caches.

Use ECS access on the same thread that drives the Runtime—normally the LibGDX render thread.

Prefer facades before raw mutation

Facades update authored components and notify the Runtime of the corresponding change:

EntityRef entity = api.entities().requireTag("player");
entity.transform().moveBy(10f, 0f);

Prefer SpriteFacade for sprite changes, AnimationFacade for animation, ParticleFacade for particles, RenderOrderFacade for layer and z-order changes, PhysicsAPI for normal physics access, and the Tiled facades for tile edits.

If you bypass those APIs and modify components directly, you must follow the component’s dirty or invalidation contract. For example:

ComponentMapper<TransformComponent> transforms =
        api.ecs().mapper(TransformComponent.class);

TransformComponent transform = transforms.get(entityId);
transform.x += 10f;

DirtyTrackerSystem dirty =
        api.ecs().system(DirtyTrackerSystem.class);
dirty.geometry(entityId, GeometryDirty.POSITION);

Without the matching notification, authored ECS data can change while synchronized render, physics, or Tiled data remains stale. Do not mutate Runtime-owned derived render storage directly.

Systems and registries

System lookup supports integrations that deliberately coordinate with a documented Runtime system:

DirtyTrackerSystem dirty = ecs.system(DirtyTrackerSystem.class);
IdentityRegistry identities = ecs.identityRegistry();
TagRegistry tags = ecs.tagRegistry();

Normal collision listeners, ray casts, AABB queries, coordinate conversion, and borrowed Box2D access belong to api.physics(), not to an ECS system lookup.

Supported expert surface

ECSAPI is a supported expert extension surface, but Java public does not automatically mean “supported extension point.” Prefer the expert APIs and systems documented by Pixscape instead of coupling gameplay code to arbitrary Runtime internals.

Keep these rules in mind:

• Prefer focused Runtime APIs when they cover the job.
• Reacquire borrowed ECS objects after a scene or World replacement.
• Mutate components directly only when you understand their dirty and invalidation rules.
• Do not mutate Runtime-owned derived or render storage directly.