Expert ECS Access

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

Pixscape uses an Entity Component System (ECS) for its game and scene state. In an ECS, entities are composed from data components and systems process those components. Pixscape uses Artemis-ODB for this ECS.

Most games do not need direct ECS access. api.ecs() is the low-level escape hatch for integrations that genuinely need custom systems, direct component access, advanced tooling, specialized diagnostics, or performance-sensitive coordination. For the reason Pixscape separates ECS state from rendering data, see Architecture & Performance.

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 send the corresponding change notification for you:

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.

Notify Pixscape after direct mutation

Pixscape keeps some Runtime and rendering data derived from ECS state. Derived data is data Pixscape computes from authored or game state for another purpose, such as rendering or physics.

If application code bypasses the normal Runtime APIs and modifies a component directly, Pixscape cannot automatically know which derived data needs to be refreshed. The code must therefore send the corresponding change notification. These notifications form Pixscape’s dirty and invalidation rules: dirty tracking identifies what changed, while invalidation marks computed data as no longer valid so it can be rebuilt or refreshed.

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);

GeometryDirty.POSITION tells Pixscape that position-derived rendering data for this entity must be refreshed. Without the notification, the ECS position can change while synchronized rendering or physics data remains stale.

Game Object hierarchy semantics still apply through raw ECS access: a member’s transform data is local to its parent, not a resolved world transform. Direct component mutation also bypasses the hierarchy and Physics safeguards enforced by high-level facades, so use it only when those contracts are understood. See Game Objects API.

ECS state and rendering storage

api.ecs() is the supported low-level surface for game and scene state; it is not access to every representation Pixscape stores internally. Pixscape prepares some rendering data separately in a compact Structure of Arrays (SOA) layout because rendering and gameplay have different data needs.

That SOA rendering layout is not a normal gameplay API. Because Pixscape computes, rebuilds, and manages this derived storage, application code must not modify it 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 and send their dirty or invalidation notifications.
• Do not mutate Runtime-owned derived or rendering storage directly.