dpk’s weblog

This will be a 3 part post demonstrating how to make a simple side scrolling game using libgdx (official project blog), a cross-platform library that allows you to simultaneously build for the desktop and for Android devices.

Updated 2011-09-19: Updated to use libgdx 0.9.2. No code changes required.

Updated 2011-09-18: Updated to use libgdx 0.9.1 (for real this time…) which meant renaming the pack file, TiledMapRenderer to TileMapRenderer, moving and renaming the tiles and pack file (and reindexing) due to new requirements from libgdx.

Updated 2011-06-12: Fixed some graphical glitches reported by Ed (in part 2′s comments). Thanks for all of your help Ed! Additionally, the tutorial is now based on libgdx 0.9.1 (it might have been libgdx 0.9.0 at the time, sorry folks) instead of an arbitrary nightly build, and it uses a modified TexturePacker in place of “manual” pack file generation.

This example is for anyone interested in making Android games, but is unsure where to start. By the end of part 3 you will have a basic Mario-like side-scrolling game with realistic physics, and (hopefully) you will be able to take this example and build something fun.

I’ve learned a few things since writing my previous post on using Tiled Map Editor with libgdx that I’ll apply in this series, things that make building a simple tiled-map game a lot easier. All code found here is released under the Apache 2.0 license, meaning, basically, you can use it for whatever you want. (IANAL, read the license for details.)

This is a much more involved tutorial than you have seen before on this site. There are a lot of different components used here and I tried to avoid cutting corners during explanations.

Post index

1. Creating map tiles and the game map
   1. Where to begin
   2. Creating map tiles
   3. Creating the game map
   4. Saving the map data to the projects
   5. Loading and viewing the map in-game: TiledMapHelper
   6. Enable scrolling through the map by touch
   7. Summary
2. Integrating box2d
   1. Define the collision boundaries for each type of map tile
   2. Introducing TileCollisionTool
   3. Programmatically configure the map’s collision boundaries
   4. Add a player character sprite
   5. Navigate the map with the player character
   6. Summary
3. Final touches: Scoring, lives, game over [coming soon]
   1. Add breaking blocks
   2. Add score and score display
   3. Add player death and a game over screen
   4. Hey, you’ve got a game
   5. Summary

Where to begin

This series was written with the assumption that you have read through all of the beginner libgdx tutorials, up through Projection Viewport Camera. libgdx has a tutorial on working with tiled maps, however that tutorial does things a little differently than what you’ll find in this series.

The box2d library includes a JNI wrapper for box2d, a “rigid body simulation library”, more commonly known as a physics library. It is pretty easy to use, although there are some box2d idiosyncrasies that you need to be aware of, and I will point those out in part 2. The box2d manual is worth reading, although its examples are all written for C++.

Your first steps are to create your libgdx project pair, named “JumperTutorial” and “JumperTutorialAndroid”. You can name them whatever you want, of course, but this series will use these names.

Next, download and install Tiled Map Editor and a graphics program before you begin. I can easily recommend using either Pixen on Mac OS X or GIMP on Windows (GIMP’s interface has come a long ways in recent years, I really like it).

Download the JumperTutorialProjects.zip projects used in part 1 and follow along as its components are explained. (14.4MB)

Creating map tiles

Your map will be made up of small, identically sized tiles, all eventually stored in a single image file, which I’ll refer to as “the tile image”. You can create this image file in any program (including MS Paint or similar), but some programs have features that make drawing easier.

Before you begin creating your graphics, take a moment to draw out a diagram of the sort of level you want to create. This will help you figure out how many different tiles you’re going to need to construct a whole map, and that will help you determine the size of your tile image.

Rough sketch of what a game map might look like

Based on my sketched map I’ll need tiles for the open air, a regular ol’ ground tile with a floor on top, a ground tile with no floor (that will go under the floor tile), a set of three tiles for the stairs (left-to-right and right-to-left stairs and a tile to sit between), two more ground tiles with left and right facing cliffs (and two more tiles to continue those cliffs downward), and six tiles for mountains in the background (left-to-right ramp and right-to-left ramps, a solid mountain block, and three for the mountain top). I’m skipping the clouds and exclamation-point blocks for now, as they will be handled separately as sprites (in part 3). I’m also skipping the pipes (part 4? if there is interest). That makes 16 tiles in total.

It’s important to decide early on what size you want each of your tiles to be. Consider the size of your target platform’s screen and how much detail you want to work in to each tile. For this example, I have chosen to make the tiles 32×32 pixels. On a ~400×900 pixel screen, the game will show around 12×28 tiles on screen at a time, which will work quite well for a Mario-clone.

The 16 different tiles will be saved to separate files, and then will be combined in to one large tile image file using a customized version of libgdx’s TexturePacker. TexturePacker combines the images together and creates a separate “pack” file that specifies where each tile is located within the tile image. TexturePacker also adds a buffer around the edge of each tile. This buffer seems to come in handy when the map display is automatically resized just a tiny bit. (I have not personally verified this.)

Some tiles next to part of the packed tile set

In the JumperTutoralProjects.zip file you’ll find the modified TexturePacker source and project. You can use Eclipse to export it as a runnable jar (File menu -> Export -> Runnable Jar). The modifications include support for numbering the tiles by their position within the tile image, rather than based on the tile filename, and support for including the level name inside the resulting pack file. These modifications together make the pack file work unmodified in the example code. Additionally, the TexturePacker code has been configured to add a 2 pixel buffer around images.

Important note: The resulting image and its pack file need to be named or renamed to “level.png” and “level packfile” (with a space) once you are done and before you create a map in Tiled Map Editor.

Steps for using the modified TexturePacker for this project:

1. Create an input directory to hold your individual and an output directory to hold the tool’s output
2. Create all of your individual tile images and save them to the input directory
3. Open a command prompt and run java -jar TexturePacker.java inputdirectory outputdirectory level where “level” is the name of the level file you’ll create later on, without its extension.
4. Done. Inside the output directory you’ll see a single, larger png file and the “pack” file.

If you’re curious, go ahead and open the pack file in any standard editor. You shouldn’t need to make any changes in the file, however. In the file you’ll see the top left corners of each tile (xy) and the tile’s size and index values.

Creating the game map

Start up Tiled Map Editor and choose “New Map” in the File menu. Enter a map size at least a few times as wide as and a bit taller than your target screen, so you’ll have something to scroll around. I picked 60×15 (1920x480pixels) for the example map. Be sure to select “Orthogonal” under orientation and use the correct tile size (I’m using 32×32 as before).

Tiled Map Editor “New Map” dialog

In the Map menu, choose “New Tileset”. In the dialog that pops up, pick a name for the tiles (anything will do) and browse to your tiles. Leave the “Use transparent color” box unchecked — this tutorial is not using transparencies. Set your tile width and height (32 and 32 in this example) and set the spacing to 2.

Select a tileset

Now you’re ready to start drawing the map. Tiled Map Editor works just like a pixel image editor, with a standard paintbrush tool and a fill tool. It saves to a “TMX” file that contains instructions for rendering the tiled map. You can find my sample TMX file inside the project zip file (at the top of the page).

Screenshot of a map in Tiled Map Editor

Saving the map data to the projects

The file names and directory structure used for your tiled map assets are important. Create a “data” directory in your desktop project if you haven’t already. Inside “data” create “world” and a subdirectory “level1″. For now, this game will only have one level, but it will be easy to add another level should the time come. Copy your TMX file in to that “level1″ directory and name it “level.tmx”.

Inside “data” create a “packer” directory and save your tile image there as “level.png” and its pack file as “level packfile” (yes, with a space, required by libgdx).

The main project directory structure

Loading and viewing the map in-game: TiledMapHelper

I wrote a simple, reusable class to handle all of the map loading and framing of the map within the display (through positioning of the camera). This decouples the game code from the map code and makes it easy for the game to change from level to level. The class is based on code found in libgdx’s tiled map test suite, and it only works with single-layer maps. You can find it inside the zip file (beginning of the article).

Here’s some explanation about some of the class methods

45
46
47
48
49
50
51
52
53
54

	public void render() {
		tileMapRenderer.getProjectionMatrix().set(camera.combined);
 
		Vector3 tmp = new Vector3();
		tmp.set(0, 0, 0);
		camera.unproject(tmp);
 
		tileMapRenderer.render((int) tmp.x, (int) tmp.y,
				Gdx.graphics.getWidth(), Gdx.graphics.getHeight(), layersList);
	}

The camera’s position controls what is shown on the display. This method copies the camera’s combined projection and view matrix (in effect, its current position) to the tiled map library’s projection matrix and then sets the coordinates (x, y, w, h) that will be used to render the map to the screen.

105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

	public void loadMap(String tmxFile) {
		if (packFileHandle == null) {
			throw new IllegalStateException("loadMap() called out of sequence");
		}
 
		map = TiledLoader.createMap(Gdx.files.internal(tmxFile));
		tileAtlas = new TileAtlas(map, packFileHandle);
 
		tileMapRenderer = new TileMapRenderer(map, tileAtlas, 16, 16);
 
		camera = new OrthographicCamera(Gdx.graphics.getWidth(),
				Gdx.graphics.getHeight());
 
		camera.position.set(0, 0, 0);
	}

This method will be used when your player switches levels. It basically just takes care of things that you would otherwise have to worry yourself with, like preparing the camera and tile atlas and renderer. Note: The 16 used in the TiledMapRenderer constructor was picked arbitrarily.

Enable scrolling through the map by touch

The code in the project detects touch and drag events by recording where the event began and then measuring the horizontal and vertical distance from that point. The code will also ensure that the user cannot scroll outside of the map area. You’ll find this in the render() method of JumperTutorial.java.

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

		if (tiledMapHelper.getCamera().position.x < screenWidth / 2) {
			tiledMapHelper.getCamera().position.x = screenWidth / 2;
		}
		if (tiledMapHelper.getCamera().position.x >= tiledMapHelper.getWidth()
				- screenWidth / 2) {
			tiledMapHelper.getCamera().position.x = tiledMapHelper.getWidth()
					- screenWidth / 2;
		}
 
		if (tiledMapHelper.getCamera().position.y < screenHeight / 2) {
			tiledMapHelper.getCamera().position.y = screenHeight / 2;
		}
		if (tiledMapHelper.getCamera().position.y >= tiledMapHelper.getHeight()
				- screenHeight / 2) {
			tiledMapHelper.getCamera().position.y = tiledMapHelper.getHeight()
					- screenHeight / 2;
		}

This code is pretty self-explanatory. The main thing to consider, that might not be immediately obvious, is that the camera is pointed at the center of the screen. This means the camera’s position will need to be constrained within an imaginary rectangle inside of the map, inset by half the screen width and half screen height all around.

Summary

You should now have what you need to make a simple map and an application to navigate around that map using your finger or mouse. It’s not quite a game. Where to go from here? You could, if you like, make a few more levels and add some code that uses TWL to make a menu system of sorts. You could add an intermediate map screen that allows you to select which level you want to view. Or you could add detection for clickable regions on the map that will take you from level to level.

In part 2, I’ll describe how to integrate the box2d physics library, and I’ll include some code that will make adding collision detection to your map a whole lot easier.