Introduction

Start with Pixscape Runtime's focused APIs, work with individual entities, and use direct ECS access only for advanced integrations.

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

Start with the focused APIs for normal gameplay, use EntityRef facades when you have a specific entity, and drop to direct entity-component-system (ECS) access only for advanced integrations.

Focused Runtime APIs

• api.entities() finds existing scene entities.
• api.assets() resolves resources exported into the current scene atlas.
• api.sprites(), api.animations(), and api.particles() create visual entities.
• api.gameObjects() spawns reusable Game Object hierarchies.
• api.tiled() accesses Tiled Map entities by entity or stable identity.
• api.spatial() controls Universal Layer participation in Spatial actor ordering.
• api.physics() exposes scene Physics state and borrowed Box2D objects.

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

See Assets, Sprites, Animations, Particles, and Game Objects for normal creation workflows.

Control an existing entity

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

Use persistent stableId values for saved or tool-visible identity; runtime entityId values are short-lived ECS identifiers. See Entities and EntityRef.

Tiled, Spatial, and Physics

A Tiled Map is a first-class entity in a Universal Layer. Resolve it through api.tiled() with its entity ID or stable ID, then use TiledMapRef for Map properties, cells, Map Spatial Depth, and tile animation control.

api.spatial() controls whether Universal Layers participate as Spatial actor layers. api.physics() provides scene Physics status, coordinate conversion support, entity bodies, and borrowed access to the active Box2D world.

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.

Expert ECS access

Experienced Artemis users can access the active World through api.ecs(). Direct ECS changes must also invalidate the derived Runtime data affected by the change; the focused APIs handle that coordination automatically. See Expert ECS Access when a high-level API does not cover the integration.