LibGDX Game Development Essentials

By Juwal Bose
  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies

About this book

This book focuses on teaching LibGDX and its incredible features with a balanced mix of theory and practice. As you proceed through the book, you will create a 2D game in parallel and work on active coding as well. The source code of the game and all the experiments that are done in the book are also provided to get you started quickly and easily.

The game you will develop is a simple one, aimed at helping beginners learn the basics from start to finish. You will develop the complete game and as a next step you will integrate the Box2D physics engine by replacing the existing code. The book teaches you how to create GUI elements using Scene2D and helps you with everything that is involved, from the creation to the publishing of a game. In later chapters, you will learn about 3D in LibGDX and 3D physics using Bullet. The final chapter details the process involved in publishing the game to Google Play, Apple App Store, PC, and the Web.The book covers all the relevant topics of LibGDX game development but makes sure that even a beginner can easily follow the development with the help of sample code and illustrations.

Publication date:
December 2014
Publisher
Packt
Pages
216
ISBN
9781784399290

 

Chapter 1. Wiring Up

In this chapter, we will lay the ground work to facilitate our plan of creating a game like Flappy Bird for multiple platforms, including Android, iOS, PC, and the Web. You might wish to jump right in and start designing the game, but that is not the case with LibGDX. There are lots of things to be done before we could start to code. This chapter deals with the setting up of LibGDX for a cross-platform project. This is done on a development environment configured for Android development. We will cover the following topics:

  • Installing Java Development Kit (JDK)

  • Installing Eclipse for Java

  • Installing Android SDK

  • Installing Google Web Toolkit (GWT) SDK

  • Installing all relevant Eclipse plugins, such as Gradle, Android Development Tool (ADT), Google App Engine (GAE), GWT, and RoboVM

  • Using the LibGDX Gradle setup app to create our first LibGDX project

  • Exploring LibGDX demos and tests

 

Getting started


Hope I didn't scare you with all those abbreviations. The majority of what we will do in this chapter will only need to be done once, as it is required to set up your development environment. Once it is done, we can forget about it and focus on creating wonderful games. I will be using a Mac-based development setup throughout this book, but the process is similar for Windows as well. The added benefit that Mac provides is the ability to deploy to iOS as well. In the first part, we will set up a Java development environment that will be very simple for all our Java developers. This can be accomplished by setting up Eclipse, IntelliJ, or NetBeans IDEs, but we will be focusing on Eclipse throughout this book. This does not mean that this way is superior to the others but we've used it just because Eclipse is the most widely used Java IDE and the majority of our potential readers should have worked with Eclipse one way or another.

Note

If you need to use another IDE, please check the LibGDX wiki page at http://libgdx.badlogicgames.com/documentation.html#gettingstarted.

Setting up the Java development environment

Our first step will be to install the Java Development Kit (JDK) if the development PC does not have it. For all of the tools, applications, and SDKs that we will use, there are different versions for Windows and Mac. Your browser will automatically take you to the relevant download in most cases, but be sure to double check that you are indeed downloading the right version. Also, there are different versions for 32-bit and 64-bit processors; make sure that you download the right one for your development PC.

You can download the latest version of JDK from Oracle's site at http://www.oracle.com/technetwork/java/javase/downloads/index.html.

At the time of writing this book, the latest version is JDK 8u5 and the following screenshot shows how the different versions are listed:

Once you download the relevant file, go ahead and install it on your machine. Now, your machine is ready to be used for Java-based application development.

On a Windows machine, you may need to set the value of the environment variable JAVA_HOME to the installation path of the JDK after installation. We can check this by running the following command in the command prompt:

C:\Users\admin>java -version

If the system displays the version details as follows, then Java is installed correctly:

java version "1.7.0_25"
Java(TM) SE Runtime Environment (build 1.7.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 23.25-b01, mixed mode)

Otherwise, we need to set up the Java environment variable. To find the correct path, go to C:\Program Files (x86)\Java\. You should see a folder with the jdk extension in its name. The complete path should be similar to the following one:

C:\Program Files (x86)\Java\jdk1.8.0_05

Follow the given steps on a 64-bit Windows machine with 32-bit Java installed to set the environment variable:

  1. Click on the Windows Start button, right-click on Computer, select Properties, and open control panel system window.

  2. Click on Advanced system settings on the left-hand side of the Control Panel window to open the System Properties window.

  3. Next, click on the Environment Variables… button and click on the New... button at the top that corresponds to User variables for <USERNAME>. A window with the title New User Variable will appear.

  4. Now, fill in the two text fields. Use JAVA_HOME in the Variable name field and the JDK path you found out earlier in the Variable value field.

Installing Eclipse

Next, we will need to install our IDE of choice: Eclipse. The latest version of Eclipse can be found at http://www.eclipse.org/downloads/. We need to select Eclipse for Java developers from the multitudes of flavors in which it is available. At the time of writing, the latest Eclipse build is Luna, as shown in the following screenshot:

Once you have downloaded the relevant IDE, go ahead and install it on your machine. Now, we are all set to write and compile the Java code. It's time to set up the Android development environment.

 

Setting up the Android development environment


To use our Eclipse IDE for Android development, we need to install two things: the Android SDK and the Android ADT plugin. Android SDK can be downloaded as a compressed archive from http://developer.android.com/sdk/index.html. It will be listed under GET THE SDK FOR AN EXISTING IDE. The archive can be extracted to a location on your hard drive which needs to be linked from within Eclipse. The following screenshot shows the download page where you can see a link to download Eclipse ADT, which is a complete package for Android development. If you are setting up Eclipse for the first time, then downloading Eclipse ADT is the way to go; however, in this chapter, we are assuming that Eclipse is already installed.

Installing the ADT plugin and linking the Android SDK with Eclipse

The ADT plugin connects with our Android SDK and keeps it up to date. It also has the SDK Manager and Android Virtual Devices that are used to emulate Android devices. We need to fire up Eclipse so that we can install the plugin. For those who are not aware of the process of installing plugins in Eclipse, the following screenshot will help. We need to select Install New Software... from the Help section.

In the new window that pops up, enter the URL https://dl-ssl.google.com/android/eclipse/ in the section that says type or select a site and press Enter. We need to select all available items and proceed with the installation. Once the plugin is successfully installed, we need to restart Eclipse. After restarting, Eclipse will ask you for the Android SDK location; you can also set it up by navigating to Window | Preferences | Android. Once the Android SDK location is set, the SDK Manager will check our installation to find missing items. It will prompt you to download the latest Android SDK platform and Android platform tools. Check out the selected items in the Download dialog box. We need to have the recommended Android build tools and SDK platform. It is safe to not alter the recommended setting and allow the downloader of Eclipse to download all the required files. The following screenshot shows the update in progress:

Now we are all set to develop Android applications.

Installing the LibGDX support plugins

LibGDX uses GWT plugin to publish HTML5/JavaScript, which is the web platform. GWT includes the GWT SDK and Google App Engine. The other support plugins that we need are RoboVM and Gradle.

RoboVM is used to compile the LibGDX project on the iOS platform. Gradle is a dependency management and build system that wires our LibGDX game together.

Setting up GWT

From within Eclipse, launch the Install New Software... window, input the following link, and install the GWT plugin:

https://dl.google.com/eclipse/plugin/4.4

The last part of the link is actually the Eclipse version and the preceding link is for Version 4.4.x. Select the checkboxes to install Google Plugin for Eclipse, Google App Engine SDK, and Google Web Toolkit SDK. Once the plugin is installed, we need to restart Eclipse.

Installing the RoboVM plugin

iOS development is only possible if we are using a Mac machine for development. We will also need Xcode, the Mac IDE for support. RoboVM is the brainchild of Niklas Therning, a Swedish developer and co-founder of Trillian Mobile AB. RoboVM is used to make Java work on iOS via a Java to Objective-C bridge. RoboVM is open source and stable. Let's all take a few minutes to appreciate this wonderful effort by learning more about RoboVM (http://www.robovm.com/).

Mac users can go ahead and install the RoboVM plugin from http://download.robovm.org/eclipse/. After restarting, we are now all set to deploy our games on the Apple iOS platform as well.

Installing the Gradle plugin

Gradle is a dependency management system and is an easy way to pull in third-party libraries into your project without having to store the libraries in your source tree. Instead, the dependency management system relies on a file in your source tree that specifies the names and versions of the libraries you need to be including in your application.

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 and store them in a directory outside of your project.

Note

If you want to read more about Gradle and get to know how it benefits the LibGDX setup, visit https://github.com/libgdx/libgdx/wiki/Improving-workflow-with-Gradle.

Gradle also has a build system that 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. More information can be found at http://www.gradle.org/.

At this point, we are very comfortable adding new plugins to Eclipse. Fire up the new software window to add the Gradle plugin from the link http://dist.springsource.com/release/TOOLS/gradle. After installation, restart Eclipse and that's the end of our setup.

 

The LibGDX Gradle combo


I know that you are wondering how we reached the end of our setup without installing anything related to LibGDX but everything else out there. The LibGDX installation will be handled by Gradle automatically, and we will be using a helper application to create all the dependencies and the project structure. Such a LibGDX Gradle combo requires an Internet connection while creating the project, as Gradle needs to load all the necessary dependencies, files, and libraries on the fly while setting up the project for the first time. Personally, I am not a fan of this as I come from a country where a good Internet connection is still a luxury. For those of you who are in a similar situation, the alternative way will be to download all dependencies and wire them all up as required. This is a complicated task although we used to do it during the initial days of LibGDX.

Let's start creating our first Gradle-based LibGDX project. We will be following the steps explained in the LibGDX wiki page, which can be found at https://github.com/libgdx/libgdx/wiki/Project-Setup-Gradle.

Using the Gradle setup application

We need to use a Java application with the Gradle setup to create Gradle-based LibGDX projects. This setup file can be found at http://libgdx.badlogicgames.com/download.html.

Note

A direct link to the setup application is http://bitly.com/1i3C7i3.

The setup application has to be stored for easy access, as we will need it when we create new LibGDX projects. The purpose of the application is to create all platform-specific Eclipse projects, such as desktop, Android, iOS, and JavaScript applications. It also links with all the necessary dependency libraries and the latest version of LibGDX. The following screenshot shows the Gradle project structure that clearly explains how the different projects are created under the relevant folders:

A Hello World project

Let's launch the gdx-setup.jar Gradle setup application. The following screenshot shows how I have populated the options for our Hello World project:

We need to specify a name for our project, which is Hello World in this case. Then, we need to specify a package name for our project. In my case, I am using my company's package name but you can use any unique package name. It's time to specify our main class name; take care that there are no spaces in between. While setting the destination project, make a new folder within your Eclipse Workspace folder so that there are no possible conflicts between Gradle files and Eclipse workspace metadata files. In this case, I have specified FirstGradleProject. Link the Android SDK and select the version of LibGDX that you will use.

In the Sub Projects section, we need to select the platforms that we want the project to target. Note that we will need a Mac to compile an iOS build.

The Extensions section will link any of the standard LibGDX libraries or packages available. It is always safe to select the options in this stage rather than hacking into the project later on. For our Hello World app, we do not need any of these extensions. Hit the Generate button and your LibGDX Gradle project structure will be created.

Alternatively, we can create an Eclipse-specific project structure by clicking on the Advanced button, enabling the Eclipse checkbox, and clicking on Save. If the project is created this way, then we need to import it as a normal Eclipse project by navigating to File | Import | General | Existing Projects to Workspace. This process will need an active Internet connection to load the files needed by the setup application.

Importing Gradle projects to Eclipse

It's time to import our projects into Eclipse by navigating to File | Import | Gradle | Gradle Project. Browse the root folder, FirstGradleProject, and hit the Build Model button. This step is very important, as you may not see your projects without this. Gradle will download a few necessary files based on our project, and it will take a while before you see your projects listed as shown in the following screenshot:

Go ahead and select all the projects and click on Finish to load them to Eclipse. At this point Gradle will load all the dependencies as per our selection in the setup application. This is where Gradle will actually load the LibGDX packages and extensions. The following screenshot shows the process:

Running the project

Everything should be wired properly and all projects are good to go at this point. One issue that may pop up is that the Android project may have a red cross indicating that the proper Android SDK is missing. This happens all the time, but the fix is straightforward. Right-click on the Android Project folder to select its properties. Then, select the proper Android target version under the Android section in the window that pops up. This will remove the error. Congratulations! You can now run your projects. The following screenshot shows how to remove the Android error:

In order to run the desktop project, right-click on the Hello World desktop project, select Run As, and click on Java Application. A popup may ask you to select the application class and you should select DesktopLauncher to run the app. The following window will pop up, which means we have successfully created and run our first Gradle-based LibGDX application:

Running the application on your Android device is also very easy. Connect your Android device to the development PC via USB and make sure USB debugging is enabled in the device's settings.

Tip

USB debugging can be enabled by navigating to Settings | Developer options | USB debugging.

In order to see the connected device from within Eclipse, you need to enable the Devices view. In Eclipse, go to Window | Show View | Other. Then, select Devices from the Android section. A new tab showing the connected device will be added to Eclipse. For Windows, we need to install the respective drivers for the connected phone to show up, but on Mac the connected device would be automatically detected.

Once you see your device listed in the Devices view, right-click on the Hello World-android project, select Run as, and click on Android Application. Eclipse will prompt you to select how to launch the Android app. You can select to launch on a device or on a Android Virtual Device (AVD) if you have set one up already. Select to launch the application on the device and then the application should show up on your Android device. Eclipse will show the LogCat view, which shows the application status:

In order to run the iOS project, you need to be on a Mac and should have Xcode Version 5 or above installed. Xcode can be downloaded free from the Mac App Store. It provides the necessary frameworks and the iOS Simulator tool. Right-click the Hello World-ios project, select Run As, and select iOS Simulator App. You can select either of the simulator options, iPad or iPhone. This will start the RoboVM cross compilation and would take some time for entire classes to be compiled. Eventually, you will see the app running on the iOS Simulator.

Tip

In some cases, you may run out of memory while RoboVM works on the compiling. You may need to increase the memory heap sizes for Eclipse in the eclipse.ini file, as follows:

-Xms512m
-Xmx2048m

Getting the HTML project to run is the trickiest part of them all. We need to follow exactly what the LibGDX wiki tell us to do. Right-click on the Hello World-html project, select Run As, and click on External Tools Configuration. Create a new configuration by double-clicking the Program entry in the left sidebar. Give the configuration a name, for example, GWT SuperDev. Set the location field to the gradlew.bat (Windows) or gradlew (Linux, Mac) file. Set the working directory to the root folder of your project and specify html:superDev as the argument. Click on Apply and then click on Run.

Wait until you see the message The code server is ready in the console view. After that, go to the URL http://localhost:8080/html. You can leave the server running. If you change the code, simply click on the SuperDev Refresh button in the browser. This will recompile your app and reload the site.

Check out this screenshot to see the app running on a browser:

 

Exploring the project


That was some heavy lifting; now we can take a break to explore the project in detail. You are seeing an image in the bottom-left corner of the app window. Let's see how we got this output. The core code logic will always be present in the project's src folder, which is the Hello World-core src folder in our case. We can find the HelloWorld.java main class inside the specified package; open it up. This class extends the ApplicationAdapter class, which in turn implements the ApplicationListener interface. These classes have a few methods that align with the Android application life cycle methods: create, pause, resume, dispose, render, and resize.

The HelloWorld class is a very simple class with only two variables and two overridden functions:

SpriteBatch batch;
Texture img;
create ();
render();

The SpriteBatch class is a class that facilitates the efficient drawing of images on the screen. The create function, which will be called when the application is launched, just creates a new SpriteBatch class and a Texture class named img that loads a texture from the external asset badlogic.jpg. The render function is called continuously and can be considered as our game loop. It clears the screen and draws the texture onto screen at the coordinates (0,0). This means the origin of the coordinate system in LibGDX is the bottom-left corner of the screen, as we can see that the image is placed there. We will revisit the graphics package in the next chapter.

The following code clears the screen before each draw call:

Gdx.gl.glClearColor(1, 0, 0, 1);
Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT);

The next bit of code starts the batch drawing, draws the texture at the specified coordinates, and closes the batch drawing:

batch.begin();
batch.draw(img, 0, 0);
batch.end();

The only thing missing is the external image file, as we won't be able to find it among the core project files. LibGDX follows the convention to store all asset files within the assets folder in the Android project. Hence, we can find badlogic.jpg within the assets folder in the Hello World-android project. The assets folder is shared among all the other projects. All the other projects are simple wrapper projects that have platform-specific code and data that will launch the code in the core project. You can easily explore the projects on your own, but we will revisit specific platforms in the final chapter.

Displaying the Hello World text

Let's alter the code to display our Hello World text thereby officially declaring the start of our quest of mastering LibGDX. The easiest way to do this will be to draw some text on the screen using the BitmapFont class. A bitmap font is created using an external tool like Hiero (https://github.com/libgdx/libgdx/wiki/Hiero) where a font is converted into a bitmap with all the letters in a fixed size along with a .fnt file that stores the presentation data. To make things easier, let's use fonts from the LibGDX test project. You can download verdana39.fnt and verdana39.png from https://github.com/libgdx/libgdx/tree/master/tests/gdx-tests-android/assets/data. As explained, we need to place these files in the assets folder within the Hello World-android project.

Now, let's edit the code in HelloWorld.java in the core project to remove the texture drawing and to add our text display. The code is as follows:

public class HelloWorld extends ApplicationAdapter 
{
  SpriteBatch batch;
  BitmapFont font;

  @Override
  public void create () 
  {
    batch = new SpriteBatch();
    font = new BitmapFont(Gdx.files.internal("verdana39.fnt"),
    Gdx.files.internal("verdana39.png"), false);
    font.setColor(Color.RED);
  }

  @Override
  public void render () 
  {
    Gdx.gl.glClearColor(0, 0, 0, 1);
    Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT);
    batch.begin();
    font.draw(batch, "Hello World", 200, 200);
    batch.end();
  }
  @Override
  public void dispose() 
  {
    batch.dispose();
    font.dispose();
  }
}

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com.If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

The BitmapFont class requires the .fnt and .png file to create the font. In the render function, we draw the Hello World text at the coordinates (200,200). I have also added an overridden dispose function that releases the memory by destroying the created instances. Congratulations! You have our shining Hello World text.

This method may not always be suitable to display text, as we may need to show text in multiple sizes. In such cases, we will use the Freetype extension that enables us to use a ttf font to create bitmap fonts of different sizes dynamically at runtime. We will revisit fonts in detail in Chapter 4, Bring in the Extras!

Running demos

For the adventurous among you, this is the chance to dive deeper into LibGDX by checking out the fully functional game demos. You can find the links for these games at https://github.com/libgdx/libgdx/wiki/Running-Demos. The most interesting one is the example project similar to Flappy Bird, The plane that couldn't fly good. The link to this project is https://github.com/badlogic/theplanethatcouldntflygood. In order to explore this project, we need to clone the repository in Git or download it on our PC. Once downloaded, we can import it to Eclipse as a Gradle project.

Tip

The local.properties file may be missing from the downloaded project's folder. Just copy the file from our FirstGradleProject root folder. This file sets the Android SDK location in our PC.

This is a very simple project to get you started and can be used as a starter code for your Flappy Bird game. The whole code is in the single file PlaneGame.java in the core project.

Running tests

The LibGDX tests project is a treasure trove of goodies. There are numerous small tests exploring the different features of LibGDX. These tests are the ideal way to get started with LibGDX and they also let you learn new things in an easy way. Alternatively, they act as a source of functional sample code that we can simply copy and paste for our own use cases. The LibGDX wiki entry for running these tests advises us to use Ant to set up these tests on our PC. The link is https://github.com/libgdx/libgdx/wiki/Running-Tests. The tests can be found at https://github.com/libgdx/libgdx/tree/master/tests/gdx-tests/src/com/badlogic/gdx/tests.

You can temporarily set up Ant after downloading it from http://ant.apache.org/bindownload.cgi. Assuming that it is extracted to /Setups/apache-ant-1.9.4, we can temporarily install ANT using the terminal on a Mac. In the terminal, enter the following code:


export ANT_HOME=/Setups/apache-ant-1.9.4
export PATH=${PATH}:${ANT_HOME}/bin

In the terminal, navigate to the folder where LibGDX Git project is cloned. Run the Ant command to fetch dependencies:

ant -f fetch.xml

This will download all the LibGDX dependencies for all the projects. Later, we can import all these projects into Eclipse by navigating to Import | Existing Projects into Workspace. After importing the Demo and Tests projects, our Package Explorer in Eclipse will look something like this:

The test examples are contained in the gdx-tests project. This project only contains the source code. To actually start the tests on the desktop, you have to run the LwjglTestStarter class contained in the gdx-tests-lwjgl project. To run the tests on Android, simply fire up the gdx-tests-android project in the emulator or on a connected device! To run the tests in your browser, fire up the gdx-tests-gwt project. For iOS, you can start the gdx-tests-robovm project. Play with them.

The alternate LibGDX setup

Previously, LibGDX had to be manually wired up and was a complicated process. Later, the French developer Aurelien Ribon created a gdx-setup-ui tool that automated this process. Aurelien Ribon is a rock star Java developer who has released lots of goodies that can be accessed on his blog at http://www.aurelienribon.com/blog/.

This non-Gradle-based system still works but is not recommended or supported at present. The blog post with all the details of Version 3.0.0 can be found at http://www.aurelienribon.com/blog/2012/09/libgdx-project-setup-v3-0-0/. The gdx-setup-ui interface can be downloaded from https://github.com/libgdx/libgdx-old-setup-ui.

The app will need an Internet connection to download the LibGDX files; this screenshot shows it in action:

 

Summary


This chapter explained a lot of theory that lays the solid foundation for all our development. This chapter will serve as a reference to set up your development environment if you move to a new workplace or get a new laptop. You learned to set up Eclipse-based Android and Java development environments. We used the gdx-setup tool to create a Gradle-based LibGDX project, which was successfully imported to Eclipse with the help of associated support plugins. We explored the project structure of a typical LibGDX cross-platform project.

We successfully executed the Hello World project on desktop, Android, iOS, and the browser. Some minor editing of the code helped us display the text Hello World using the BitmapFont class. It is very important to successfully import the LibGDX Demo and Tests and we used Ant to get them running.

In the next chapter, we will start with the graphics package in LibGDX and get started with our game.

About the Author

  • Juwal Bose

    Juwal Bose is a game developer, game designer, and technology consultant from the incredibly beautiful state of Kerala in India. He is an active figure in social media and game development SIGs, and he never misses a chance to speak at technical conferences and BarCamps. He conducts technical workshops for engineering students at professional colleges as part of open source initiatives. Juwal is the Director at Csharks Games and Solutions Pvt. Ltd., where he manages research and development, training, and pipeline integration.

    He has been developing games since 2004 using different technologies, such as ActionScript, Objective-C, Java, Unity, LibGDX, Cocos2D, OpenFL, Unity, and Starling. His team has created more than 400 games to date, and many of the job management games are listed at the top of leading portals worldwide. He was involved in the development of more than 20 LibGDX games, primarily for the Android platform.

    Juwal writes game development tutorials for GameDevTuts+ and manages the blog of Csharks. His isometric tutorial for GameDevTuts+ was well received and is considered a thorough guide for developing tile-based isometric games. This is his second book and he aims to keep writing and sharing his 10 years of game development experience through more books. His first book, Starling Game Development Essentials, Packt Publishing, was on another exceptional cross-platform game development framework—Starling.

    Juwal is a voracious reader and likes to travel. His future plans also include writing fiction.

    Browse publications by this author

Recommended For You

LibGDX Game Development By Example

Learn how to create your very own game using the libGDX cross-platform framework

By James Cook