Badlogic Games

What is libgdx?

Libgdx is my attempt at a cross-platform game development library written in Java with some JNI code for performance hungry sections. It abstracts away the differences between writting desktop and Android games based on OpenGL. This allows you to prototype and develop your application entirely on the desktop and only needing 6 lines of code to make it run on Android.

Neat, so what does it offer?

Libgdx offers modules for graphics via OpenGL ES, audio, input and file i/o as well as a full Box2D JNI wrapper especially suited for Android. All modules abstract away system specifics so you can execute the same code on the desktop and Android. The graphics module offers full bindings to OpenGL ES 1.0, 1.1 and 2.0. On the desktop almost all of the OpenGL ES functionality is emulated via translations to desktop OpenGL. The audio module features a native mp3 and ogg decoder and simple classes to playback sound effects as well as stream music. The input module provides you with information about the current state of all input devices available. This includes the touch screen, the accelerometer and the keyboard. On the desktop the touch screen is emulated via mouse input, the accelerometer is of course not available and keyboard input is mapped accordingly. The file i/o module offers you a unified way to read application internal data which map to assets on Android and files in the root directory of the application on the desktop. Additionally the module allows you to read and write external data. On Android this maps to the external storage device like the SD-card, on the desktop all paths are relative to the user’s home directory.

Ok, but can i write commercial games with this?

Libgdx is licensed under the Apache license 2.0 so there’s no problem when you want to use it in your paid game.

Got a Demo?

Well, yes. I wrote a small space invaders clone. Unsophisticated but should bring the point across. Here’s an image of the desktop version:

Here’s a video of the Android version:

And clicking this link will lead you to the applet version of it.

You can find the source code for this game in the SVN repository at

http://libgdx.googlecode.com/svn/trunk/gdx-invaders/

http://libgdx.googlecode.com/svn/trunk/gdx-invaders-android/
http://libgdx.googlecode.com/svn/trunk/gdx-invaders-applet/

Where can i find it?

You can either check out the code via SVN from http://code.google.com/p/libgdx/source/browse/#svn/trunk/gdx/src/com/badlogic/gdx or get the latest build from the download page at http://code.google.com/p/libgdx/downloads/list. The build files contain all the needed jars for the desktop version as well as the shared libraries for the desktop and Android. To get something setup fast you can simply download the gdx-helloworld.zip from the download page above. It contains two eclipse project, one for the desktop version and one for Android. All the jar dependencies and shared libraries are in place and the inter project dependencies are also setup properly. The Android project depends on the desktop project which hosts all the code. The Android project only houses a single class that is the Activity of the Android version of the application. Of course you have to create a Run Configuration for each project which starts the main class and activity respectively. On the desktop you have to pass the VM argument “-Djava.library.path=libs/” to the VM in order for libgdx to find the shared library. On Android no special actions are needed.

That’s all nice and good, but is there any documentation?

Glad you ask! Everything in libgdx has extensive Java docs attached to it. In the binary distribution you will find a file called gdx-version-sources.jar. You can attach that to your Java projects to get the Java doc info for all classes and methods that are offered to you by libgdx. You can also browse the SVN repository to get to that information. You can start at http://code.google.com/p/libgdx/source/browse/#svn/trunk/gdx/src/com/badlogic/gdx and check out the main interfaces first, then move on to the packages in that directory to see what else is available to you. Additionally i’m writting a series of small blog posts that illustrate the various functionalities libgdx offers you. You can find all of those at http://apistudios.com/hosted/marzec/badlogic/wordpress/?cat=17. And if you are into reading a lot you can check out the extensive Javadocs for all public interfaces and classes at http://www.apistudios.com/hosted/marzec/badlogic/gdx/doc/

I want to help!

Perfect! What’s needed is an understanding of Java, Eclipse and subversion. Everything else you can learn on the way. What’s needed at the moment is the following:

• Small examples that illustrate the the various classes

Dude, you’re code is bugged

Awesome! Please report any bugs to libgdx at badlogicgames dot com or on the issue tracker at http://code.google.com/p/libgdx/issues/list!

Anything else i need to know?

Yes, here’s a list:

• The OpenGL ES emulation on the desktop is of course not 100% functional. Some non-essential getter methods of the GL11 interface are not implemented on the desktop. Vertex arrays with fixed point buffers are supported on the desktop. However, fixed point vertex buffer objects are not as there’s no way for me to intercept those glBindBuffer calls and know which part of the buffer is fixed point data which i’d need to transform to floats. You will only run into this problem is you implement VBOs yourself. Normally you should just use the MeshRenderer class which will do all the heavy lifting for you! Unimplemented or unsupported methods will throw an UnsupportedOperationException
• vertex and fragment shaders on the desktop have a bit more functionality than their OpenGL ES 2.0 counter parts. You have to be careful when implementing cross plattform shaders. Generally you will want to target the OpenGL ES 2.0 GLSL specification. Your fragment shaders should come in desktop and Android versions as OpenGL ES 2.0 fragment shaders need to define the precision of floats which is not needed on the desktop (and will produce a parsing error there).
• The library currently includes FFT code from the minim project, sources from kissfft as well as the sources for libmpg123 to be able to compile a shared library for Android. There’s no issue with the FFT code. In the case of libmad you can only use it if your application is non commercial. I’ll probably remove it completely and use libmpg123 instead.

Thankies

Stefanie for still sticking with me after spending so much time on this Robert Green from Battery Powered Games for some late night discussions (at least for me)

•