LibGDX Game Development By Example

Before I dive into what LibGDX is, here is how LibGDX describes itself. From the LibGDX wiki—https://github.com/libgdx/libgdx/wiki/Introduction:

So what does that actually mean? What can LibGDX do for us game-makers that allows us to focus purely on the gameplay?

To begin with, LibGDX is Java-based. This means you can reuse a lot, and I mean a lot, of tools that already exist in the Java world.

I can imagine a few of you right now must be thinking, "But Java? For a game? I thought Java is supposed to be slow". To a certain extent, this can be true; after all, Java is still an interpreted language that runs in a virtual machine. However, to combat the need for the best possible performance, LibGDX takes advantage of the Java Native Interface (JNI) to implement native platform code and negate the performance disadvantage. One of the beauties of LibGDX is that it allows you to go as low-level as you would like. Direct access to filesystems, input devices, audio devices, and OpenGL (via OpenGL ES 2.0/3.0) is provided. However, the added edge LibGDX gives is that with the APIs that are built on top of these low-level facilities, displaying an image on the screen takes now a days only a few lines of code.

I am happy to wait here while you go and check it out.

Impressive list of features, no?

So, how cross-platform is this gaming platform? This is probably what you are thinking now. Well, as mentioned before, games are being delivered on many different platforms, be it consoles, PCs, or mobiles.

LibGDX currently supports the following platforms:

That is a pretty comprehensive list. Being able to write your game once and have it delivered to all the preceding platforms is pretty powerful.

At this point, I would like to mention that LibGDX is completely free and open source. You can go to https://github.com/libGDX/libGDX and check out all the code in all its glory. If the code does something and you would like to understand how, it is all possible; or, if you find a bug, you can make a fix and offer it back to the community.

Along with the source code, there are plenty of tests and demos showcasing what LibGDX can do, and more importantly, how to do it. Check out the wiki for more information:

"Who else uses LibGDX?" is quite a common query that comes up during a LibGDX discussion. Well it turns out just about everyone has used it. Google released a game called "Ingress" (https://play.google.com/store/apps/details?id=com.nianticproject.ingress&hl=en) on the play store in 2013, which uses LibGDX. Even Intel (https://software.intel.com/en-us/articles/getting-started-with-libgdx-a-cross-platform-game-development-framework) has shown an interest in LibGDX. Finally, I would like to end this section with another quote from the LibGDX website:

This means that you can use the available tools if you want to; if not, you can dive deeper into the framework and create your own!

We know by now that LibGDX is this awesome tool for creating games across many platforms with the ability to iterate on our code at superfast speeds. But how do we start using it?

Thankfully, some helpful people have made the setup process quite easy. However, before we get to that part, we need to ensure that we have the prerequisites installed, which are as follows:

Not that big a list! Follow the given steps:

At the time of writing, Android Studio has just been released. Android Studio is an IDE offered by Google that is built upon JetBrains IntelliJ IDEA Java IDE. If you feel comfortable using Android Studio as your IDE, and as a developer who has used IntelliJ for the last 5 years, I suggest that you at least give it a go. You can download Android Studio + Android SDK in a bundle from here:

http://developer.android.com/sdk/index.html

Alternatively, if you plan to use a different IDE (Eclipse or NetBeans, for example) you can just install the tools from the following URL:

http://developer.android.com/sdk/index.html#Other

You can find the installation instructions here:

https://developer.android.com/sdk/installing/index.html?pkg=tools

However, I would like to point out that the official IDE for Android is now Android Studio and no longer Eclipse with ADT.

For the sake of simplicity, we will only focus on making games for desktops for the greater part of this book. We will look at exporting to Android and iOS later on.

Once the Android SDK is installed, it would be well worth running the SDK manager application; so, finalize the set up.

If you opt to use Android Studio, you can access this from the SDK Manager icon in the toolbar. Alternatively, you can also access it as follows:

The following screen might appear:

As a minimum configuration, select:

Let them download and install the selected configuration. Then that's it!

Well, not really. We just need to set the ANDROID_HOME environment variable. To do this, we can open up a command line and run the following command:

Phew! With that done, we can now move on to the best part—creating our first ever LibGDX game!

Follow the given steps to create your own project:

Before we hit the Generate button, let's just take a look at what we are creating here:

Next is the version of LibGDX we want to use. At time of writing, the version is 1.5.4.

Now, let's move on to the subprojects. As we are only interested in desktops at the moment, let's deselect the others.

Finally, we come to extensions. Feel free to uncheck any that are checked. We won't be needing any of them at this point in time. For more information on available extensions, check out the LibGDX wiki (https://github.com/libgdx/libgdx/wiki).

Once all is set, let's hit the Generate button!

There is a little window at the bottom of the UI that will now spring to life. Here, it will show you the setup progress as it downloads the necessary setup files.

Once complete, open that command line, navigate to the directory, and run your preferred tree command (in Windows, it is just "tree").

Hopefully, you will have the same directory layout as the previous image shows.

The astute among you will now ask, "What is this Gradle?" and quite rightly so. I haven't mentioned it yet, although it appears twice in our projects directory.

What is Gradle?

Well, Gradle is a very excellent build tool and LibGDX leverages its abilities to look after the dependencies, build process, and IDE integration. This is especially useful if you are going to be working in a team with a shared code base. Even if you are not, the dependency management aspect is worth it alone.

Anyone who isn't familiar with dependency management may well be used to downloading Java JARs manually and placing them in a libs folder, but they might run into problems later when the JAR they just downloaded needs another JAR, and so on. The dependency management will take care of this for you and even better is that the LibGDX setup application takes care of this for you by already describing the dependencies that you need to run!

Within LibGDX, there is something called the Gradle Wrapper. This is essentially the Gradle application embedded into the project. This allows portability of our project, as now if we want someone else to run it, they can.

I guess this leads us to the question, how do we use Gradle to run our project? In the LibGDX wiki (https://github.com/libgdx/libgdx/wiki/Gradle-on-the-Commandline), you will find a comprehensive list of commands that can be used while developing your game.

However, for now, we will only cover the desktop project.

What you may not have noticed is that the setup application actually generates a very simple "Hello World" game for us. So, we have something we can run from the command line right away!

Let's go for it!

On our command line, let's run the following:

• On Windows: gradlew desktop:run

• On Linux and Mac OS X: ./gradlew desktop:run

  The following screen will appear once you execute the preceding command:

  

You will get an output similar to the preceding screenshot. Don't worry if it suddenly wants to start downloading the dependencies. This is our dependency management in action! All those JARs and native binaries are being downloaded and put on to classpaths. But, we don't care. We are here to create games!

So, after the command prompt has finished downloading the files, it should then launch the "Hello World" game.

Awesome! You have just launched your very first LibGDX game!

Although, before we get too excited, you will notice that not much actually happens here. It is just a red screen with the Bad Logic Games logo.

I think now is the time to look at the code!

So far, we have launched the "Hello World" game via the command line, and haven't seen a single line of code so far. Let's change that.

To do this, I will use IntelliJ IDEA. If you are using Android Studio, the screenshots will look familiar. If you are using Eclipse, I am sure you will be able to see the common concepts.

To begin with, we need to generate the appropriate IDE project files. Again, this is using Gradle to do the heavy lifting for us.

Once again, on the command line, run the following (pick the one that applies):

Now, Gradle will have generated some project files. Open your IDE of choice and open the project.

Once the project is open, have a poke around and look at some of the files. I think our first port of call should be the build.gradle file in the root of the project. Here, you will see that the layout of our project is defined and the dependencies we require are on display.

It is a good time to mention that going forward, there will be new releases of LibGDX, and to update our project to the latest version, all we need to do is update the following property:

gdxVersion = '1.6.4'

Now, run your game and Gradle will kick in and download everything for you!

Next, we should look for our game class, remember the one we specified in the setup application—MyGdxGame.java? Find it, open it, and be in awe of how simple it is to display that red screen and Bad Logic Games logo. In fact, I am going to paste the code here for you to see how simple it is:

public class MyGdxGame extends ApplicationAdapter {
  SpriteBatch batch;
  Texture img;
  @Override
  public void create () {
    batch = new SpriteBatch();
    img = new Texture("badlogic.jpg");
  }

  @Override
  public void render () {
    Gdx.gl.glClearColor(1, 0, 0, 1);
    Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT);
    batch.begin();
    batch.draw(img, 0, 0);
    batch.end();
  }
}

We will cover what all this means in the next chapter, but, essentially, we can see that when the create() method is called, it sets up a SpriteBatch batch and creates a texture from a given JPEG file. Then, on the render() method, this is called on every iteration of the game loop; it covers the screen with the color red, then it draws the texture at the (0, 0) coordinate location.

Finally, we will look at the DesktopLauncher class, which is responsible for running the game in the desktop environment. Let's take a look at the following code snippet:

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

The preceding code shows how simple it is. We have a configuration object that will define how our desktop application runs, setting things like screen resolution and framerate, amongst others. In fact, this is an excellent time to utilize the open source aspect of LibGDX. In your IDE, click through to the LwjglApplicationConfiguration class. You will see all the properties that can be tweaked and notes on what they mean.

The instance of the LwjglApplicationConfiguration class is then passed to the constructor of another class LwjglApplication, along with an instance of our MyGdxGame class.

Finally, those who have worked with Java a lot in the past will recognize that it is wrapped in a main method—a traditional entry point for a Java application.

That is all that is needed to create and launch a desktop-only LibGDX game.

In this chapter, we looked at what LibGDX is about and how to go about creating a standard project, running it from the command line and importing it into your preferred IDE ready for development.

Coming up in the next chapter, we will look at making our very first LibGDX-based game! We will take a very well known old mobile game and recreate it in LibGDX. We will also introduce the game cycle concept along with rendering our own textures to the screen, move them, and access input detection.