Runtime Overview

Use Pixscape Runtime's focused Java APIs and entity facades to load and control exported scenes in LibGDX games.

Pixscape Runtime loads scenes exported by Studio and exposes them to Java gameplay code in a LibGDX application. PixscapeAPI is the main entry point:

PixscapeAPI api = engine.api();

It provides focused APIs for entities, assets, sprites, animations, particles, prefabs, Tiled maps, Spatial ordering, physics, and expert ECS access.

Create gameplay content with focused APIs

Use the API for the kind of content you want to create or inspect:

• api.assets() for resources exported into the current scene atlas
• api.sprites() and api.animations() for visual entities
• api.particles() for prepared particle effects
• api.prefabs() for exported prefab fragments

SpriteRef coin = api.sprites().spawn("coin", 120f, 64f);
EntityRef enemy = api.prefabs().requireFirst("Enemy", 320f, 80f);

See Assets, Sprites, Animations, Particles, and Prefabs for their complete contracts.

Control an existing entity with facades

Find an entity through api.entities(), then use the facades exposed by its EntityRef:

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

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

Common gameplay operations therefore do not require direct Artemis component access. Use persistent stableId values for saved or tool-visible identity; runtime entityId values are short-lived ECS identifiers.

See Entities and EntityRef and Entity Facades.

Work with Tiled, Spatial, and physics

• api.tiled() gives entity-, stable-ID-, or layer-index-based access to exported Tiled layers.
• api.spatial() controls whether exported visual layers participate in 2.5D front/behind ordering.
• api.physics() exposes normal physics status, coordinate conversion, bodies, and borrowed Box2D access.

if (api.physics().isRunning()) {
    com.badlogic.gdx.physics.box2d.World world = api.physics().box2dWorld();
}

See Tiled Maps, Spatial API, and Physics and Collisions.

Prepare the scene before gameplay

Load the scene before gameplay starts. If gameplay will create resources that are not already used by the scene, add them to Runtime Availability so Studio prepares and exports them with that scene.

Drop to ECS only when needed

Pixscape still gives experienced Artemis users direct ECS access through api.ecs() when the focused APIs are not enough. It is useful for custom Artemis systems, specialized component access, tooling, diagnostics, and advanced integration.

Direct ECS mutation also makes your code responsible for the corresponding dirty and invalidation contracts. It is not the normal route to physics, animation, rendering, or Tiled operations. See Expert ECS Access when you genuinely need that lower-level control.

Start with the focused Runtime APIs and EntityRef facades. Drop to ECS only when your game genuinely needs lower-level Artemis access.