Scene Loading

Load Pixscape scenes immediately or progressively, including on HTML.

Load the Pixscape project once, then load the scene you want to play.

Load a scene directly

On platforms where blocking loading is appropriate, call loadScene(...) after loadProject(...):

PixscapeEngine engine = new PixscapeEngine();

FileHandle projectJson = Gdx.files.internal(
        PixscapeEngine.RUNTIME_DIR_NAME + "/project.json"
);

engine.loadProject(projectJson.parent().parent());
engine.loadScene("iso2");

When loadScene(...) returns successfully, the scene is active and ready to use.

Pass null to load the project’s current scene:

engine.loadScene(null);

Load a scene progressively

Progressive loading is useful when you want to show a loading screen, keep control of the application loop while a large scene loads, or wait for HTML resources that still need network delivery.

Start the load after loadProject(...), then advance its SceneLoadHandle from the normal render loop. A complete loading-screen flow appears in the final examples section.

Pixscape does not start a worker thread for this. Each call to update() advances the load from your application loop, normally the LibGDX render loop.

progress() returns a value from 0 to 1 that never moves backward during the load. You can use it for a loading bar.

Loading phases

phase() reports the current step:

What READY means

When the load reaches READY, the scene is active and the resources Pixscape knows it needs are ready to use.

Normal gameplay does not silently load new undeclared scene resources after READY. If gameplay will create or use a resource later, declare it in Runtime Availability before loading the scene. This commonly applies to particle effects, Game Objects, and sprites or animations used only from code.

Loading failures

isFailed() reports whether loading stopped because of an error. failure() returns the original error:

if (sceneLoad.isFailed()) {
    Throwable failure = sceneLoad.failure();
}

If loading fails before Pixscape starts replacing the scene, the current scene remains active. A later failure can leave the engine without an active scene. The exact failure remains available through failure().

Only one unfinished progressive scene load can be active at a time. Start the next load after the current one has either reached READY or failed.

Using your own AssetManager

If your game already uses a LibGDX AssetManager, Pixscape can share it:

AssetManager assets = new AssetManager();

PixscapeEngine engine = new PixscapeEngine()
        .setAssetManager(assets);

Configure the manager before loading the Pixscape project or a scene.

Your application owns the supplied manager. Pixscape uses it for the resources Pixscape loads, but does not globally clear or dispose it. Pixscape only releases the resource references it acquired as scenes and the engine are disposed. Dispose the manager from your application when it is no longer needed.

Sharing an AssetManager is optional. Without one, Pixscape creates and manages its own.

HTML and WebGL2

HTML cannot always wait synchronously for resources that still need network delivery. Use progressive loading in that situation and advance the handle from the render loop.

See HTML5 / WebGL2 Setup for the platform configuration.

Code examples

Show a splash screen while a scene loads

Advance one progressive load from the normal render loop while application UI displays its state.

private SceneLoadHandle sceneLoad;

private void loadScene(String sceneName) {
    sceneLoad = engine.beginLoadScene(sceneName);
}

void render() {
    if (sceneLoad != null && !sceneLoad.isReady()) {
        if (!sceneLoad.isFailed()) {
            // One bounded synchronous loading step on the render thread.
            sceneLoad.update();
        }

        if (sceneLoad.isFailed()) {
            // Application UI owns errors and retry choices.
            showLoadingError(sceneLoad.failure());
            return;
        }

        if (!sceneLoad.isReady()) {
            // Application UI owns the splash/loading screen.
            drawSplashScreen(sceneLoad.progress(), sceneLoad.phase());
            return;
        }
    }

    // READY already published the requested scene as active.
    engine.update(Gdx.graphics.getDeltaTime());
    engine.render();
}

loadScene(...), drawSplashScreen(...), and showLoadingError(...) are application code, not Pixscape Runtime methods.

Load the next scene when the level ends

Start the next progressive load when application gameplay detects level completion.

void onLevelCompleted() {
    loadScene("level-02");
}

onLevelCompleted() represents an application-owned event or condition, not a Pixscape event. Start this transition only after any earlier progressive load has reached READY or failed.

Load an authored exit destination

Read the destination scene name authored on an exit entity, then let application gameplay start the transition.

void onExitReached(EntityRef exit) {
    // nextScene is a read-only String authored on the exit entity.
    String nextScene = exit.properties()
            .getString("nextScene", null);

    if (nextScene != null) {
        loadScene(nextScene);
    }
}

An exit entity can store nextScene, such as "level-02", as an authored String custom property. The application decides when the exit has been reached.