Click here to Skip to main content
Click here to Skip to main content

Create your first Android Game with libgdx

, 6 Jan 2014
Rate this:
Please Sign up or sign in to vote.
Create your first Android Game with libgdx

Android libgdx games

Introduction

The last couple of years a lot of cross-platform game frameworks have emerged. These frameworks came to fill a gap that due to the growing interest for mobile games and the diversity of the platforms kept getting bigger and bigger. And today is easier than ever before to adopt a game engine and develop your first game. The most difficult part is to select the proper gaming framework. However, from all the available options there is one that clearly stands out: libgdx. These are some of the features of libgdx that make it one of a kind:

  • Cross platform: Deploys on Desktop, Android, HTLM5 and iOS (with the aid of RoboVM)
  • You can debug and test your game in a desktop environment and then deploy it for the Android platform with almost zero effort.
  • Great performance
  • Good documentation, excellent community support
  • Many features for 2D and 3D games.
  • Friendly Open Source license (Apache 2.0). It can be freely used for commercial applications.

In this article I am going to provide an overview of the libgdx. A simple 2D game, called "Fruit Catcher" will be used as an example. In this game fruits fall off the sky. You carry a basket and you move it around, either by touching the screen or sliding your phone, to catch them. To make it more interesting seasonal fruits worth more points. You of course know that you must prefer seasonal fruits! Since, as I said, libdgx documentation is very good, I am not going to cover basic information here. You can read how to set up and run a project in the Wiki. You can also read how to create a simple game and how to extend it to use Game Screens. Here I am going to cover some important game concepts and also provide tips that will help you move from a sample game to one that is ready to be deployed in the market. Although libgdx is a cross-platform framework, emphasis will be given on deploying for the Android platform.

Before starting writing code however, we must cover two topics that are important for game designing.

Game Resources

I suspect that most of you reading this are developers and not designers. In my opinion however creating a game is more an art than a development process. Great games usually stand out because of their good graphics and nice sound and music. That doesn't mean that a single developer has no luck of creating a game. It is difficult for a developer to create all the resources from scratch, but it is much easier to locate the appropriate resources online and then use the appropriate tools to adapt them. And because no one that reads this is a lawyer, this a list of URLs that provide resources you can freely use in your games:

  • Images: Openclipart. Public domain SVG graphics.
  • Sounds: freesound. Creative Commons Licensed sounds. Pay attention to the individual sound license.
  • Fonts: Font Squirrel. It may come as a surprise, but you can't use native fonts in your games. Font Squirrel provides fonts that are free for commercial use. libgdx provides a tool that will allow you to easily integrate these fonts.

This list is of course not exhaustive. There are other resource centers as well. When searching however, take note of the license. Do not just use the first image you find in the Web. You need to make sure you have the right the use it. Also, the above list doesn't cover other types of resources, such as 3D models.

Tools

After you have found the appropriate resources online (or having paid a designer to create them for you), you are still not ready to start coding. Most of the times the resources will need some editing. There is a basic level of designing that you can avoid doing. The good thing is that this kind of design is actually fun and that are free tools you can use:

  • Inkscape: Professional vector graphics editor. It is good to design all your images in a vector format. This will allow you to easily resize them for any current or future screen resolution.
  • Gimp: Image manipulation program. It has similar features to Photoshop. Most game engines require bitmap (usually PNG) images. After exporting an image from Inkscape, you may need to do some final touching before incorporating into your games. Gimp's UI isn't that user friendly and requires some time to getting used to. However Gimp is feature-full and there are many tutorials and videos available online.
  • Audacity: Cross-platform software for recording and editing sounds.

All the above tools are free, open-source and of a professional level. They are more than enough for any task you are going to need. Besides the above general tools, there are also many game specific tools. There are tools for creating bitmap fonts, tools for packing many small images to a big one, tools for creating tile maps. libgdx has good support for this king of tools and some of them will be presented later in this article.

Game Main Loop

Games do have some software design patterns of their own. The most ubiquitous of them is of course the game loop. I am sure you have heard of it. The game loop is actually a while-loop, where all the processing is taking place. In this loop you display all images, play sounds, apply physics and game logic. You try to do that as fast as possible. When the loop is finished, it immediately starts over again. The number of times the loop runs in one second equates to "Frame per seconds" (FPS). The highest the FPS is, the more smooth the game will appear to be.

Most game frameworks implement the game loop by providing a function (or method). This method does all the processing and the framework takes care of calling it as fast as possible. Let's call this method the "Loop method". The "Loop method" in pseudo-code is presented below:

void gameMain(float delta) {

    renderWorld();
    
    getUserInput();
    
    update(delta);
}

This pseudo-code also relates to the well known MVC pattern, which is also popular in game development. The "Loop method" accepts a single float argument. This is called delta and is actually the time passed since the last time the loop method was called. You can think of it as the inverse of FPS. That is: delta = 1 / FPS.

The renderWorld method renders all images on the screen. This is the "View" of the game that draws all images in the appropriate locations. All images are drawn every time the loop runs, even if their position hasn't changed. Next the loop reads the user input. This may come from the touch screen, a keyboard, a mouse, the accelerormeter, a gaming pad... Although above it appears to be part of the loop method, it is more common to be implemented as a separate class (the "Controller") that updates the "Model". The last part applies the physics and the game logic. This is where the delta information is needed. The game may require a full physics engine or just some simple object movement and collision detection. In any case a timing information is needed to implement this. In this part stuff like updating the score and checking game over conditions will take place. If you have worked with XNA or MonoGame, you may find this part similar to the Update method. This method actually updates the "Model" or state of the game. In MonoGame special consideration is taken so that the Update method is called in regular intervals, regardless of how long the rendering is taking to execute. In other words the framework always calls the update method, which shouldn't take long to execute, a specific number of times per second and then uses the remaining time to render the world as frequently as possible. libgdx doesn't support a separate update method. Therefore you should implement this pattern yourselves. If the renderWorld takes too long to execute (lower-end device, too many objects to render), it shouldn't be called in every loop, so that the update method is regularly called and the game state remains consistent. If you fail to do so, you may find yourself in a situation where objects fly through obstacles and all kind of strange things happen.

libgdx supports the game main loop pattern through the ApplicationListener interface. This interface defines the following methods:

void create() //Called when the Application is first created.
void dispose() //Called when the Application is destroyed.
void pause() //Called when the Application is paused.
void render() //Called when the Application should render itself.
void resize(int width, int height) //Called when the Application is resized.
void resume() //Called when the Application is resumed from a paused state.

The above methods provide entry points for all events you are going to need to handle in a game's lifecycle. The render method is the main loop method, we have described above. libgdx provides static constructs to read the delta time (Gdx.graphics.getDeltaTime()) and process user input (Gdx.input). Although you can process input directly from inside the render method, libgdx also provides more advanced mechanisms that allow you to implement a separate Controller class (InputProcessor). As explained above a separate update method isn't provided and you would need to implement this pattern yourselves.

From the other ApplicationListener methods the create and dispose methods are very important for the game resources handling. Since in your games you are going to deal a lot with OpenGL resources, garbage collection won't help and you would need to manually dispose of them. We usually allocate resources for the game in the create method. This is called only once, when the game is started. In the dispose method we have our chance to dispose of these resources. Resource handling is of course usually more complicated than this. In order to start a game quickly and avoid out of memory errors, a more complex resource handling is needed. You may need to pre-allocate some resources and de-allocate some of them earlier in low memory conditions. We'll discuss more on this later.

Game Screens

The image below displays the screens of a typical game. The game consists of various screens. Every time only a single screen is being displayed. When developing a game it is very convenient to be able to think in terms of these screens. First implement the initial menu screen, then the game start screen, the main game screen (which is usually the most difficult one), the game over screen and so on.

Game screens

libgdx supports this pattern through the Game abstract class and the Screen interface.

This is a very thin construct and you need to provide implementations both for the Game and the Screen objects. The Game class is nothing more than an ApplicationListener that delegates the rendering to one or more screen objects. This makes it easier to think in Screen terms. It also makes resource handling easier. The Screen interface provides a dispose method, which however isn't called automatically. You should call it yourselves in order to dispose of the screen's resources. This is a good thing, because it allows a more flexible resource handling. A screen may remain pre-loaded so that it can be re-used quickly. In general this pattern will allow you to implement a resource handling service. This service will pre-load resources and it will dispose of the resources that aren't going to be used shortly. For example when going from Level 1 to Level 2, you need to dispose of the Level 1 resources and pre-load the Level 2 ones, while still in the Level screen. A separate service class will be responsible for loading and unloading resources. The Game Screen pattern makes it easy to invoke this service at the appropriate times.

If you look at the game screens, you will definitely notice that most of them are very simple. With the exception of the action screen, all screens just display a message and offer a couple of action points for the users. They are only simple UIs. libgdx provides Scene2d in order to facilitate the creation of such screens. Copying from the libgdx Wiki:

scene2d is well equipped for laying out, drawing, and handling input for game menus, HUD overlays, tools, and other UIs. The scene2d.ui package provides many actors and other utilities specifically for building UIs.

I haven't personally used Scene2d in Fruit Catcher, but I believe that you should consider it for your own applications.

Rendering Images

The following code snippet displays what you need to do in order to render an image to the screen (It is taken from the simple game example in libgdx wiki). First you need to create a camera and a SpriteBatch object in the create method. There you also create Texture objects that you load images in them. In the render method you use the SpriteBatch object to draw the textures. You must not forget to dispose of the textures and the SpriteBatch objects in the dispose method.

Texture bucketImage;

OrthographicCamera camera;
SpriteBatch batch;

@Override
public void create() {
    camera = new OrthographicCamera();
    camera.setToOrtho(false, 800, 480);

    batch = new SpriteBatch();
    dropImage = new Texture(Gdx.files.internal("droplet.png"));
    ...
  
}

@Override
public void render() {
    Gdx.gl.glClearColor(0, 0, 0.2f, 1);
    Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);

    batch.setProjectionMatrix(camera.combined);
    batch.begin();
    batch.draw(bucketImage, bucket.x, bucket.y);
    batch.end();
}
 
@Override
public void dispose() {
    bucketImage.dispose();
    batch.dispose();
    ...
}

Drawing images with libgdx is easy. (If you believe that the above code is complicated, you should do a research about drawing images with OpenGL without the aid of a framework). However, the above code is only appropriate for very simple games. In real situations you would need to add a couple of abstraction layers to your image drawing code.

First of all, if you have a lot of small images, you shouldn't load them one by one. Instead, you should "pack" them into a big image, load this image into a Texture and then select regions from it. The image below depicts the small images in Fruit Catcher all packed into a single one.

game images atlas

libgdx makes it very easy to create packed images. You can do that straight from the desktop project. All you have to do is to add the gdx-tools.jar in the classpath and write a couple of lines of code. This is how I do it in Fruit Catcher. I define the maximum height and width to be 1024. If the images do not fit in one 1024x1024 image, more than one will be created. This will be completely transparent for you, as the code to select a region won't change. The TexturePacker2.process takes all the images from a specific folder, packs them and copies the packed images to the Android project assets folder. It also creates an "atlas" file. This is a simple text file, which contains the locations of the individual images into the packed one. In Fruit Catcher three "atlases" are created: one for the small images, one for text images in English, and one for text images in German.

Settings settings = new Settings();
settings.maxWidth = 1024;
settings.maxHeight = 1024;
TexturePacker2.process(settings, "images", "../FruitCatcher-android/assets", "game");
TexturePacker2.process(settings, "text-images", "../FruitCatcher-android/assets", "text_images");
TexturePacker2.process(settings, "text-images-de", "../FruitCatcher-android/assets", "text_images_de");
 

After you have called the above code, you need to refresh the Android project in order for the changes to be picked up. Also, you should pay attention to a naming convention the TexturePacker2 utility uses in order to support animations. You can name a series of images like this: image_n.png, where n is an integer. Number n actually denotes the frame index. If you have a sprite that consists of a number of frames, this convention will make it easy to load these frames.

 // Create an atlas object
TextureAtlas atlas = new TextureAtlas(Gdx.files.internal("game.atlas"));

// Load Star frame 1
TextureRegion startTexture1 =  atlas.findRegion("star", 1);

// Load Star frame 2
TextureRegion startTexture2 =  atlas.findRegion("star", 2);

// Load Image button
TextureRegion buttonTexture = atlas.findRegion("button");

In complex games, with a lot of images, it may take considerable time to load all the images. What games usually do is to display a "loading" screen in the beginning and start loading the images and other required assets. When everything is loaded, the game can start. There is a delay at the start, which the users can put up with and then the game runs smoothly. libgdx supports this pattern with the aid of AssetManager.

As you've seen loading images isn't so simple in real applications. You may need to use an AssetManager, a TexturePacker or both. You may also need to implement a custom loading and unloading scheme that runs in the in-between screens of your game. For these reasons, I believe that it would be better to create a separate service that will provide all images to other code layers. I call this service ImageProvider in Fruit Catcher. Having this service will allow you to experiment with different loading and unloading techniques without affecting the whole source base. It would really pay off, if you design your game like this from the beginning.

Rendering Text

If you have never developed a game before, it may come as a surprise that special consideration is needed in order to display text. However, you should understand that for performance reasons gaming frameworks use OpenGL and there is no way to combine this with native code that can use system fonts. Luckily, libgdx makes it very easy to create a bitmap font and then use it in your application. libgdx has adopted the Hiero Bitmap Font Tool. This is an open source tool. Previously it was difficult to find a working version of it. Now libgdx maintains it as a tool and you can run it straight from libgdx binaries. Hiero can load any system font and convert into a bitmap font, in a format that libgdx understands. It can also load TTF fonts directly, without having to install them. When working with Hiero pay attention to the license. Only use fonts that you have the right to do so. After you have created the bitmap font, it is very easy to load it and then use it to display text.

// Loading a bitmap font 
BitmapFont font = new BitmapFont(Gdx.files.internal("fonts/poetsen.fnt"),
                                 Gdx.files.internal("fonts/poetsen.png"), false);
                                 
// Draw a string with a SpriteBatch object
font.draw(spriteBatch, line_string, lineX, lineY);

State

Something that you may not realize from the beginning, is that your game must be able to store its state and then resume from it. This is especially important in mobile devices that may be interrupted from a phone call. When the player returns to the game after an interruption, she would expect to find it in the state she had left it. If she was about to achieve a high score and finds out she has to start from the beginning, she would be angry and you should expect some very negative reviews.

Your game must be able to start from the beginning and from a well known state as well. The game must constantly update its state and must persist it in a non volatile location at appropriate times. libgdx provides JSON utilities that will allow you to serialize and deserialize classes in a cross-platform way. In Fruit Catcher there are two separate state classes: GameScreenState that is used to store the state of the current game (number of points collected, time remaining, fruits in the sky) and GameState, which holds information about a game session. Both are saved in the pause method of e game. If you have more complex state objects that take a lot of time to serialize, you should serialize them in regular intervals and not wait for the pause method.

Calling Android Native Code

Calling Android native code may be necessary in some situations:

  • Displaying ads
  • In-app purchases
  • Using native user input
  • Connecting with leaderboards

In the Wiki you can read how to integrate a libgdx game with AdMob. I have used the described techniques to display AdMob ads in Fruit Catcher. However, I needed native code also for getting user's name, when a high score is achieved and for displaying the top 5 of scores. Integration with native code is actually taking place inside AndroidApplication class. This is a class provided by libgdx that extends an Android Activity. In order to call native code from libgdx you should do the following:

  • Create an interface that defines methods as entry points for actions that require calling native code. Your implementation of AndroidApplication will implement this interface. I call this interface GameEventListener. This interface is part of the libgdx and not of the Android project. It is also accessible from the desktop project as well.
  • Your implementation of com.badlogic.gdx.Game will accept a GameEventListener as an argument constructor. This can be passed as null for platforms you don't care to implement native functionality. I need the desktop version of Fruit Catcher for quick debugging and testing. I don't need however displaying ads and high scores for it. I simply pass a null GameEventListener for it. In my Game class I check for null, before calling a GameEventListener method.
  • After the above you will have entry points methods in the AndroidApplication class. These methods will be called by the libgdx engine. Because libgdx doesn't run in the UI thread you can't access the UI from them. Instead you need to use a message handler to post messages that will trigger the appropriate UI action. 

Compiling instructions

The zip file at the top of the article doesn't contain the libgdx binaries (this would have made the zip file too big). However, it is very easy to add them. Download libgdx and run gdx-setup-ui.jar. This allows you to create a new project or update an existing one. Click "Update", select the location, where you have extracted the zip file and the required files will be added. One thing, that won't be added is the gdx-tools.jar file. You need to add this manually to the libs folder of the desktop project.

I have also made the code available in GitHub. You can clone the repository from there. All required binaries are included. Finally, you can download the game from Google Play. Please note that this version of the game displays ads. The APK at the top of the page is Ad free.

Summary

If this article was too long for you and you immediately scrolled sown to the bottom, this is a summary.

  • libgdx is a cross-platform open source gaming framework that you can use freely in commercial applications.
  • libgdx implements the Game Main Loop pattern with the ApplicationListener interface. It also implements the Game Screens pattern.
  • libgdx makes it easy to render images on the screen. It also provides tools for packing small images into a large one and loading images on the background, while displaying a splash screen.
  • With libgdx you can embed a bitmap font with a single line of code. And you can create a bitmap font out of any font installed in your system with a provided utility.
  • Calling native code is usually required (displaying ads, in-app purchases, native input text, integration with leaderboard services).
  • It is necessary to save the state of your game regularly. libgdx makes this easy with a cross-platform json serializer.

History

  • 2013/12/28: First submission
  • 2014/01/04: Added compiling instructions

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

Giannakakis Kostas
Software Developer (Senior) Self employed
Greece Greece
No Biography provided

Comments and Discussions

 
QuestionHelp please [modified] PinmemberAmol Chopra18hrs 14mins ago 
QuestionMain Menu Button PinmemberMember 109312697-Jul-14 20:05 
AnswerRe: Main Menu Button PinpremiumGiannakakis Kostas8-Jul-14 22:42 
QuestionGetting error regarding opengl PinmemberMember 1066744713-Mar-14 3:33 
AnswerRe: Getting error regarding opengl PinpremiumGiannakakis Kostas13-Mar-14 4:50 
QuestionAppreciation & Reporting problem too! Pinmembermemberash4-Mar-14 8:48 
AnswerRe: Appreciation & Reporting problem too! PinmemberGiannakakis Kostas4-Mar-14 20:32 
GeneralRe: Appreciation & Reporting problem too! Pinmembermemberash25-Mar-14 2:23 
GeneralRe: Appreciation & Reporting problem too! PinpremiumGiannakakis Kostas25-Mar-14 21:34 
QuestionNice tutorial PinmemberMember 1062543625-Feb-14 23:39 
AnswerRe: Nice tutorial PinmemberGiannakakis Kostas26-Feb-14 0:58 
Questionproblem ! PinmemberAlex Scali14-Feb-14 4:10 
AnswerRe: problem ! PinmemberGiannakakis Kostas16-Feb-14 17:57 
GeneralRe: problem ! [modified] PinmemberAlex Scali17-Feb-14 0:39 
GeneralRe: problem ! [modified] PinmemberGiannakakis Kostas17-Feb-14 6:39 
GeneralRe: problem ! [modified] PinmemberAlex Scali17-Feb-14 19:16 
GeneralRe: problem ! PinmemberGiannakakis Kostas17-Feb-14 22:04 
Questionfont.draw font sizes are different in Desktop and Android PinmemberMember 1058112410-Feb-14 7:27 
AnswerRe: font.draw font sizes are different in Desktop and Android PinmemberGiannakakis Kostas10-Feb-14 22:08 
QuestionVery nice! PinstaffYuriy Loginov7-Jan-14 9:15 
AnswerRe: Very nice! PinmemberGiannakakis Kostas7-Jan-14 20:41 
GeneralRe: Very nice! PinstaffYuriy Loginov8-Jan-14 3:49 
GeneralMy vote of 5 PinmemberJOE MIS3-Jan-14 13:37 
GeneralRe: My vote of 5 PinmemberGiannakakis Kostas3-Jan-14 20:59 
GeneralRe: My vote of 5 PinmemberJOE MIS5-Jan-14 14:29 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140709.1 | Last Updated 6 Jan 2014
Article Copyright 2013 by Giannakakis Kostas
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid