Image may be NSFW.
Clik here to view.
NOTE: This is an updated version of a previous article, since it is now much easier+faster to create a LibGDX project using gdx-setup-ui
Why Android?
I’ve been creating games using flash/actionscript for a while now, but have really wanted to get started with android game development, since it’s an open source platform, the sky is the limit to how much you can learn about it.
The devices are usually fairly non-restrictive, being able to load custom roms, install any available software – even not directly through the market, being more practical (using internal storage as storage, not needing to install bloatware to connect to a computer), as well as having many more choices in hardware, since there is such a wide diversity of available mobile phones.
All in all, Android is very non-restrictive and flexible to it’s users, as well as it’s developers, and the market is supposed to be much easier to upload your app on, without getting turned down without a reason. It also caters more towards free apps (with ads), which is what I had wanted to offer, to allow everyone to be able to play my games.
Why LibGDX?
Image may be NSFW.
Clik here to view.
I have read a few android programming books, and most go into quite a bit of detail about application programming, but very little about OpenGL, not to mention I hadn’t done much programming using multiple separate threads in the past.
LibGDX takes care off pretty much all of the low-level stuff for you, so you can focus on game programming, or basic engine programming, and not about techniques for loading different image and music types, creating and handling multiple threads, or creating OpenGL surfaces to render 2d bitmaps on to.
Using it also does not take away any of the control you have, i f you wanted to or needed to program lower level stuff, such as creating surfaces and 3d objects using OpenGL. Thus, it provides an excellent platform to get started with without having to worry about creating everything from scratch yourself, but also allows you to create things later on when you need them.
And for super-icing on the cake, it is specifically made for creating games, and it also allows you to compile and test using native Java on your computer before deploying to your android device, which makes debugging and compile time so much faster! No needing to deal with the android emulator for most of your design, unless you wish to, no needing to compile the apk, move it to the SD card, install, open, and finally debug- you can do it all on your computer before deploying to your android device!
So in summary:
- Handles a lot of the stuff that you would normally need to program from scratch, saves you time, as well as allows you to expand it if needed
- Specifically created for games!
- Debug, test and try out your android app without having to rely on having a device/ emulator running almost all the time!
- Open source and free, as well as great forums for support
So Now that you know why it is a great framework to use to develop android games, lets get up and running.
Downloading and installing everything you need
The things we’ll be downloading and installing include:
- Java SE JDK/SDK (to be able to compile Java code)
- Eclipse IDE (for creating/editing code, compiling, running and deploying your game)
- LibGDX .jar library files
- Android SDK
- Eclipse ADT plugin
Downloading and installing the Java SE JDK
Image may be NSFW.
Clik here to view.
Android programming by default is done in Java. To be able to program in it, you will need the Java JDK. You can get the Java SE JDK from from:
http://www.oracle.com/technetwork/java/javase/downloads/index.html
Download and install it with the defaults (unless you want to chose a different folder).
Downloading and setting up the Eclipse IDE
Image may be NSFW.
Clik here to view.
Now that you have the Java SDK, you can download your IDE for programming and compiling.
You can use any IDE you want, but it is recommended to use the Eclipse, so that is what I use, although it took a little bit of time to get used to it.
Download it from:
http://www.eclipse.org/downloads/
And select ‘Eclipse IDE for Java Developers’, for whichever OS you use (I use windows 64bit).
Once it finishes downloading, open up the zip file. It does not come with an install, but just an eclipse folder. Just move it out onto your hard drive somewhere that you will want to keep your android programming stuff (I put mine in “c:\android\eclipse”).
Next, open up that folder, and double click on “eclipse.exe” (it will have a blue circle icon with 3 horizontal white lines through it). This will open Eclipse, and prompt you for a workspace location, which is where all of your source files for any game projects will go. I put mine in “c:\android\workspace”, and click on “Use this as the default and do not ask again”.
Image may be NSFW.
Clik here to view.
You can just close the welcome screen by clicking on the ‘X’ on the top left, which will bring up the main interface you’ll be using. On the left is the “package explorer”, where your different games/ projects will go. In the center is where you’ll be coding. The bottom is where you’ll see the console, and any syntax problems before compiling your game.
Now that we have Java Ready to go, we need to get the stuff for creating android applications/games.
The Android SDK
Head on over to http://developer.android.com/, click on “SDK” on the top tab, and download the SDK .zip.
It should contain one folder called “android-sdk-windows”, which you just need to move into your android folder area you created earlier (or anywhere you like, really), which I put at: “c:\android\android-sdk-windows”.
Note: developer.android.com is a great place to find info on setting up getting started developing android apps, as well as for reference.
Installing the ADT plugin for Eclipse
Now we need to install the ADT plugin to allow eclipse to easily create android applications/games.
Open Eclipse (if not already open), click on ‘Help->Install New Software” from the top menu.
Click the ‘Add’ button, and enter ‘ADT’ for name, and ‘https://dl-ssl.google.com/android/eclipse/’ for location(You can also see these instructions at: http://developer.android.com/sdk/eclipse-adt.html#installing – and there is also a manual method if yours does not connect) and click ‘OK’. (if it doesn’t seem to download, you may need to turn off a firewall if you’re using it- zone alarm would not let it fetch properly while on)
Select “ADT – http://dl-ssl.google.com/android/eclipse/” in the drop down box for “Work with:”, if it was not already selected. Below, after a time, it should show “Developer Tools” under “Name”. Click the check box next to it, and click “Next”and click “Next” again on the next screen. Read through the license agreement, click the radio button for “I accept…” and click “Finish”.
It should have a popup for “Installing software”, and another popup warning for “installing unsigned content”, which you just need to click “OK” to, since you trust android for adding the ADT to your eclipse.
Image may be NSFW.
Clik here to view.
Click “Restart Now” on the next popup, and let Eclipse Restart.
Once this restarts, you can “Configure/setup” your ADT plugin.
Setting up the ADT plugin for Eclipse
We just need to setup the ADT plugin for android development.
You first need to tell it where you put the Android SDK, so click on “Window->Preferences” on the top menu. Click “Android” on the left side, click on “Browse” next to “SDK Location” and go select where you unzipped your android SDK folder (“C:\android\android-sdk-windows” is where I put it on my computer). and click “OK” twice to get back to eclipse. I had a popup for “Android SDK Verification” “SDK Platform Tools component is missing”, and to install it through the SDK Mangaer, which we’ll do next. Click “Ok” again.
Next Click on “Window->Android SDK and AVD Manager” from the top window. The first screen is for creating “virtual android devices”- to later test out different display sizes and configurations to make sure your app/game looks good (although it runs very slow compared to a real device, or in Java on your computer).
Click on “Available packages”, click the small arrow next to “Android Repository”. From here click whichever ones you think you will need, or all if you have extra disk space + time for downloading. I just needed “Android SDK Platform-tools”, “Documentation for Android”, “SDK Platform Android 3.2, API13″, as well as “API 3″ for android 1.5, and samples for API13.
Click “Install Selected”, “Accept all” radio button on the new popup, and “Install”. Next the download window will popup, and it will begin downloading the selected Android packages, which may take a while.
Afterwards, it should ask you if you want to restart ADB, so click yes.
Image may be NSFW.
Clik here to view.
Now that we have the ADT and the SDK for android setup, we could begin developing applications or games without LibGDX by using the top menu and selecting “File->New->Project->Android->Android Project”, but we will first setup LibGDX and a quick game demo, to get right into game development.
Downloading LibGDX
Go to http://libgdx.badlogicgames.com/nightlies// to download the LibGDX nightlies zip (libgdx-nightly-latest.zip).
After it downloads, create a folder in your android folder, and put the zip file into it (I created the folder “libgdx_2013_03_25″, so c:\android\libgdx_2013_03_25″, but it doesn’t really matter what you call it as long as you remember it). Then also unzip the zip to the same folder, which should now have at least ‘libgdx-nightly-latest.zip’ and ‘gdx-setup-ui.jar’ (but will have all the other files as well, just those two are required to use the setup).
Creating a Java project with integrated LibGDX Setup GUI Jar Program
One of LibGDX’s biggest strong points is being able to compile and debug in native Java on your computer, without having to try it out on your android phone or the emulator, which saves massive amounts of time.
It also used the java project as a reference, so everything you create there will be part of your android project, so you don’t have to re-type anything.
So to Create your LibGDX project, double click on ‘gdx-setup-ui.jar’ which will open the LibGDX project setup app (if you have Java installed and working right, if not “Google” how to run a .jar file ).
Image may be NSFW.
Clik here to view.
Next, click “Create”, and you’ll be taken to the project setup screen:
Image may be NSFW.
Clik here to view.
The main window you’ll need to edit is on the left side- so you can name your project (which will also be your main folder name), then name your package (which is basically like the folder system- which should be unique for each person/ project. I usually name my projects ‘com.companyname.projectname’(or your name instead of company name). So if you want to follow along, use ‘MyGDXGame’ for the name, package: ‘com.chrismweb.mygdxgame’, Game class: ‘Game’.
Then click on the folder icon next to “destination”, and browse to your workspace folder for eclipse (c:\android\workspace from earlier- in the screen shot it shows mine, which is s:\android\workspace2).
You can also chose which types of projects to generate in the bottom left, which I only uncheck ‘ios’(Apple iPhone/ pad/ touch), since Apple requires you to be in Mac OS(osX), and LibGDX currently requires Mono to compile to iOS. But you want at least want the desktop project for quickly testing, and the HTML project is nice for later, to easily share with friends without having to download anything.
[Extra information Start]
Now if you always want to have the latest LibGDX nightly (which you should currently have, so don’t need to do right now), you can click on the ‘N’(1.) next to “LibGDX” in the center of the screen, and it will download directly into your folder, instead of needing to download off of the website!
In the center of the screen, you can chose to add other common libraries (physics body editor and universal tween engine), but you only need to if your project will need them (click on the ‘i’ to see info on them – the ‘S’ to download the latest stable version). The tween library is helpful for lots of things, providing smooth linear animations quickly to user interface elements (or anything else), but isn’t required for game programming
[Extra information End]
Now under ’4′ on the bottom right, it should say in green letters ‘Your configuration is valid’ if you have all the libraries in the same folder as the setup program. Click on ‘Open the generation screen’, then click on the “Launch” button. It will do several things, but finish with “All done!”, which means you are now all done with the setup program, and could even delete the folder if you chose to(but you’ll want to keep it for generating new projects in the future).
Close the program, and open eclipse- we’re going to now import the projects into our workspace (even though they are already in our workspace folder).
Importing Projects into Eclipse Workspace
So, make sure Eclipse is open, then either right click in the left panel(package explorer) white area, and click on ‘Import’, OR click on ‘File’ in the top left, and click on ‘Import’.
Under ‘General’, double click on ‘Existing Projects into Workspace’.
Image may be NSFW.
Clik here to view.
Then, next to “Select root directory” click “Browse”, and click on your workspace folder (“c:\android\workspace” from earlier).
Image may be NSFW.
Clik here to view.
It should have your projects in the “projects” box below checked, which will be imported, so you can work with them in Eclipse (it won’t actually move them or anything- it’s just for Eclipse to be able to see them). Then click “Finish”, and you should see them pop up in the left panel(package explorer).
Your main project is the one without an extension ‘MyGDXGame’, and has nicely enough been populated with a basic ‘Game’ class, all the libraries needed, and the build paths setup.
So now the rule is: “MyGDXGame” – where you actually make changes to your game; “MyGDXGame-desktop” – where you can actually run your game on your Desktop(where you’ll do 99% of your development), and “MyGDXGame-android”, where you can see your game running on a connected emulator or Android device.
So to run the project setup, double click on “MyGDXGame-desktop”, open ‘src’->”com.chrismweb.mygdxgame”->”Main.java”, which should bring up this file in the right side panel. Hit “F11″ on your keyboard (or the little bug icon), and it should run and open up your LibGDX application on your desktop!
Image may be NSFW.
Clik here to view.
You can likewise open up the android project ‘MainActivity.java”, connect your Android device, and run it on there, again using ‘F11′ (or create a very slow emulator for when it prompts you).
If you don’t see anything in the bottom window(should be ‘console’), click on the little down arrow next to the computer icon on the right (hover over it: display selected console), and click on “Android”. If you had clicked ‘F11′ it should show you it installing, then starting up on your android device.
File Explanation – Desktop
Lets first look at the desktop file ‘Main.java’ in the “MyGDXGame-desktop” project to see what is going on there.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | package com.chrismweb.mygdxgame; import com.badlogic.gdx.backends.lwjgl.LwjglApplication; import com.badlogic.gdx.backends.lwjgl.LwjglApplicationConfiguration; public class Main { public static void main(String[] args) { LwjglApplicationConfiguration cfg = new LwjglApplicationConfiguration(); cfg.title = "MyGDXGame"; cfg.useGL20 = false; cfg.width = 480; cfg.height = 320; new LwjglApplication(new Game(), cfg); } } |
This file just controls starting up the desktop version of your game. Title is the title in the top of the window, GL20 is whether you require using openGl 2.0 or not (you don’t need to until you learn how to use shaders, which isn’t required to create a game), and the width and height of the window being created.
They used 480×320, because that is also the most common, smallest resolution on phones.
The last line ‘new LwjglApplication(new Game(), cfg);’ actually creates the game (from Game.java in your linked ‘MyGDXGame’ Project), with all the information above.
So all this file is, is for window initialization code for the desktop.
File Explanation – Android
Now for ‘MainActivity.java’ in the “MyGDXGame-android” project:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | package com.chrismweb.mygdxgame; import android.os.Bundle; import com.badlogic.gdx.backends.android.AndroidApplication; import com.badlogic.gdx.backends.android.AndroidApplicationConfiguration; public class MainActivity extends AndroidApplication { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); AndroidApplicationConfiguration cfg = new AndroidApplicationConfiguration(); cfg.useGL20 = false; initialize(new Game(), cfg); } } |
This is just the window initialization code for Android. Notice you don’t need to specify the screen resolution because the application will just use the native resolution on the Android device, and is full screen.
One thing you SHOULD take note of is the folders on the left for this project: ‘assets->data->libgdx.png’. This is the actual image that is loaded when you start up the desktop, or android project. If you double click on it, you should see the same thing you actually saw in the program, but with lots of white space below it. This is because when using openGL ES 1.0, all images loaded have to have resolutions of multiples of 2 (such as 4,16,32,64,128,256,512,1024,2048, ect). So since the image we want to load is for full screen is 480×320 to fit the smallest screen, we have to put it inside an image that is big enough to contain it- 512×512 pixels (it doesn’t always have to be even, you could use 1024×256 if you wanted to, if the images in it fit inside properly).
With the setup GUI, it also linked all other projects assets folder to the android projects asset folder. So all you need to change is the android assets folder, and it will automatically update in all your other projects. Or you could copy it manually.
File Explanation – Main game Project
Now for the project without an extension:
Now for ‘Game.java’ in the “MyGDXGame” project:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 | package com.chrismweb.mygdxgame; import com.badlogic.gdx.ApplicationListener; import com.badlogic.gdx.Gdx; import com.badlogic.gdx.graphics.GL10; import com.badlogic.gdx.graphics.OrthographicCamera; import com.badlogic.gdx.graphics.Texture; import com.badlogic.gdx.graphics.Texture.TextureFilter; import com.badlogic.gdx.graphics.g2d.Sprite; import com.badlogic.gdx.graphics.g2d.SpriteBatch; import com.badlogic.gdx.graphics.g2d.TextureRegion; public class Game implements ApplicationListener { private OrthographicCamera camera; private SpriteBatch batch; private Texture texture; private Sprite sprite; @Override public void create() { float w = Gdx.graphics.getWidth(); float h = Gdx.graphics.getHeight(); camera = new OrthographicCamera(1, h / w); batch = new SpriteBatch(); texture = new Texture(Gdx.files.internal("data/libgdx.png")); texture.setFilter(TextureFilter.Linear, TextureFilter.Linear); TextureRegion region = new TextureRegion(texture, 0, 0, 512, 275); sprite = new Sprite(region); sprite.setSize(0.9f, 0.9f * sprite.getHeight() / sprite.getWidth()); sprite.setOrigin(sprite.getWidth() / 2, sprite.getHeight() / 2); sprite.setPosition(-sprite.getWidth() / 2, -sprite.getHeight() / 2); } @Override public void dispose() { batch.dispose(); texture.dispose(); } @Override public void render() { Gdx.gl.glClearColor(1, 1, 1, 1); Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT); batch.setProjectionMatrix(camera.combined); batch.begin(); sprite.draw(batch); batch.end(); } @Override public void resize(int width, int height) { } @Override public void pause() { } @Override public void resume() { } } |
This is the project that you’ll be developing everything for your game in. The other projects just contain code that is specific to what they’ll be running on – so if you added something that was Android only (like GPS, or using the accelerometer), you would create Android only code using an ‘interface’ to access it from your main game project, which would only run on Android, and you can chose to handle it differently on the desktop (or ignore it). Check out the badlogic/libgdx forums for more information (http://www.badlogicgames.com/forum/) when you get to that point.
For now, lets explain what is going on:
Line 23-24 Here we’re just getting the width and height of the screen (what you setup in the config for desktop -automatic for Android)
Line 26 We have to create the “camera”, which will allow us to position everything easily in our “world” so we can actually see it on screen.
Line 27 We create a SpriteBatch, which is how we typically render graphics to the screen. A sprite batch is used because it is more efficient to render all the graphics from the same texture at the same time, which LibGDX handles for us. So that way it looks from our end like we can draw out any graphics at any point, but they will actually be batched up, and rendered out together to improve frame rate.
Line 29 Loading the texture that we saw in the Android project (which is always copied and updated to the other projects).
Line 30 Setting the texture filter used. The Texture by default sets the filter to “Nearest”, which would also work. Using “Linear” makes the image smoother when resizing to different screen sizes (which can be seen here: http://en.wikipedia.org/wiki/Image_scaling
Line 32 This is actually creating a “TextureRegion”, by using the texture loaded before, and the coordinates for the top left of the texture, and as wide and tall as the image (512×275 – apparently they scaled up the image from 480×320, so it would be higher resolution and look better on larger screens- as well as use the extra room that was available on the 512x512px image)
Line 34-37 Setting up the position and size of the Sprite, which will be used to be drawn on screen.
Line 54-56 The actual drawing code, which is used to draw the sprite texture on screen every frame. The ‘render()’ is called automatically every frame, which is where your main game loop code will go.
Now personally, the .9 scales, w/h, ect aren’t very straight forward, and you might get a “WTF” moment. I personally redo everything to make sure it makes sense, and is easily readable what is going on.
Modifying the Example Project for Basic Animation, and increased Readability
Below is how I modified the project:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | package com.chrismweb.mygdxgame; import com.badlogic.gdx.ApplicationListener; import com.badlogic.gdx.Gdx; import com.badlogic.gdx.graphics.GL10; import com.badlogic.gdx.graphics.OrthographicCamera; import com.badlogic.gdx.graphics.Texture; import com.badlogic.gdx.graphics.Texture.TextureFilter; import com.badlogic.gdx.graphics.g2d.Sprite; import com.badlogic.gdx.graphics.g2d.SpriteBatch; import com.badlogic.gdx.graphics.g2d.TextureRegion; public class Game implements ApplicationListener { private OrthographicCamera camera; private SpriteBatch batch; private Texture texture; private Sprite sprite; float SCREEN_WIDTH; float SCREEN_HEIGHT; @Override public void create() { SCREEN_WIDTH = Gdx.graphics.getWidth(); SCREEN_HEIGHT = Gdx.graphics.getHeight(); camera = new OrthographicCamera(SCREEN_WIDTH, SCREEN_HEIGHT); camera.position.set(SCREEN_WIDTH / 2, SCREEN_HEIGHT/ 2, 0); camera.update(); batch = new SpriteBatch(); texture = new Texture(Gdx.files.internal("data/libgdx.png")); texture.setFilter(TextureFilter.Linear, TextureFilter.Linear); TextureRegion region = new TextureRegion(texture, 0, 0, 512, 275); sprite = new Sprite(region); sprite.setSize(SCREEN_WIDTH, SCREEN_HEIGHT); sprite.setPosition(0, 0); } @Override public void dispose() { batch.dispose(); texture.dispose(); } @Override public void render() { Gdx.gl.glClearColor(1, 1, 1, 1); Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT); batch.setProjectionMatrix(camera.combined); batch.begin(); sprite.draw(batch); Gdx.app.log("Game:", "sprite x is at: "+sprite.getX()+", "+sprite.getRegionWidth()); sprite.setX(sprite.getX()+Gdx.graphics.getDeltaTime()*300); if(sprite.getX()>SCREEN_WIDTH) sprite.setX(-SCREEN_WIDTH); batch.end(); } @Override public void resize(int width, int height) { } @Override public void pause() { } @Override public void resume() { } } |
Which you can see is mostly replacing numbers and variables to make it much more readable(IMO). Also, in the “render” function/method, I modified the Sprite to scroll across the screen, and reset, to create a basic marquee, as well as logging out the ‘X’ position, which you can see in the console as it is running.
NOTE: if you click ‘F11′ in the project, it will prompt you with an “Debug As” window. This is because there is no window initialization code in this project, so it doesn’t know how to run. Instead, you need to click on the ‘-desktop’ project in the left hand panel, then you can hit ‘F11′ to run.
Alternatively, if you get tired of this, as I do, you can copy the desktop “Main.java” into this project, copy all the libraries from the desktop ‘lib’ folder into the Game ‘lib’ folder, and add them to the java build path (right click on your Game project ‘MyGDXGame’->properties-> Build path in left panel – > libraries in top right panel, ‘add jars’, open project->libs, select jars (except source) using “ctrl+ click” or “shift+click” to add multiple jars at once. Then click on the arrow next to each jar, double click ‘source attachment’, ‘browse’, then select the relevant source for that jar.
The only disadvantage is that you need to comment out the entire ‘Main.java’ file when you try to compile the html version, but you don’t need to for compiling the Android version.
Conclusion
Now you should know how to compile the example LibGDX application for Desktop and Android, and how to do some basic editing to it.
I recommend checking out, and compiling the LibGDX demos and tests:
Demos: https://github.com/libgdx/libgdx/tree/master/demos
Tests: https://github.com/libgdx/libgdx/tree/master/tests/gdx-tests/src/com/badlogic/gdx/tests
And more info on the main documentation page:
http://libgdx.badlogicgames.com/documentation.html
I recommend looking at the game demo’s for libGDX, the jumper game is especially helpful (showing you how to load textures, use input, play music+ sounds, create different screens, and a menu system)
Resources
You can see the LibGDX forums (Search for your question before asking at: http://www.badlogicgames.com/forum/
You can see Mario’s blog (one of the creators of LibGDX) at: http://www.badlogicgames.com/forum/
The main LibGDX sites are:
The Google code site with a few tutorials and a video: http://code.google.com/p/libgdx/
I’ll try to add more tutorials soon, but hopefully this will get you up and running, and playing with the demos!
The new main site for LibGDX: http://libgdx.badlogicgames.com/