A modern setup tool for libGDX Gradle projects
A modern setup tool for libGDX Gradle projects, forked from czyzby/gdx-setup
If you've used libGDX for even a short time, you've probably used the official
gdx-setup.jarmade by the libGDX team. It's seen major improvements lately, but it still lags behind in some areas -- it places assets in different locations depending on how you initially configured your project, and it is very far behind the times on its default LWJGL version and on third-party extensions. The official setup may transition to a web-based tool soon, but any user of the Internet can recall times when formerly-reliable services went offline or had outages. This project provides another alternative setup tool based on SquidSetup, but removing the close ties to the SquidLib libraries to make it more general-use. Using SquidSetup's code, which is built on czyzby's code, gives us working projects that use Gradle 7.2, ahead of 6.7.1 for the official setup and 4.0.2 for czyzby's gdx-setup. The current Gradle version is 7.2 at the time of writing, and since gdx-liftoff 22.214.171.124, new projects use that 7.2 version. This allows new projects to "just work" on machines where Java 16 is the default, and the relatively small amount of configuration changes needed for Gradle 7.2 are all handled by gdx-liftoff. Thanks to the Gretty plugin's latest release, Gradle 7.x now works well with the HTML platform, without additional quirky configuration (earlier versions of Liftoff needed that). Currently, gdx-liftoff projects depend on libGDX 1.10.0 by default, and allow using snapshots as well. The current version of libGDX is 1.10.0, which had a longer release cycle because there was an emphasis on fixing bugs in earlier releases. You can choose any released version of libGDX (or a nightly version) in the Advanced tab of the program window; it will be downloaded if needed when you import the Gradle project into your IDE or run one of most Gradle tasks. If you're updating from an older libGDX version, see the official migration guide.
Projects default to using LWJGL3 instead of LWJGL2 (the old 'desktop' platform), since code tends to be very similar between the two, but LWJGL3 generally offers more features. Somewhat confusingly, gdx-setup used LWJGL2 for its desktop platform until recently, but now uses LWJGL3 and still calls it 'desktop'. Liftoff projects can have both LWJGL2 and LWJGL3 modules, which shouldn't be needed for too much longer, but is sometimes needed now. The "desktop" module is LWJGL2, and "lwjgl3" is, well, LWJGL3. If following a tutorial, you may need to change mentions of the "desktop" module to "lwjgl3". This code is tested for compatibility with GWT, including the various changes that Gradle needs with this version. It is sometimes tested on Android, but Android Studio is often incompatible with recent Gradle releases, and Android certainly doesn't support Java 13 or higher features across the board. Issues with iOS and RoboVM will have to be addressed by someone sending a pull request, because I can't reproduce any iOS issues without an iOS device.
The current version of gdx-liftoff uses LWJGL3 internally; 126.96.36.199 used LWJGL2 in an attempt to be compatible with libGDX's TexturePacker, but there seem to be more compatibility issues with LWJGL2, maybe since it hasn't been updated in 5+ years, than with LWJGL3. This perhaps validates the decision to default to LWJGL3 for new projects generated by gdx-liftoff.
gdx-liftoff.jarfrom the Releases tab of this project.
ld.soor a linking error. If you encounter this, switch to AdoptOpenJDK (bundling it with releases) or LWJGL3.
Java versionis set to 8 on the Advanced tab, then gdx-liftoff sets up the Android configuration to use core library desugaring and other Java-8-related features, allowing a large subset of Java 8 language features, and the standard library in JDK 8, to be used across most platforms (not iOS, though).
intnumber types, and relates to
intnot overflowing as it would on desktop, and
longnot being visible to reflection. See this small guide to GWT for more. It's very likely that you won't notice any difference unless you try to make behavior identical on GWT and other platforms, and even then there may be nothing apparent.
varkeyword to be used, plus other Java 11 features, but doesn't change much of what's available from the standard library.
leinand a simple built-in manager.
Java versionis the minimum across all platforms, and should be 7 or more (8 is generally safe). You can set
Desktop Java versionto any version at least equal to
Java version, and similarly for
Server Java version; these only affect the Desktop/LWJGL3 and Server modules, respectively. You can set
Java versionto as high as 16 if you have Java 16 installed, or similarly for Java 11, 12, 13, 14, or 15, but it will require users to also have Java of that version, or for you to distribute a JRE of the appropriate version with your game.
SETUP COMPLETEin green, the build is done; at the time you import the generated
build.gradleproject file, some tasks will run.
Now you'll have a project all set up with a sample. In IntelliJ IDEA or Android Studio, you can choose to open the
build.gradlefile and select "Open as Project" to get started. In Eclipse or Netbeans, the process should be similar; see libGDX's documentation.
View -> Tool Windows -> Gradle, and selecting tasks to perform, such as
lwjgl3 -> Tasks -> application -> run.If you try to run a specific class'
main()method, you may encounter strange issues, but this shouldn't happen with Gradle tasks.
main()method, you usually need to set a run configuration so the working folder is
assets. The location of the
assetsfolder is different here than with the official setup; it's at the same depth as
lwjgl3, and doesn't change across configurations like with the official setup.
lwjgl3 -> Tasks -> build -> jar; this jar will be in
lwjgl3/build/libs/when it finishes. Note: this is the command-line option
gradlew lwjgl3:jar, not the
distcommand used by the official setup jar. Substitute
lwjgl3is if you use the legacy LWJGL2 version.
superDevtask for the
gwtmodule, or also possibly the
disttask in that module.
ios/data/Media.xcassets/AppIcon.appiconsethas the iOS icons,
android/reshas icons in subfolders, and
lwjgl3/src/main/resourceshas icons for desktop with LWJGL3. You'll probably want to keep the icons with their existing names.
Gradle has some quirks. Here's some notes on things you might encounter during upgrades from other projects or older versions.
apikeyword instead of the
compilekeyword it used in earlier versions. All modules use the
java-libraryplugin, which enables the
apikeyword for dependencies.
Reimport all Gradle projectsbutton is a pair of circling arrows in the Gradle tool window, which can be opened with
View -> Tool Windows -> Gradle.
jcenter()repo will not be used in new projects.
gradlew lwjgl3:runcommand can work at all on MacOS.
-XstartOnFirstThreadto be passed to the
javacommand, but Guacamole can handle this for you and your users).
-XstartOnFirstThread, and so don't need Guacamole for that.
ANDROID_SDK_ROOTvariable. If this variable wasn't set on the first time you ran gdx-liftoff, then the latest value entered for the Android SDK path will be saved in
~/.prefs/gdx-liftoff-prefs(that is, inside
.prefs/in your user home directory). Starting in 188.8.131.52, gdx-liftoff will pre-fill the Android SDK path with
ANDROID_SDK_ROOTif it hasn't been set yet, but will use the last used path if there's a historical path. You can change any and all settings history by either editing
~/.prefs/gdx-liftoff-prefsor just deleting that file and having gdx-liftoff remake it.
When submitting pull requests, please format the code with the
Huge thanks to czyzby for writing the original tool this is based on, as well as much of the code gdx-liftoff depends on. Thanks also to Raymond Buckley for making the Particle Park skin for scene2d.ui, which was adapted to be the skin added to new projects (if you choose the "Generate UI Assets" option in the Advanced tab). More thanks to "Accademia di Belle Arti di Urbino and students of MA course of Visual design" for making the Titillium Web font that the skin uses (SIL OFL license). Thanks to anyone who's contributed code to gdx-liftoff ( Mr00Anderson, lyze237, metaphore, and payne911, so far)! And of course, thanks to all the early adopters, for putting up with any partially-working releases I churned out.
Good luck, and I hope you make something great!