Creating a cross-platform project

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.

Getting ready

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.

How to do it…

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:

1. First, download the latest version of the tool from http://libgdx.badlogicgames.com/nightlies/dist/gdx-setup.jar.
2. Running the .jar file with no additional arguments opens up the user interface straightaway. Filling the form in does not entail any mystery at all.
3. 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:\android
   

   Done! Just like we did with environment-test in the previous recipe, now it is time to import the project in Eclipse.

4. 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.

   Note

   Remember that you need to set the working directory for the desktop project so that it can find the assets that are located within the Android project.

5. Right-click on the desktop project. Go to Properties | Run/Debug Settings, select DesktopLauncher, and click on Edit.
6. Open the Arguments tab and select Other as the working directory.
7. Now, enter this in the input box:

   ${workspace_loc:my-gdx-game-android/assets}

8. 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.properties file located under the gradle directory in your user folder:

   org.gradle.jvmargs=-Xms128m -Xmx512msdk.dir=C:/android

   Note

   The Libgdx Gradle build system is also compatible with Intelij IDEA, Netbeans, and the command line. Feel free to explore and look for additional information on these lines.

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!

How it works…

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:

There's more…

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.gradle file is
• The user home, which will be C:\Users\User\.gradle\gradle.properties in Windows and ~/.gradle/gradle.properties in GNU/Linux
• The 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.

See also

• For further details on the Gradle project and dependency management, read the Updating and managing project dependencies recipe of this chapter.