In this recipe, we will lay out a series of very simple steps for you to set up Libgdx cross-platform projects really quickly. With very little hassle, you will have a functional barebones application ready to take your brilliant game logic in.
Make sure you have all Libgdx dependencies installed in your development machine. If you didn't follow all the steps in the Setting up a cross-platform development environment recipe, proceed to do so before carrying on.
Libgdx makes use of Gradle to handle the build process. Gradle is an open source build automation tool, very similar to Apache Ant and Apache Maven. It handles your project's dependencies and downloads external libraries when necessary; you only have to declare that you want to include them in your project.
Luckily enough, you do not need to learn a lot about Gradle to start working on Libgdx projects because our framework bundles a tool that creates a skeleton application with all the basics for you to use.
The gdx-setup tool offers a very straightforward user interface as well as a command-line option. Feel free to use whichever you are most comfortable with; we will explain both here. Perform the following steps:
First, download the latest version of the tool from http://libgdx.badlogicgames.com/nightlies/dist/gdx-setup.jar.
Running the
.jarfile with no additional arguments opens up the user interface straightaway. Filling the form in does not entail any mystery at all.Simply enter the project folder name, Java package name, name of the game logic entry point class, folder where the projects will be created, and location of your Android SDK. Once you are ready, click on the Generate button, as shown in the following screenshot:
For those who fancy the command-line version of the tool, here is its usage:
java --jar gdx-setup.jar --dir <dir-name> --name <app-name> --package <package_name> --mainClass <main_class> --sdkLocation <sdk_location>--dir: This is the destination folder of the projects--name: This is the name of the application, which will determine the project folders' names--package: This is the name of the Java package where the code will live--mainClass: This is the class name for the game code entry point--sdkLocation: This is the path to your Android SDK
For example, to call the tool from the command line with the settings shown in the previous screenshot, you will have to enter:
java –jar gdx-setup.jar –dir E:\projects\tools\test –name my-gdx-game –package com.mygdx.game –mainClass MyGdxGame –sdkLocation C:\androidDone! Just like we did with
environment-testin the previous recipe, now it is time to import the project in Eclipse.Right-click on Package Explorer, select Import, and choose the Gradle project inside the Gradle tab.
Select your destination folder and click on Build Model.
Right-click on the desktop project. Go to Properties | Run/Debug Settings, select DesktopLauncher, and click on Edit.
Open the Arguments tab and select Other as the working directory.
Now, enter this in the input box:
${workspace_loc:my-gdx-game-android/assets}You need to override the memory allowance for Gradle and specify the location of Android SDK so that Gradle can pick it up. Add the following lines to the
gradle.propertiesfile located under thegradledirectory in youruserfolder:org.gradle.jvmargs=-Xms128m -Xmx512msdk.dir=C:/android
Your newly created Libgdx project should be fully functional. Gradle will take care of the dependencies, download the necessary libraries, and handle the compilation process. Like we mentioned before, the first build can take quite a while, but it should be significantly smoother from then on.
Happy coding!
At this point, you will notice how the Libgdx projects are structured. They are actually made of several projects, one per platform and another core project. The core project contains the actual logic of your game, while the platform-specific projects typically only have a launcher that calls the core entry point.
The resulting directory tree inside the test folder will look as follows:
|- settings.gradle - project submodules |- build.gradle - main Gradle build config file |- gradlew - Build script for GNU/Linux |- gradlew.bat - Build script for Windows |- local.properties - Intellij IDEA only file | |- gradle/ - local Gradle | |- core | |- build.gradle - Gradle build for core project, do not modify | |- src/ - Game code | |- desktop | |- build.gradle - Gradle build for desktop project | |- src/ - Desktop specific code | |- android | |- build.gradle - Gradle build for Android project | |- AndroidManifest.xml - Android config | |- src/ - Android specific code | |- res/ - Android icons and other resources | |- assets/ - Shared assets | |- gwt | |- build.gradle - Gradle build for GWT project | |- src/ - GWT specific code | |- webapp/ - War template | |- ios | |- build.gradle - Gradle build for iOS project | |- src/ - iOS specific code
Gradle, our build system, is particularly good with multiproject solutions. It uses domain-specific language (DSL) rather than XML, like Ant and Maven do, to define targets as well as their dependencies. When we tell Gradle to build a project for us, it uses the build.gradle files to create a directed acyclic graph representing the dependencies. Then, it builds the dependencies in the right order.
The dependency graph for the Libgdx project skeleton will look as follows:
Gradle is extremely configurable so as to accommodate the needs of a diverse set of developers and their environments. This is done through several gradle.properties files located at various specific places:
The project build directory where the main
build.gradlefile isThe user home, which will be
C:\Users\User\.gradle\gradle.propertiesin Windows and~/.gradle/gradle.propertiesin GNU/LinuxThe system properties
These settings are applied in descending order, which means that the lower settings can overwrite the higher settings.
Gradle downloads dependencies from repositories on demand. When your machine is behind a proxy, you need to specify this through one of the gradle.properties files by adding the following settings:
systemProp.http.proxyHost=www.somehost.org systemProp.http.proxyPort=8080 systemProp.http.proxyUser=userid systemProp.http.proxyPassword=password
For secure addresses, you only need to replace http with https in the previous properties.
As you surely understand, this is not a book on Gradle. If you wish to know more about it and how to tailor it for your needs, refer to the official user guide at http://www.gradle.org/docs/current/userguide/userguide_single.html.