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:

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. mygame
  • 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.

  • 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 the list of community-made libGDX extensions.

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.

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

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           <- IntelliJ only file, defines Android SDK location

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

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

    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

    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

    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.

A dependency management system is an easy way to pull in third-party libraries into your project, without having to manually download them. Instead, the dependency management system 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.

A build system helps 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.