Libgdx 1.12.0 LWJGL3 Migration: Dual‑Backend Support for Desktop Targets?

Answer to the Core Question

There is no officially supported Gradle configuration or Libgdx plugin that lets a single JAR contain both gdx-backend-lwjgl (LWJGL2) and gdx-backend-lwjgl3 (LWJGL3) without class‑path clashes. The two backends share package names (e.g. com.badlogic.gdx.backends.lwjgl) and their native libraries are incompatible, so the JVM will load the wrong classes or fail with UnsatisfiedLinkError if both are present.

Recommended Practical Approach

1. Split the project into three Gradle modules:
   • core – contains all shared Libgdx core code.
   • desktop-lwjgl – depends on gdx-backend-lwjgl and the legacy lwjgl natives.
   • desktop-lwjgl3 – depends on gdx-backend-lwjgl3 and the lwjgl3Natives configuration.
2. Gradle snippet for each desktop module:

   // desktop-lwjgl/build.gradle
   plugins { id 'java' }
   
   repositories { mavenCentral() }
   
   dependencies {
       implementation project(':core')
       implementation 'com.badlogicgames.gdx:gdx-backend-lwjgl:1.12.0'
       runtimeOnly 'com.badlogicgames.gdx:gdx-backend-lwjgl:natives-windows' // adjust for OS
   }
   
   application {
       mainClass = 'com.example.MyGame'
   }
   
   // desktop-lwjgl3/build.gradle
   plugins { id 'java' }
   
   repositories { mavenCentral() }
   
   dependencies {
       implementation project(':core')
       implementation 'com.badlogicgames.gdx:gdx-backend-lwjgl3:1.12.0'
       runtimeOnly 'com.badlogicgames.gdx:gdx-backend-lwjgl3:natives-windows' // adjust for OS
   }
   
   application {
       mainClass = 'com.example.MyGame'
   }
   

3. Build and run each module separately:
   • Legacy Windows machines → ./gradlew desktop-lwjgl:run
   • Modern platforms → ./gradlew desktop-lwjgl3:run
4. Optional single‑launcher approach:
   • Package both desktop modules into one distribution.
   • Create a small Launcher that reads a system property (e.g., -Dbackend=lwjgl3) and uses reflection to instantiate either LwjglApplication or Lwjgl3Application.
   • Ensure that only the selected backend’s native JARs are on the -Djava.library.path at runtime; you can do this by launching with a classpath that contains only the chosen desktop module.
5. Native dependency alignment:
   • All extensions (Box2D, FreeType, etc.) must match the LWJGL version of the backend they target. Mixing LWJGL2 extensions with LWJGL3 will cause UnsatisfiedLinkError.
   • Use the same lwjgl3Natives classifier for LWJGL3 builds and the legacy lwjgl natives for LWJGL2 builds.

What This Means for Your Build

With the multi‑module layout you keep the core code in one place, avoid class‑path conflicts, and can still publish two separate desktop binaries: one for legacy Windows users and one for modern systems. If you truly require a single binary that decides at runtime, you must implement a custom launcher and classloader, which is complex and not recommended for most projects.

Next Diagnostic Question

Do you need to deliver a single executable that supports both backends, or are separate legacy and modern desktop builds acceptable for your release process?