To setup your first project and download the necessary dependencies, libGDX offers a setup tool.

  1. Download the libGDX Project Setup Tool

  2. Open your command line tool, go to the download folder and run
    java -jar ./gdx-setup_latest.jar

This will open the following setup that will allow you to generate your project:

Note: Instead of the User Interface of the Setup Tool you can also use the command-line to create your project.

You are asked to provide the following parameters:

  • Name: the name of the application; lower case with minuses is usually a good idea, e.g. my-game
  • Package: the Java package under which your code will reside, e.g. com.badlogic.mygame
  • Game Class: the name of the main game Java class of your app, e.g. MyGame
  • Destination: the folder where your app will be created
  • Android SDK: the location of your Android SDK. With Android Studio, to find out where it is, start Android Studio and click “Configure” -> “SDK Manager”. By default it is in /Users/username/Library/Android/sdk

  • Sub Projects: libGDX is cross-platform. By default, all the target platforms are included (Desktop; Android; iOS; HTML). There is no need to change the default value unless you are sure you will never compile for a specific target.

Note: iOS projects can only be compiled on macOS.

  • extensions: the extensions offered are:
    Bullet: 3D Collision Detection and Rigid Body Dynamics Library.
    FreeType: Scalable font. Great to manipulate font size dynamically. However be aware that it does not work with HTML target if you cross compile for that target.
    Tools: Set of tools including: particle editor (2d/3d), bitmap font and image texture packers.
    Controller Library to handle controllers (e.g.: XBox 360 controller).
    Box2d: Box2D is a 2D physics library.
    Box2dlights: 2D lighting framework that uses box2d for raycasting and OpenGL ES 2.0 for rendering.
    Ashley: A tiny entity framework.
    Ai: An artificial intelligence framework.

By clicking “Show Third Party Extensions” you can access a list of community-made libGDX extensions. If you want to add extensions later on, please take a look at this wiki page.

When ready, click “Generate”.

Note: You may get a message indicating that you have a more recent version of Android build tools or Android API than the recommended. This is not a blocking message and you may continue.

Project Layout

This will create a directory called mygame with the following layout:

settings.gradle            <- definition of sub-modules. By default core, desktop, android, html, ios
build.gradle               <- main Gradle build file, defines dependencies and plugins
gradlew                    <- local Gradle wrapper
gradlew.bat                <- script that will run Gradle on Windows
gradle                     <- script that will run Gradle on Unix systems
local.properties           <- IntelliJ only file, defines Android SDK location

core/
    build.gradle           <- Gradle build file for core project*
    src/                   <- Source folder for all your game's code

desktop/
    build.gradle           <- Gradle build file for desktop project*
    src/                   <- Source folder for your desktop project, contains LWJGL launcher class

android/
    build.gradle           <- Gradle build file for android project*
    AndroidManifest.xml    <- Android specific config
    assets/                <- contains for your graphics, audio, etc.  Shared with other projects.
    res/                   <- contains icons for your app and other resources
    src/                   <- Source folder for your Android project, contains android launcher class

html/
    build.gradle           <- Gradle build file for the html project*
    src/                   <- Source folder for your html project, contains launcher and html definition
    webapp/                <- War template, on generation the contents are copied to war. Contains startup url index page and web.xml

ios/
    build.gradle           <- Gradle build file for the iOS project*
    src/                   <- Source folder for your iOS project, contains launcher

What is Gradle?

libGDX projects are Gradle projects, which makes managing dependencies and building considerably easier.

Gradle is a dependency management system and thus provides an easy way to pull in third-party libraries into your project, without having to manually download them. Instead, Gradle just needs you to provide it with the names and versions of the libraries you want to include in your application. This is all done in the Gradle configuration files. Adding, removing and changing the version of a third-party library is as easy as changing a few lines in that configuration file. The dependency management system will pull in the libraries you specified from a central repository (in our case Maven Central) and store them in a directory outside of your project. Find out more in our wiki.

In addition, Gradle is also a build system helping with building and packaging your application, without being tied to a specific IDE. This is especially useful if you use a build or continuous integration server, where IDEs aren’t readily available. Instead, the build server can call the build system, providing it with a build configuration so it knows how to build your application for different platforms. If you want to know more about deploying your application, take a look here.

Now you are ready to import the project into your IDE and run it.