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.

Getting Started

Create a Pixscape scene, export it to a LibGDX project, and run it on Desktop.

On this page

This guide takes you through the shortest path from an empty folder to a Pixscape scene running in a LibGDX Desktop application.

If you would rather explore a working project first, follow Try Pixscape in 10 Minutes. Come back here when you are ready to create your own project.

What you will set up

Pixscape has two parts that work together:

  • Pixscape Studio is where you create and edit scenes.
  • Pixscape Runtime loads the exported scenes in your LibGDX game.

You will keep the editable Studio project separate from the generated runtime files. Studio exports those runtime files into your LibGDX assets folder.

Before you start

Pixscape currently targets:

  • Desktop (LWJGL3 / OpenGL 3)
  • Android (OpenGL ES 3)
  • HTML5 (WebGL2 / GWT)

Start with Desktop even if you ultimately plan to ship on Android or the web. It gives you the quickest feedback loop and confirms that the shared core module is configured correctly.

Download the current Studio release:

Download Pixscape Studio Free 0.2.2

This guide uses:

  • Pixscape Studio Free 0.2.2
  • Pixscape Runtime 0.1.9

See Runtime Compatibility & Setup if you are upgrading an existing project or need the complete dependency and Java compatibility notes.

1. Create a LibGDX project

Create a LibGDX project with gdx-liftoff and select Pixscape Runtime.

For the first run, enable these modules:

  • core
  • lwjgl3

You can add or configure Android and HTML after the Desktop version works.

2. Enable GL30

LiftOff configures the Pixscape Runtime integration. Pixscape still requires GL30, so enable it for each selected target. For this Desktop guide, follow Desktop / LWJGL3 Setup.

3. Create a Studio project

Open Pixscape Studio and choose File > New.

The new-project dialog asks for two different locations:

  • Project Directory: a dedicated folder for the editable Studio source project.
  • Export Directory: the assets folder in your LibGDX project.

For example:

my-pixscape-project/       <- editable Studio project
my-game/
  assets/                  <- choose this as Export Directory
  core/
  lwjgl3/

Do not use the export directory as the Studio project directory. Exported files are generated output and can be replaced the next time Studio saves or exports the project.

For a detailed explanation of every field, see Studio Project Setup.

4. Create and export a scene

Give the default scene a simple name such as main, add an asset or sprite, and save the Studio project.

Studio writes the runtime-ready project under your selected assets directory:

my-game/assets/pixscape-project/

Do not create or hand-edit pixscape-project. Make changes in the Studio project and export again.

Before continuing, confirm that this file exists:

my-game/assets/pixscape-project/project.json

If it does not, open File > Project settings and check that Export Directory points to the LibGDX assets folder.

5. Load the exported scene

In your core module, create the Pixscape engine, load the exported project, and load the scene. Pass null to load the current scene selected in Studio:

public class Main extends ApplicationAdapter {

    private PixscapeEngine engine;

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

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

        engine.loadProject(projectJson.parent().parent());
        engine.loadScene(null);
    }

    @Override
    public void render() {
        engine.update(Gdx.graphics.getDeltaTime());
        engine.render();
    }

    @Override
    public void resize(int width, int height) {
        engine.resize(width, height);
    }

    @Override
    public void dispose() {
        engine.dispose();
    }
}

Add the imports suggested by your IDE from LibGDX and Pixscape Runtime. If your generated application class has a different name, keep that class name and replace its lifecycle methods with the same setup.

6. Run the Desktop application

From the LibGDX project root, run:

./gradlew lwjgl3:run

On Windows:

.\gradlew.bat lwjgl3:run

Your Studio scene should appear in the LibGDX window. That confirms the complete authoring loop: edit in Studio, export to assets, and run through Pixscape Runtime.

Troubleshooting the first run

project.json cannot be found

Confirm that the LibGDX project contains assets/pixscape-project/project.json. If the file is elsewhere, correct the Studio Export Directory and export again.

The application starts but the wrong scene loads

engine.loadScene(null) loads the current scene saved by Studio. Select and save the intended scene, or pass its exact name to loadScene("scene-name").

Desktop works, but Android or HTML does not

Each target needs additional platform configuration. Complete the matching guide before running that target.

Continue from here