Runtime Examples

Query helpers, registries, physics, rendering state, and diagnostics.

Prerequisites

These examples assume you already booted the runtime:

OrthographicCamera camera = new OrthographicCamera();

PixscapeEngine engine = new PixscapeEngine()
        .setWorldCamera(camera);

engine.loadProject(projectRoot);
engine.loadScene("MainScene");

Find an entity by stable id

Use this when you already know a stable id and want the matching entity.

long stableId = 42L;

int entityId = engine.findEntityByStableId(stableId);
if (entityId != -1) {
    System.out.println("Found entity: " + entityId);
}

Single-result helpers return -1 when nothing is found.

Find the first entity by name

Use this when you expect a single named entity or only care about the first match.

int player = engine.firstEntityByName("Player");
if (player != -1) {
    System.out.println("First Player entity: " + player);
}

Find all entities by name

Use this when multiple entities may share the same name.

IntBag enemies = engine.findEntitiesByName("Enemy");

int[] data = enemies.getData();
for (int i = 0; i < enemies.size(); i++) {
    int entityId = data[i];
    System.out.println("Enemy entity: " + entityId);
}

Find the first entity by tag

Use this when a tag identifies a main gameplay object such as player, camera-target, or boss.

int player = engine.firstEntityByTag("player");
if (player != -1) {
    System.out.println("Player entity: " + player);
}

Find all entities by tag

Use this when many entities share the same gameplay tag.

IntBag pickups = engine.findEntitiesByTag("pickup");

int[] data = pickups.getData();
for (int i = 0; i < pickups.size(); i++) {
    int entityId = data[i];
    System.out.println("Pickup entity: " + entityId);
}

Access the shader registry

Use the shader registry to inspect shader metadata and default uniforms. This is useful when building custom shader editors, default parameter UIs, or runtime debugging tools.

ShaderRegistry shaders = engine.getShaderRegistry();

ObjectFloatMap<String> defaults = ShaderRegistry.getDefaultUniforms("water");
if (defaults != null) {
    for (ObjectFloatMap.Entry<String> e : defaults) {
        System.out.println(e.key + " = " + e.value);
    }
}

Access the Box2D world service

Use this when you need access to the active physics world service.

Box2dWorldService box2d = engine.getBox2dWorldService();
if (box2d != null && box2d.world != null) {
    System.out.println("Physics world is available");
}

Typical use cases:

advanced physics queries
custom debug tools
low-level physics integrations
Access the Box2D sync system

Use this when you need the runtime system that synchronizes Pixscape and Box2D state.

Box2dSyncSystem sync = engine.getBox2dSyncSystem();
if (sync != null) {
    System.out.println("Box2D sync system enabled: " + sync.isEnabled());
}

This is mainly useful for runtime tooling and advanced integration work.

Access the atlas runtime service

Use this when you need runtime atlas access, cached regions, or bundle-related tooling.

AtlasRuntimeService atlas = engine.getAtlasRuntimeService();
if (atlas != null) {
    System.out.println("Atlas runtime service is ready");
}

Typical use cases:

custom asset inspection
atlas debugging
texture-array bundle related tooling

Access render state

Use this when you need low-level runtime render data.

RenderStateSOA renderState = engine.getRenderState();
System.out.println("Render state capacity: " + renderState.capacity());

This is an advanced API intended for diagnostics, profiling, and engine-level tooling.

Access layer state

Use this when you need runtime information about scene layers.

LayerStateSOA layerState = engine.getLayerState();
System.out.println("Layer state capacity: " + layerState.capacity());

Typical uses:

custom debug overlays
layer inspection tools
runtime diagnostics

Access the draw list

Use this when you want to inspect the generated draw submission data.

DrawList drawList = engine.getDrawList();
System.out.println("Draw list size: " + drawList.size());

This is mainly useful for rendering diagnostics and internal tooling.

Access the metrics batch

Use this when you need batch-level metrics or advanced rendering instrumentation.

MetricsBatch batch = engine.getMetricsBatch();
if (batch != null) {
    System.out.println("Metrics batch is active");
}

Access render stats

Use this when you want aggregated render metrics. This is useful for profiling, debug panels, and performance tracking.

RenderStats stats = engine.getRenderStats();
if (stats != null) {
    System.out.println("Render stats available");
}

Access the render stats sink.

Use this when you want sampled or delayed render-stat reporting.

RenderStatsSink sink = engine.getRenderStatsSink();
if (sink != null) {
    System.out.println("Render stats sink available");
}

Combine query helpers with a component mapper

A common runtime pattern is:

find an entity with a helper
fetch a mapper

work directly with ECS data

int player = engine.firstEntityByTag("player");
if (player != -1) {
    ComponentMapper<TransformComponent> mTransform = engine.mapper(TransformComponent.class);
    TransformComponent transform = mTransform.get(player);

    System.out.println("Player position: " + transform.x + ", " + transform.y);
}

When should you use these APIs?

Use the query helpers often:

findEntityByStableId(…)
firstEntityByName(…)
findEntitiesByName(…)
firstEntityByTag(…)
findEntitiesByTag(…)

Use the advanced runtime accessors when needed for:

custom tooling
diagnostics
profiling
debugging
engine-level integrations

For most gameplay code, the usual pattern is still:

find entities with helper APIs
get mappers or systems from the engine
work directly with Artemis components and systems