Libgdx Cross-platform Game Development Cookbook

Libgdx is based on Java, and therefore, Java Development Kit is a requirement. The installation step is as follows:

Go to Oracle's download site, http://www.oracle.com/technetwork/java/javase/downloads, and click on the latest release of Java SE Development Kit that corresponds to your operating system. Note that you need to differentiate between the x86 and x64 builds.

Eclipse is the most popular IDE for Libgdx game development, and it is thus the one we will focus in this book. If it is not of your liking, you can use IntelliJ IDEA, Netbeans, or any editor along the command line. Perform the following installation steps:

Follow these instructions to install Android Development Kit, which is essential to target Android devices:

export PATH=$PATH:/dev/android-sdk-mac_x86_64/tools
export PATH=$PATH:/dev/android-sdk-mac_x86_64/platform-tools

Getting tired? Worry no more, we are getting close to the finish line! We are about to install several plugins that will allow us to manage our build process and target iOS devices:

A course on how to use an IDE is out of the scope of this book. However, pertinent explanations will be provided when having to deal with Eclipse-specific issues. The installation steps are as follows:

Gradle is an open source build automation system. It will gracefully handle all the dependencies of our projects, doing most of the cumbersome heavy lifting. Perform the following steps:

Great! One more task can be crossed out from our shopping list.

XCode is the Apple IDE required to develop for their platforms. Mac users who want to target iOS can get hold of XCode free of charge from Apple Store.

Eclipse has the impolite practice of not using UTF-8 encoding and Unix line endings if you are under a Microsoft operating system. While this will not affect you initially, it will prove to be a huge pain when it comes to using other peers' code as many conflicts will appear to ruin the party. Perform the following steps:

The time of truth has come as we are about to import a Libgdx project to our workspace for the first time and see whether we have made any mistakes along the way. This is the most basic Libgdx project you can possibly make if you want to target all platforms. Use the source code provided with this book. Perform the following steps:

As long as you followed this recipe correctly, there should be no errors hanging around; so, it is time to run the project on every platform as a final test.

First, let's try the desktop project, which is the easiest of all.

Right-click on it, select Run As followed by Java application, and then choose the entry point (DesktopLauncher). You will see the following window:

Android is next in the queue.

To pair your Android device, be it a phone or tablet, you need to enable USB debugging on your Android device, which can be a little obscure in later versions. Perform the following steps:

Let's try the HTML project now. Perform the following steps:

Additionally, Mac users can run the iOS project by right-clicking on environment-test-ios and going to the Run As menu. Inside, you will find three options of interest:

Pretty much like the HTML5 project, the first build will take a long time; it should be fine after this.

Congratulations! Now, you can run your Libgdx projects on all targetable platforms.

Every Libgdx application has a very well-defined lifecycle controlling the states it can be in at a given time. These states are: creation, pausing, resuming, rendering, and disposing. The lifecycle is modeled by the ApplicationListener interface, which we are required to implement as it will serve as the entrance to our game logic. In our recipe's example, the EnvironmentTest class in the core project carries out such roles.

Meet the ApplicationListener interface:

public interface ApplicationListener {
   public void create ();
   public void resize (int width, int height);
   public void render ();
   public void pause ();
   public void resume ();
   public void dispose ();
}

Your ApplicationListener interface implementation can handle each one of these events in the way it deems convenient. Here are the typical usages:

When do each of these methods get called? Well, that's a really good question! Before we start looking at cryptic diagrams, it is much better to investigate and find out for ourselves. Shall we? We will simply add some logging to know exactly how the flow works.

Take a look at the EnvironmentTest.java file:

public class EnvironmentTest implements ApplicationListener {
   private Logger logger;
   private boolean renderInterrupted = true;
   
   @Override
   public void create() {
      logger = new Logger("Application lifecycle", Logger.INFO);
      logger.info("create");
   }

   @Override
   public void dispose() {
      logger.info("dispose");
   }

   @Override
   public void render() {
      if (renderInterrupted) {
         logger.info("render");
         renderInterrupted = false;
      }
   }

   @Override
   public void resize(int width, int height) {
      logger.info("resize");
      renderInterrupted = true;
   }

   @Override
   public void pause() {
      logger.info("pause");
      renderInterrupted = true;
   }

   @Override
   public void resume() {
      logger.info("resume");
      renderInterrupted = true;
   }
}

The renderInterrupted member variable avoids printing render for every game loop iteration.

The Logger class helps us show useful debug information and errors on the console. Not only does it work on desktops but also on external devices, as long as they are connected to Eclipse. Remember this little new friend as it will be truly useful for as long as you work with Libgdx. The constructor receives a string that will be useful to identify the messages in the log as well as on a logging level.

In order of increasing severity, these are the available logging levels: Logger.INFO, Logger.DEBUG, Logger.ERROR, and Logger.NONE. Several methods can be used to log messages:

Logging levels can be retrieved and set with the getLevel() and setLevel() methods, respectively. Both the level and the method used to log a message will determine whether they will actually be printed on the console. For example, if the level is set to Logger.INFO, only messages sent through info() and error() will appear, and those sent through debug() will be ignored.

Now, run the application on all the platforms and pay attention to the console. Depending on how you play with the focus, the output will vary, but it should be similar to this:

Application lifecycle: create
Application lifecycle: resize
Application lifecycle: render
Application lifecycle: pause
Application lifecycle: render
Application lifecycle: resume
Application lifecycle: render
Application lifecycle: dispose

This should give you a pretty decent handle of how the application lifecycle works.

Placing breakpoints on each ApplicationListener overridden method is also a good way of discovering what is going on. Instruction breakpoints allow you to debug an application and stop the execution flow that reaches the said instruction. At this point, you can run the code instruction by instruction and examine the current state of the active variables. To set a breakpoint, double-click next to the corresponding line; a blue dot will confirm that the breakpoint is set. Once you are done, you can debug the application by right-clicking on the desired project and selecting the Debug As menu.

The Eclipse Debug view will then enter the stage with all its shiny panels. The Debug tab shows the current execution callstack, the Variables tab contains the current state of the variables within scope, and in the following screenshot, you can see the code with the current line highlighted. The arrow buttons in the upper toolbar can be used to step over the next instruction (F6) or move on to the next method (F5), where applicable, or out of the current method (F7), as shown in the following screenshot:

Every platform project consists of a starter class (or entry point). This class is responsible for constructing the platform-specific application backend. Each backend implements the Application interface. The starter class also passes a new instance of our ApplicationListener implementation to the application backend. This implementation typically lives in the core project and serves as an entry point to our cross-platform game code. Finally, it also submits a configuration object, and by doing so, it provides a mechanism to customize general parameters, as we will see later.

public class DesktopLauncher {
   public static void main (String[] arg) {
      LwjglApplicationConfiguration config = new LwjglApplicationConfiguration();
      new LwjglApplication(new EnvironmentTest(), config);
   }
}

public class AndroidLauncher extends AndroidApplication {
   @Override
   protected void onCreate (Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      AndroidApplicationConfiguration config = new AndroidApplicationConfiguration();
      initialize(new EnvironmentTest(), config);
   }

public class GwtLauncher extends GwtApplication {
   @Override
   public GwtApplicationConfiguration getConfig () {
      GwtApplicationConfiguration cfg = new GwtApplicationConfiguration(480, 320);
      return cfg;
   }

   @Override
   public ApplicationListener getApplicationListener () {
      return new EnvironmentTest();
   }
}

public class IOSLauncher extends IOSApplication.Delegate {
    @Override
    protected IOSApplication createApplication() {
        IOSApplicationConfiguration config = new IOSApplicationConfiguration();
        return new IOSApplication(new EnvironmentTest(), config);
    }

    public static void main(String[] argv) {
        NSAutoreleasePool pool = new NSAutoreleasePool();
        UIApplication.main(argv, null, IOSLauncher.class);
        pool.drain();
    }
}

As you already know, every Libgdx game needs to have an ApplicationListener interface implementation in its core project for the launchers to use. We also saw how the developer is forced to implement the create(), dispose(), render(), resize(), pause(), and resume() methods of such an interface. However, these overridden methods might end up completely empty. What a waste of digital ink, and more importantly, our precious time!

Luckily enough, Libgdx provides a useful ApplicationAdapter class that already contains an empty implementation for each ApplicationListener interface method. This means that you can simply inherit from ApplicationAdapter and only override the methods you really need. This comes particularly in handy when writing small tests rather than big games. These small adapter classes are quite common within the API, and they are really comfortable to use as long as we do not need to inherit from anything else. Remember that Java does not support multiple inheritance.

The following will be perfectly valid if we want a completely empty application:

public class MyGame extends ApplicationAdapter {}

Most games are made out of several screens the player can navigate through. The main menu, level selection settings, or levels are some of the most common examples. Though this completely depends on the nature of each project, most of them definitely share the structure. Libgdx comes with an utterly minimalistic screen system built-in, which might just be enough for your requirements, so why not use it? Reinventing the wheel is rarely a good idea.

The two main components of this system are the Game abstract class and Screen interface. Game implements the well-known ApplicationListener interface, so you will only need your main class to inherit from Game.

The Game class holds a reference to the current Screen and provides the getter and setter methods for it. Game requires you to implement the create() method, but already provides implementations for the rest of the application lifecycle methods. Be aware that if you override any of the other methods, you will need to call the parent version so as to maintain screen behavior correctness. The helpful bit comes with the render() method, which will automatically update and render the active Screen reference, as long as it is not null.

What follows is an UML class diagram illustrating a sample game architecture based on the Game/Screen model. The user implemented MyGame as a Game derived class, and the SettingsScreen, GameScreen, LevelSelectionScreen, and MainMenuScreen classes were derived from Screen:

The Game public API looks like this. Note that method implementation has been omitted for space reasons:

public abstract class Game implements ApplicationListener {
   public void dispose ();
   public void pause ();
   public void resume ();
   public void render ();
   public void resize (int width, int height);
   public void setScreen (Screen screen);
   public Screen getScreen ();
}

The Screen interface is quite similar to the ApplicationListener interface, but its equivalent methods will only be called when it is the active screen. It also adds the hide() and show() methods that will be called when changed to and from a screen, respectively. In the following code, you will find an overview of the interface:

public interface Screen {
   public void render (float delta);
   public void resize (int width, int height);
   public void show ();
   public void hide ();
   public void pause ();
   public void resume ();
   public void dispose ();
}

Throughout this primer, and for space reasons, we will only show small snippets from the build file.

Go ahead and open the build.gradle file from Eclipse. The first thing you will come across is the buildscript element, which defines the list of repositories and basic dependencies. Repositories act as a library-serving system. We can reference libraries by name, and Gradle will ask the list of repositories for a library that matches the name:

buildscript {
    repositories {
        maven {
            url 'https://github.com/steffenschaefer/gwt-gradle-plugin/raw/maven-repo/'
        }
        ...
    }

    dependencies {
        ...
    }
}

The allprojects element contains a string with the application version. Additionally, it defines appName as well as the Libgdx and roboVM versions it should build against. It also provides a list of repositories to fetch from:

allprojects {
    apply plugin: "eclipse"
    apply plugin: "idea"
    
    version = "1.0"
    ext {
        appName = "environment-test"
        gdxVersion = "1.2.0"
        roboVMVersion = "0.0.13"
    }
    
    repositories {
        ...
    }
}

Every project has a project element indicating its name. A skeleton application's core project will only depend on the previously defined Libgdx version:

project(":core") {
    apply plugin: "java"
    
    dependencies {
        compile "com.badlogicgames.gdx:gdx:$gdxVersion"
    }
}

Platform-specific projects, such as a desktop project, will depend on core as well as their corresponding backend and potentially native libraries:

project(":desktop") {
    apply plugin: "java"
    
    dependencies {
        compile project(":core")
        compile "com.badlogicgames.gdx:gdx-backend-lwjgl:$gdxVersion"
        compile "com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop"
    }
}

Do not panic if you do not fully understand everything that goes on inside the build script. However, you should at least have a very basic grasp on how the general structure holds itself together.

Now, let's get on to some useful business.

Dependencies that are pulled from repositories take the following typical Maven format:

compile '<groupId>:<artifactId>:<version>:<classifier>'

Intuitively, whenever you desire to change a dependency version, you just need to go and modify the version component of its declaration. Now, imagine the Libgdx team has released a new version and we are all very excited with the new features; it is time to try them out. Conveniently enough, throughout the script, the Libgdx version points to the gdxVersion variable. We only need to find the allprojects element and change the following:

gdxVersion = "1.1.0"

To the following, you are free to choose whichever version you like:

gdxVersion = "1.2.0"

To make Gradle fetch the new dependencies, select all the projects, right-click on Gradle, and then click on Refresh All.

Libgdx comes with several additional libraries that provide a ton of extra features. The reason they are not part of the core is because either not everyone is likely to need them or because they might not work on all backends. These extensions have been mavenized and can be fetched from the repositories.

Currently, the following are the Libgdx Gradle-ready extensions along with their required dependencies for each of the projects. The core dependency will add the interfaces for you to use within the game code, whilst the platform-specific dependencies will contain the implementation of such interfaces. You will need to add them inside the corresponding dependencies element.

compile "com.badlogicgames.gdx:gdx-bullet:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-desktop"

compile "com.badlogicgames.gdx:gdx-bullet:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-armeabi"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-armeabi-v7a"

compile "com.badlogicgames.gdx:gdx-bullet:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-ios"

compile "com.badlogicgames.gdx:gdx-freetype:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-freetype-platform:$gdxVersion:natives-desktop"

compile "com.badlogicgames.gdx:gdx-freetype:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-freetype-platform:$gdxVersion:natives-armeabi"
natives "com.badlogicgames.gdx:gdx-freetype-platform:$gdxVersion:natives-armeabi-v7a"

compile "com.badlogicgames.gdx:gdx-freetype:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-freetype-platform:$gdxVersion:natives-ios"

compile "com.badlogicgames.gdx:gdx-controllers:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-controllers-desktop:$gdxVersion"
compile "com.badlogicgames.gdx:gdx-controllers-platform:$gdxVersion:natives-desktop"

compile "com.badlogicgames.gdx:gdx-controllers-android:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-controllers:$gdxVersion:sources"
compile "com.badlogicgames.gdx:gdx-controllers-gwt:$gdxVersion"
compile "com.badlogicgames.gdx:gdx-controllers-gwt:$gdxVersion:sources"

compile "com.badlogicgames.gdx:gdx-box2d:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-desktop"

compile "com.badlogicgames.gdx:gdx-box2d:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-armeabi"
natives "com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-armeabi-v7a"
natives "com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-x86"

compile "com.badlogicgames.gdx:gdx-box2d:$gdxVersion"
natives "com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-ios"

compile "com.badlogicgames.gdx:gdx-box2d-gwt:$gdxVersion:sources"
compile "com.badlogicgames.gdx:gdx-box2d:$gdxVersion:sources"

compile "com.badlogicgames.gdx:gdx-tools:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-tools:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-ai:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-ai:$gdxVersion"

compile "com.badlogicgames.gdx:gdx-ai:$gdxVersion:sources"

It is possible to add extra repositories to Gradle to look for the files you need by adding them to the allprojects section. Gradle supports Maven- and Ivy-formatted repositories:

allprojects {
    ...
    
    repositories {
        ivy { url "https://some-ivy-repo.com/repo" }
        maven { url "https://some-maven-repo.com/repo" }
    }
}

The library you want to use so desperately might not be in any Maven or Ivy repository. Is everything lost? Of course not! You can make projects depend on local files such as arbitrary JAR packages.

For instance, you can place the JAR files you need inside a lib folder in each project. Then, you will need to add the following entry to the dependencies section of the projects:

dependencies {
    compile fileTree(dir: 'libs', include: '*.jar')
}

HTML5 projects will require extra attention when adding dependencies. The GWT compiler needs to know about the modules the application will use. This information needs to be specified in both the GdxDefinition.gwt.xml and GdxDefinitionSuperdev.gwt.xml files located in the class path. The following snippet shows a typical gwt.xml file highlighting the addition of the popular Universal Tween Engine dependency:

<module rename-to="html">
    <inherits name='com.badlogic.gdx.backends.gdx_backends_gwt' />
    <inherits name='com.cookbook.environment.EnvironmentTest' />
    <inherits name='aurelienribon.tweenengine'/>
   
    <entry-point class='com.cookbook.environment.client.GwtLauncher' />

    <set-configuration-property name="gdx.assetpath" value="../android/assets" />
</module>

The Box2D extension will require you to inherit from the following module:

<inherits name='com.badlogic.gdx.physics.box2d.box2d-gwt' />

The Controllers extension will ask for the following module:

<inherits name='com.badlogic.gdx.controllers.controllers-gwt' />

The AI extension will require the following:

<inherits name='com.badlogic.gdx.ai' />

Managing GWT projects can be a bit fiddly, and we will cover this topic more thoroughly in the Making libraries compatible with GWT recipe of Chapter 11, Third-party Libraries and Extras.

Every time you add or update a dependency, it is advisable to rebuild the Gradle model so that everything is up to date and you can carry on working normally. Select Gradle and Refresh All from the project by right-clicking on the contextual menu.

Most times you work with Git, you will operate locally because your repository contains everything that you need. It lets you check the full history, commit, and revert changes, among many others. This makes Git lightning fast and very versatile as it does not attach you to any Internet connection.

The typical usage of Git is as follows:

Though we didn't use them, the way to experience Git's true glory is through branching and merging. You can think of the history of your repository as a series of directory-tree snapshots linked together. A commit is a small object that points to the corresponding snapshot and contains information about its ancestors. The first commit will not have a parentand subsequent commits will have a parent, but when a commit is the result of merging several changes together, it will have several parents.

A branch is simply a movable pointer to one of these commits; you already know master, the default branch. The way we have been working, master will point to the last commit you made, as shown in the following diagram:

Branching in Git has a minimal overhead as the only thing it does is create a new pointer to a certain commit. In the following diagram, we create a new branch called test:

We can work on test for a while, go back to master, and then work on something different. Our repository will look something like this:

Someone in the team decides it is time to bring the awesome changes made on test over to master; it is now merging time! A new commit object is created, with the last commits from master and test as parents. Finally, the master branch pointer moves forward so that it points to the new commit. Easy as pie!

As we mentioned, this is not intended to be a comprehensive guide on Git but a mere introduction instead. If you are dying out of curiosity, I will wholeheartedly recommend Pro Git, which is freely available online under a Creative Commons license at http://git-scm.com/book.

The .gitignore file we created earlier contains a list of rules that tell Git which files we are not interested in. Files under this branch of the directory tree that match the patterns and are not committed to the repository just yet, will not appear as candidates when running git status on the Source Tree Working Copy Changes panel.

Typically, you will want to ignore specific files, that is, every file with a specific extension or anything that is under a certain folder. The syntax for these, in the same order, is quite simple:

/game/doc/doc.pdf
*.jar
/game/game-core/bin

SourceTree lets us add files and paths to .gitignore very easily. Select the file you want to add to the ignore list from the Working Copy Changes panel, and right-click and select Ignore. A new modal window will appear giving you the options to ignore just this file, all the files with this extension, or everything placed under a certain folder from the file's path. Once you select the option you want, click on OK, as shown in the following screenshot: