libgdx-headless-backend

libGDX Headless Backend

Reference for running libGDX without a display, audio, or input — for servers, CI/testing, procedural generation, and headless simulation. Lives in the gdx-backend-headless module.

Setup

import com.badlogic.gdx.backends.headless.HeadlessApplication;
import com.badlogic.gdx.backends.headless.HeadlessApplicationConfiguration;

public class ServerLauncher {
    public static void main(String[] args) {
        HeadlessApplicationConfiguration config = new HeadlessApplicationConfiguration();
        config.updatesPerSecond = 20;  // render() called 20 times/sec
        new HeadlessApplication(new MyServerListener(), config);
    }
}

Dependency (Gradle):

implementation "com.badlogicgames.gdx:gdx-backend-headless:$gdxVersion"
implementation "com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop"

HeadlessApplicationConfiguration

The only important field is updatesPerSecond — an int controlling how often render() is called.

updatesPerSecond value	Behavior	Use case
20	render() called 20 times/sec	Game server at 20 tick rate
60 (default)	render() called 60 times/sec	Wastes CPU on a server — always set explicitly
0	Never sleep between calls (run as fast as possible)	Batch processing, benchmarking
Negative (e.g. -1)	render() is NOT called at all	One-shot tasks that do all work in create()

CRITICAL — use updatesPerSecond, not the old float field:

// ✅ CORRECT — updatesPerSecond is an int
config.updatesPerSecond = 20;

// ❌ WRONG — renderInterval was removed; this will not compile on 1.9.14+
// config.renderInterval = 1 / 20f;   // DO NOT USE

For servers: Always set updatesPerSecond to match your desired tick rate. The default (60) runs at 60fps which wastes CPU on a headless server.

For one-shot tasks (generate data then exit): Do all work in create() and call Gdx.app.exit(). Set updatesPerSecond = -1 so render() is never called, or leave it at default — if your create() calls exit(), it won't matter.