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 it from the normal render loop:

private PixscapeEngine engine;
private SceneLoadHandle sceneLoad;

@Override
public void create() {
    engine = new PixscapeEngine();

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

    engine.loadProject(projectJson.parent().parent());
    sceneLoad = engine.beginLoadScene("iso2");
}

@Override
public void render() {
    if (!sceneLoad.isReady() && !sceneLoad.isFailed()) {
        sceneLoad.update();
    }

    if (sceneLoad.isFailed()) {
        Throwable failure = sceneLoad.failure();
        // Show the error, retry, or leave the loading screen.
        return;
    }

    if (!sceneLoad.isReady()) {
        float progress = sceneLoad.progress();
        SceneLoadPhase phase = sceneLoad.phase();
        // Draw your loading screen with progress and phase.
        return;
    }

    engine.update(Gdx.graphics.getDeltaTime());
    engine.render();
}

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, prefabs, 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.