Getting Started

Set up Pixscape Runtime, bootstrap a desktop application, load a project, and run your first scene.

On this page

• Requirements
• Dependency setup
• What Pixscape Runtime already brings transitively
• Minimal desktop bootstrap
• Typical startup flow
• Basic startup
• Adding an extra system
• Main loop
• Resize and cleanup
• Minimal complete example
• Notes
• Quick reference

Pixscape Runtime lets you bootstrap a project with very little setup.

This guide covers:

• dependency setup
• desktop bootstrap
• engine initialization
• loading a project and a scene
• the main update/render loop

Requirements

• Java 21 recommended
• Gradle 9.4.0 used in the runtime repository

Pixscape Runtime is currently published as:

games.pixscape:pixscape-runtime:0.1.0

Dependency setup

For a basic Java / LibGDX desktop project, add Pixscape Runtime plus the desktop backend dependencies.

Gradle

dependencies {
    implementation "games.pixscape:pixscape-runtime:0.1.0"

    implementation "com.badlogicgames.gdx:gdx-backend-lwjgl3:1.14.0"
    runtimeOnly "com.badlogicgames.gdx:gdx-platform:1.14.0:natives-desktop"
    runtimeOnly "com.badlogicgames.gdx:gdx-box2d-platform:1.14.0:natives-desktop"
}

Gradle Kotlin DSL

dependencies {
    implementation("games.pixscape:pixscape-runtime:0.1.0")

    implementation("com.badlogicgames.gdx:gdx-backend-lwjgl3:1.14.0")
    runtimeOnly("com.badlogicgames.gdx:gdx-platform:1.14.0:natives-desktop")
    runtimeOnly("com.badlogicgames.gdx:gdx-box2d-platform:1.14.0:natives-desktop")
}

Maven

<dependencies>
    <dependency>
        <groupId>games.pixscape</groupId>
        <artifactId>pixscape-runtime</artifactId>
        <version>0.1.0</version>
    </dependency>

    <dependency>
        <groupId>com.badlogicgames.gdx</groupId>
        <artifactId>gdx-backend-lwjgl3</artifactId>
        <version>1.14.0</version>
    </dependency>

    <dependency>
        <groupId>com.badlogicgames.gdx</groupId>
        <artifactId>gdx-platform</artifactId>
        <version>1.14.0</version>
        <classifier>natives-desktop</classifier>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>com.badlogicgames.gdx</groupId>
        <artifactId>gdx-box2d-platform</artifactId>
        <version>1.14.0</version>
        <classifier>natives-desktop</classifier>
        <scope>runtime</scope>
    </dependency>
</dependencies>

What Pixscape Runtime already brings transitively

pixscape-runtime already exposes the runtime-side core dependencies, including:

• gdx
• gdx-ai
• artemis-odb
• artemis-odb-serializer-json-libgdx
• gdx-box2d
• fastutil

That means you normally only need to add the desktop backend and the desktop natives on the application side.

Minimal desktop bootstrap

If you are starting with a LibGDX desktop launcher, these are the usual imports:

import com.badlogic.gdx.backends.lwjgl3.Lwjgl3Application;
import com.badlogic.gdx.backends.lwjgl3.Lwjgl3ApplicationConfiguration;

A minimal launcher looks like this:

public final class DesktopLauncher {
    public static void main(String[] args) {
        Lwjgl3ApplicationConfiguration config = new Lwjgl3ApplicationConfiguration();
        config.setTitle("My Pixscape Game");
        config.setWindowedMode(1280, 720);

        new Lwjgl3Application(new MyGame(), config);
    }
}

Typical startup flow

A typical Pixscape startup flow is:

1. create a camera
2. optionally register extra systems
3. create the engine
4. load the project
5. load a scene
6. run update and render

Basic startup

ProjectConfig cfg = ProjectConfig.getInstance();

OrthographicCamera worldCamera = new OrthographicCamera();

PixscapeEngine engine = new PixscapeEngine()
        .setWorldCamera(worldCamera);

engine.loadProject(userRootDir);
engine.loadScene(cfg.getCurrentSceneName());

This is the minimum structure: create a camera, configure the engine, load the project, then load the scene.

Adding an extra system

You can extend the runtime during boot without changing the core engine setup.

@Override
public void create() {
    ProjectConfig cfg = ProjectConfig.getInstance();

    OrthographicCamera worldCamera = new OrthographicCamera();

    PhysicsMouseDragSystem dragSystem = new PhysicsMouseDragSystem(worldCamera);
    dragSystem.setMaxForce(2000f);
    dragSystem.setFrequencyHz(5f);
    dragSystem.setDampingRatio(0.7f);
    dragSystem.setGrabRadiusMeters(0.25f);

    engine = new PixscapeEngine()
            .setWorldCamera(worldCamera)
            .setConfigurationCustomizer(builder -> builder.with(dragSystem));

    engine.loadProject(userRootDir);
    engine.loadScene(cfg.getCurrentSceneName());
}

Main loop

@Override
public void render() {
    float dt = Gdx.graphics.getDeltaTime();

    Gdx.gl.glClearColor(0f, 0f, 0f, 1f);
    Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT);

    engine.update(dt);
    engine.render();
}

Resize and cleanup

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

@Override
public void dispose() {
    if (engine != null) {
        engine.dispose();
        engine = null;
    }
}

Minimal complete example

public final class MyGame extends ApplicationAdapter {

    private final FileHandle projectDir;
    private PixscapeEngine engine;

    public MyGame(FileHandle projectDir) {
        this.projectDir = projectDir;
    }

    @Override
    public void create() {
        OrthographicCamera camera = new OrthographicCamera();

        engine = new PixscapeEngine()
                .setWorldCamera(camera);

        engine.loadProject(projectDir);
        engine.loadScene("MainScene");
    }

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

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

    @Override
    public void dispose() {
        if (engine != null) {
            engine.dispose();
            engine = null;
        }
    }
}

Notes

The first public developer-facing API layer is currently being shaped.

For now, this Getting Started guide focuses on the essentials:

• dependency setup
• desktop bootstrap
• a minimal starting point for integration

Quick reference

Gradle

implementation "games.pixscape:pixscape-runtime:0.1.0"

Maven

<dependency>
    <groupId>games.pixscape</groupId>
    <artifactId>pixscape-runtime</artifactId>
    <version>0.1.0</version>
</dependency>