libgdx/gdx-liftoff

🚀 gdx-liftoff 🚀

A setup tool for libGDX Gradle projects.

📥 DOWNLOAD 📥

To generate a project, download the latest application jar. The latest release targets libGDX 1.14.2 by default. Once you have the right JAR, run it (usually double-clicking will do), or run the following command manually (replacing the VERSION appropriately):

java -jar gdx-liftoff-VERSION.jar

While other downloads are provided in recent releases, the .jar file without any operating system in the name will work on all platforms, and that one is recommended.

You must build with Java 17 or newer (up to 27)! If you are downloading Java for the first time, read this paragraph and the next two carefully; links are provided to recommended OpenJDK versions. Gradle's current version, as well as current Android tools, now require your installed JDK to be version 17 or higher. Regardless of what platforms you target, Gradle 8.10 and up need a JDK with a version at least 17! You can still target other releases, as low as 8 typically, while building with any of the JDK versions 17 and up. Stable target releases of Java from 8 to 27 work here now. If you use a JDK version that isn't 21 for Gradle, then the automatic desktop release packaging with Construo will need some configuration changes so it downloads the same version of JDK that Gradle uses. This isn't hard, but is tedious, so using 21 exactly is recommended for this reason. See our Troubleshooting document for more details.

When you enter the JDK version you use for a project, it is always one integer, such as 8 or 21. Entering any bugfix or point releases after that will confuse Gradle and lead to bizarre bugs. JDK versions, or language levels, never include bugfix versions, and when you enter one here it should always be a single int, with no . or _ . If you target iOS using RoboVM, note that you will be required to use at most Java features language level 8, but won't have access to any APIs added in Java 8 (at most, APIs from 7 are available). Liftoff forces language level 8 for RoboVM even if other projects use a higher language level; you need to make sure you only use features that are compatible with RoboVM if you target it. If you target the browser via GWT, you need to use language level 8 or 11, with 11 recommended (any recent JDK installation can still target 8 or 11; it can't actually be a JDK 8 or 11 installation and still run Gradle). If you target the browser via TeaVM, the TeaVM module will always use at least language level 17, even if a lower language level is used in core or other modules. If you are using JDK 21 to build, you won't have any problem targeting language level 17 for TeaVM, and it will work out-of-the-box.

If you don't know what JDK you have installed, or don't have one, then either of the JDK 21 installers from OpenJDK vendors BellSoft Liberica or Azul Zulu are recommended for Windows and macOS users. They have good default settings in their MSI Windows installers. Oracle's OpenJDK (and especially its proprietary JDK) are not recommended. This is partly because their installers have confusing default options. The other part is that their licensing is not as clear as OpenJDK vendors that must use GPL v2 with Classpath Exception as their license. Oracle can change (and has changed) licensing without much warning. On Linux, use your package manager to install OpenJDK 21. On macOS, you might need to get both an AARCH64 OpenJDK and an x86_64 OpenJDK to use certain parts of libGDX (any tools that still use LWJGL2 will need the x86_64 OpenJDK to run, and will use Rosetta). The links given for Windows should also have working macOS installers.

Do not install a JRE. If you have a JRE installed, you should install a JDK in its place, and make the JDK the default.

Java 25 through 27 are now somewhat supported to build your projects, in recent Liftoff versions. Java 25 does include some useful features for reducing memory usage, if you enable them, using java -XX:+UseCompactObjectHeaders ... to launch. Java 27 came out on September 15, 2026, and surprisingly is already supported by Gradle. Other than some small changes and additions, a major improvement in Java 27 is enabling Compact Object Headers by default. In order to run with Java 25 or newer, LWJGL3 must use version 3.4.0 or later; this is automatically handled by the current Liftoff version using Gradle constraints. If you find you need an older LWJGL3, you can now simply change lwjgl3Version in gradle.properties, which will make the constraints require a version of your choosing. One reason you might need this is to better support Wayland on Linux, which changed how it worked starting in LWJGL 3.3.4 . Currently, libGDX 1.14.2 uses LWJGL 3.3.3 unless some Gradle config changes that version. The constraints on the LWJGL version default to LWJGL 3.4.3 instead now, allowing Java 25 and up to work. Typically, you either leave lwjgl3Version=3.4.3 unchanged, or set it to lwjgl3Version=3.3.3 for Wayland reasons. Note that if you are running on Java 25 or newer with the --sun-misc-unsafe-memory-access=deny option (which will be the default in future JDKs), LWJGL3 will use the new FFM APIs (Foreign Function Memory) instead of the older and scheduled-to-be-removed sun.misc.Unsafe class.

Advanced users may want to try using GraalVM to either run their project or to build a "native-image" distributable. Native-image, also called Substrate VM, allows you to avoid distributing a JDK at all by compiling a fairly-small executable to native code. This starts up quickly, but can't reach as high of a peak speed as a JDK can normally, and may stutter when the garbage collector runs, so using native-image isn't always a great option for games. Games that already perform very well and don't produce much garbage may have uses for it, since it is harder to decompile at this point in time than a JAR (which is effortless to take apart). Liftoff includes some very out-of-date native-image configuration that is disabled by default; you can enable it in gradle.properties by setting enableGraalNative=true . You might prefer using Construo to build native launchers for a minimized JDK, though, which works without any changes in a new Liftoff project. To do that, just make sure Gradle is using OpenJDK 21 to run; if it doesn't work right away, see this Troubleshooting section. Note that Construo can build releases for any target platform (but can't notarize Mac builds), from any desktop OS, but GraalVM native image can only target the same OS it is run from. If you do use GraalVM, take note of its license; there is a community edition that is GPL v2 with CE, and another edition that has changed branding and license a few times. Running a JAR with GraalVM without using native-image also works, and can sometimes yield significantly better performance on long-running apps relative to a typical OpenJDK installation, but it takes longer to get to full speed.

Most current OS and architecture combinations are supported, except ARM Windows at this point because libGDX itself doesn't yet support ARM Windows. The ARM architecture is supported on Linux and macOS. x86 is supported on Windows if you use the cross-platform JAR, and x64 is supported for all OSes libGDX supports. Sorry if you use BSD, but libGDX doesn't currently support that, either. Alpine Linux (which uses MUSL as its C library) might work, but don't get your hopes up. Be aware that if you use TeaVM, you may need to output JavaScript instead of WASM to target very old OS/browser versions if you want users to be able to run with unsupported browsers on Windoes 7, for instance.

If you have any trouble, you can try our 🐛Troubleshooting Guide🐛.

Features

In addition to most features of the original gdx-setup, the gdx-liftoff tool offers:

• Project templates. You can choose one of many project skeletons highlighting various libGDX features.
• Instant input validation. Your project data is validated as you type it in.
• Other JVM languages support. You can choose additional languages for your project, like Kotlin or Scala. Their standard libraries, Gradle plugins, and appropriate source folders will be included.
• Customization. You have more control over the versions of software used by your application.
• More third-party extensions. Their versions are tracked by gdx-liftoff and are updated frequently.
• Automatic configuration for tricky extensions. If you're having trouble setting up Artemis-ODB, Lombok, or several other libraries, Liftoff does some extra work, so you don't have to.
• Preferences support. Basic data of your application is saved, so you don't have to fill it each time you generate a project.
• Optional Gradle runner. You can optionally execute Gradle tasks after project generation. Gradle doesn't have to run for a project to be created.
• Supports all libGDX backends. Do you need the LWJGL2, LWJGL3, and/or Headless backends? Liftoff provides simple checkboxes to add any and all official platforms, plus some special other modules.
• Convenience features. If you have JetBrains Toolbox, you can open a just-generated project in IDEA with one click (it needs "Generate Shell Scripts" set in Toolbox). If you use Eclipse, you can still import Gradle projects normally.
• Up-to-date. This project prides itself on updating quickly after releases of major external components such as Gradle or libGDX itself.
• More backends are supported. The headless backend has been part of libGDX for a long time, but wasn't easily accessed in gdx-setup; it is a checkbox here. TeaVM, an increasingly-popular alternative to GWT for browser-based applications, is also here, and works with Kotlin and other JVM languages as well as it does with Java. MOE, an alternative backend for iOS, is also here, and works with newer Java versions than the official RoboVM.
• Build native executables out-of-the-box. The Construo plugin lets you assemble a JDK with your project's JAR and launch it with a native Win64 .exe, MacOS (x64 or AARCH64) .app, or Linux x64 executable. Configuration is also included for Graal Native Image, though this is less likely to "just work" immediately.

Guide

For the video-inclined, @raeleus produced this tutorial video.

If you'd rather read text, then here you go...

Gdx-Liftoff is a relatively straightforward GUI application.

• Enter a project name/package/main-class-name.
• Click Project Options.
• Select options you want (additional platforms, non-Java languages, official extensions, and/or a template).
• Click Next.
• Select any third-party extensions you want to add.
• Click Next.
• Enter a project path and optionally change Java version (such as to 8 for better iOS support).
• Click Generate, and let the magic happen.

After that you can open the project in the path you specified, or open it more quickly in IDEA if it's installed how Liftoff can see it (using JetBrains Toolbox, ideally, though a manually installed IDEA can sometimes work).

If you want to use Kotlin, a Kotlin template is recommended (such as Kotlin Logo); these mention that they use "Kotlin launchers" in their descriptions. The KTX libraries are all available as third-party extensions; these aren't required for Kotlin projects, but they can be helpful. KTX and other Kotlin-based libraries need Kotlin enabled. Currently, projects generated here default to using Kotlin 2.2.21, which may have some incompatibilities with the earlier 1.9.x releases. You could instead set the version to the newest 1.9.x release (currently 1.9.25), in the Languages dialog, when you select Kotlin as an option. The 2.x series of releases claims a number of nice improvements, however, and most libraries appear to be either very close to compatible, or are compatible already. Liftoff itself is built using Kotlin 2.x , as well as substantial Java code (compatible with Java 8).

Some things are structured differently in Liftoff projects, compared to gdx-setup projects. Where gdx-setup put almost all configuration in /build.gradle (in the project root), including for subprojects like android or html, Liftoff puts only shared configuration in the root build.gradle, keeps all user-configurable version information in /gradle.properties, and moves per-project configuration to /core/build.gradle, /android/build.gradle, /html/build.gradle, etc. Liftoff also calls the project that depends on LWJGL3 lwjgl3, since you can also create a project that depends on LWJGL2, and that's called lwjgl2. You might need to change references to the "desktop" module (as gdx-setup calls LWJGL3) to lwjgl3, since that's the most likely desktop module you would be using.

If you're adding dependencies to build.gradle files, you will probably need to add them to /core/build.gradle rather than /build.gradle in the root. Some dependencies may also need parts added to /lwjgl3/build.gradle, /html/build.gradle, and so on. If a library says to add lines to the dependencies section, that almost always means the block inside dependencies { }, but not inside buildscript { }. There are often two dependencies blocks, and you generally want the last one. Templates selected in Liftoff handle this automatically.

For more details on how to use the application and how it works, see the usage guide.

When submitting a pull request, please format the application with the ktlintFormat Gradle task.

Credits

The project was forked from the czyzby/gdx-setup repository. @czyzby and @kotcrab created the original application, as well as a set of libraries that it depends on (gdx-lml and VisUI respectively). Since then, the project is maintained by @tommyettinger. Graciously, czyzby came back and made a wide variety of improvements, so big thanks there! Thanks also to @metaphore, who now maintains gdx-lml (which this used and still provides templates so new projects can use it).

@raeleus created the Particle Park skin for scene2d.ui, which was adapted to be the default skin added to new projects (if the "Generate UI Assets" option is selected). "Accademia di Belle Arti di Urbino and students of MA course of Visual design" has created the Titillium Web font that the skin uses (under SIL OFL license). Oh yeah, and he did some other stuff starting in version 1.12.1.10, such as almost the entire release. Huge thanks to raeleus for the complete overhaul of the user experience!

@Berstanio has provided help in a number of ways to this project, such as by maintaining MOE Community Edition and PRing updates to it here, as well as handling the Graal Native Image helper, and probably even more things over the years. @obigu has also contributed a lot of valuable, clean code to the project, helping a variety of places.

Other project contributors include @Mr00Anderson, @lyze237, @metaphore (again!), and @payne911. People who haven't directly contributed code have still helped a lot by spending their time to test on platforms like macOS and iOS; @JojoIce is one of several people who made a difference regarding iOS. And of course, many thanks go to all the early adopters for putting up with any partially-working releases early on!

The "Space Shuttle" icon was drawn by Delapouite for the large game-icons.net collection. These icons are also available in a libGDX atlas format in this repo, if you want to use the whole collection yourself.

The font used by the Liftoff GUI in 1.14.2.1 and later is DINish, which is licensed under the permissive SIL OFL 1.1 . It replaces another, similar-looking font that the licensing (and even the name of the font) was unclear on, though it was freely available.

Thanks also to everyone who has made the various libraries and tools Liftoff depends upon. From the huge team responsible for Graal Native Image, to Construo by pretty much a team of one, some of the best features of Liftoff aren't in Liftoff code at all.

Good luck, and we hope you make something great!