Pixscape for LibGDX developers

Compare LibGDX and Pixscape rendering, integrate libraries, and set up Pixscape Runtime with gdx-liftoff.

1. How does rendering differ from LibGDX?

LibGDX

batch.begin();
batch.draw(background, ...);
batch.draw(player, ...);
batch.draw(foreground, ...);
batch.end();

In regular LibGDX rendering, draw order is mainly determined by the sequence of draw() calls.

Pixscape

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

player.renderOrder()
      .layerIndex(4)
      .zIndex(10);

engine.render();

In Pixscape, rendering order is scene data rather than draw-call sequence.

Renderables declare where they belong using properties such as layerIndex and zIndex. Pixscape can then sort, cull and optimize the complete render set before submission.

Arbitrary SpriteBatch.draw() calls are not directly interleaved inside Pixscape’s managed world ordering.

For rendering that does not need to participate in that ordering, regular LibGDX rendering can simply run before or after the Pixscape world pass. More specialized integrations are also possible through custom systems and expert ECS/SOA access.

2. Can I still use LibGDX libraries?

Yes. How you integrate them depends mostly on whether they need to participate in Pixscape world rendering.

Libraries that do not participate in Pixscape world rendering

Gameplay libraries, networking, math, utilities, data processing, AI libraries and similar code can generally be used normally.

Regular LibGDX rendering

A library that renders independently can run in a separate pass after Pixscape renders the world:

engine.render();

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

The same applies to Scene2D and HUD rendering:

engine.render();

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

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

This is a natural place for Scene2D, HUDs, overlays, debug rendering and third-party rendering that does not need to participate inside Pixscape’s world ordering.

Rendering performed in this pass does not participate in Pixscape layerIndex, zIndex or Spatial ordering.

Libraries that must participate inside the Pixscape world

A library that must participate directly in Pixscape world ordering cannot currently be integrated by simply forwarding its batch.draw() calls.

Advanced integration is possible through custom Artemis systems and expert access to Pixscape’s ECS/SOA state.

See Can I go lower level? below.

3. Can I add my own systems?

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

Pixscape Runtime is not sealed. You can add your own Artemis systems when the high-level Runtime API does not provide the behavior you need.

See Advanced Runtime Integration.

4. Can I go lower level?

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

Advanced integrations can work directly with Pixscape ECS/SOA state and bridge specialized content into normal Pixscape processing. Such integrations may participate in layerIndex / zIndex, ordering, culling, Spatial relationships, runtime synchronization and render submission.

This is an expert path. Direct mutation must respect Runtime dirty/invalidation rules.

See Expert ECS Access, Architecture & Performance and Advanced Runtime Integration.

5. How do I add Pixscape to a LibGDX project?

New projects

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

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

Existing projects

Pixscape Runtime can also be added to an existing LibGDX project as a dependency. Enable GL30, then see Runtime Compatibility & Setup, Core Module Configuration and Scene Loading.

6. Extensions and plugins

Custom Runtime systems are available today. A broader Runtime module and Studio plugin model is planned, but no public plugin API exists yet.

A Runtime module may eventually provide:

systems
APIs / services
assets
specialized processing

A Studio plugin may eventually provide:

dockable panels
importers
custom editors
authoring tools

For example, a particle integration could combine Runtime systems with a dedicated Studio editor.