Advanced Runtime Integration

Insert custom Artemis systems into Pixscape's frame lifecycle or replace final render submission.

Most games only need the normal Runtime APIs. Use these supported expert hooks when you need to insert custom Artemis systems into Pixscape’s frame lifecycle or replace the final render submission step.

Start with the current engine constructor:

PixscapeEngine engine = new PixscapeEngine();

Pre-render systems

Pre-render custom systems run after Pixscape has synchronized its normal Runtime state but before draw-list construction, sorting, Spatial composition, frame-queue extraction, and submission.

engine.setPreRenderSystemCustomizer(builder -> {
    builder.with(new MyRenderExtractionSystem());
});

This is an advanced render-integration phase, not a general gameplay-update-before-rendering hook. Mutating an ordinary authored component here does not rerun Pixscape’s earlier synchronization systems and must not be assumed to update every derived structure in the same frame.

Post-render systems

Post-render custom systems run after Pixscape has submitted the current frame and flushed dirty state, but before the synchronous Artemis World.process() call returns.

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

This phase suits diagnostics, picking, gizmos, overlays, application integration, and state changes intended for a later frame. It cannot alter the frame Pixscape has already submitted.

setConfigurationCustomizer(...) remains a compatibility alias for setPostRenderSystemCustomizer(...). The most recent call to either method replaces the same post-render callback; use the named post-render method in new code.

One system instance per Runtime World

Artemis systems belong to exactly one World. Each customizer callback must add fresh system instances whenever Pixscape builds a scene World; never reuse the same BaseSystem instance across scene changes.

Configuring a callback does not inject systems into an already-built World. It applies to the next applicable scene World build. The lightweight project bootstrap World created by loadProject(...) does not invoke application customizers.

Custom systems execute synchronously on the thread calling render(), normally the LibGDX render thread. These hooks do not add thread-safety.

Replace final render submission

setRenderSubmitSystemSupplier(...) replaces Pixscape’s final GPU submission system while keeping earlier Runtime synchronization, culling, draw-list construction, sorting, Spatial composition, and frame-queue extraction.

engine.setRenderSubmitSystemSupplier(MyRenderSubmitSystem::new);

The supplier must return a fresh, non-null compatible system for each Runtime World. That system becomes responsible for submitting the frame: Pixscape does not also run its normal RenderSubmitSystem. It must manage its own GPU and batch lifecycle without disposing borrowed Pixscape-owned queues, cameras, batches, metrics, or layer state.

Changing the supplier affects future World builds, not the current World. Pass null to restore Pixscape’s default submit system for subsequent builds.

For other engine setup, see Core Module Configuration and Scene Loading. Shared AssetManager configuration is covered by Assets.