Pixscape logo Pixscape
Pixscape is currently in public pre-release.

The runtime and documentation are already usable, but some APIs, workflows, and editor behavior may still evolve before a stable 1.0 release.

Pixscape for LibGDX developers

Understand what stays the same in LibGDX, how Pixscape fits into the render loop, and how to integrate existing libraries.

On this page

Pixscape is built on LibGDX and runs inside a normal LibGDX application. Gameplay remains Java, LibGDX APIs remain available, and ordinary LibGDX code can run around the visual world managed by Pixscape Runtime.

For the reasoning behind Pixscape’s rendering model, start with How Pixscape Works. This page focuses on how Pixscape fits into a LibGDX application and workflow.

What stays LibGDX?

Your application still uses the normal LibGDX lifecycle and can use LibGDX input, files, audio, networking, math utilities, and other APIs. Java and LibGDX libraries that do not depend on Pixscape’s managed world can also be used normally.

Pixscape adds a managed visual 2D and 2.5D world. It does not replace LibGDX as the application framework underneath it. The exact integration for a rendering library depends on where its output needs to appear.

How does Pixscape fit into my render loop?

Update and render the Pixscape world as part of the normal LibGDX render loop. Other rendering can run before or after that world pass, depending on the intended visual result.

For example, a Scene2D stage can render afterward:

engine.update(delta);
engine.render();

stage.act(delta);
stage.draw();

Once engine.render() returns, the application is regular LibGDX code again.

An independent library renderer can run in another pass in the same way:

engine.render();

spriteBatch.begin();
library.render(spriteBatch);
spriteBatch.end();

Rendering it after Pixscape places its output after the Pixscape world pass. Render it before Pixscape when it should appear behind that world instead.

Can I still use LibGDX libraries?

The practical question is: does the library need to participate inside Pixscape world ordering?

Rendering outside Pixscape world ordering

If the answer is no, use the library normally in a separate LibGDX pass. Scene2D, HUDs, overlays, debug rendering, and many third-party renderers naturally fit here.

Content rendered in that pass does not participate in Pixscape layerIndex, zIndex, or Spatial ordering. It appears before or after the Pixscape world as a whole.

Reuse Pixscape assets as LibGDX TextureRegion objects

When a LibGDX library accepts a TextureRegion, it does not need Pixscape-specific texture handling. Resolve the Pixscape asset from the current scene atlas through the Runtime Assets API, then pass the regular LibGDX region to your code or a third-party library:

TextureRegion region =
    engine.api().assets().region("player").region();

spriteBatch.begin();
spriteBatch.draw(region, x, y);
spriteBatch.end();

You can also look up the asset by ID with engine.api().assets().region(assetId). The asset must be available in the current scene atlas, either as scene content or through Runtime Availability. Assets included through Runtime Availability can be resolved this way too, then used directly with SpriteBatch, Scene2D, another Batch implementation, or custom rendering.

AssetRegionRef#region() returns a defensive TextureRegion snapshot, so you can use and modify the returned region freely without changing Pixscape’s indexed atlas binding. Its underlying Texture remains owned by Pixscape Runtime; do not call dispose() on it.

This makes Pixscape-managed visual assets directly reusable by normal LibGDX APIs, while the draw call still runs in your separate pass. It is not inserted into Pixscape layerIndex, zIndex, or Spatial ordering.

Rendering that must participate in Pixscape world ordering

If a library’s content must appear between Pixscape world objects according to layerIndex, zIndex, or Spatial ordering, simply forwarding arbitrary batch.draw() calls into the managed world is not currently supported.

That case may require a custom Runtime system or expert integration. See Advanced Runtime Integration for the supported extension points.

How far can I customize the Runtime?

Custom systems

You can add custom Artemis systems when the normal Runtime APIs do not provide the behavior you need:

engine.setPostRenderSystemCustomizer(builder -> {
    builder.with(new MyPickingSystem());
});

See Advanced Runtime Integration for the available phases and their intended uses.

Expert ECS access

For specialized integrations, api.ecs() exposes the low-level Artemis entity-component-system (ECS) state:

ECSAPI ecs = api.ecs();
World world = ecs.world();

This is an expert escape hatch, not the normal gameplay path. Direct changes must follow the Runtime synchronization rules documented in Expert ECS Access. For more background, see Architecture & Performance.

How do I add Pixscape to a LibGDX project?

New projects

Use gdx-liftoff and select Pixscape Runtime:

gdx-liftoff
→ choose "Pixscape Runtime"
→ select targets
→ generate project
→ enable GL30 for each selected target
→ use Pixscape Studio for scene/content authoring
→ run

LiftOff configures the Runtime integration, but GL30 still needs to be enabled for each target. Follow the setup for Desktop / LWJGL3, Android, or HTML5 / WebGL2.

Existing projects

Pixscape Runtime can also be added as a dependency to an existing LibGDX project. Enable GL30, then follow Runtime Compatibility & Setup, Core Module, and Scene Loading without duplicating those steps here.

Where to go next