It’s a 3D arcade game. You control a ship in a backyard pond and fire at other ships. Really neat for 48h!

Dimitry Fink created Stargazer for Android and Facebook:

This one’s a puzzle game, where you rotate a star configuration in 3D to become a 2D object. It’s an insanely cool idea and the mechanics got me hooked this morning. What’s interesting about this one is that it integrates with the Facebook APIs via JSNI, a way to communicate with Javascript from Java in GWT. Hopefully Dimitri will enlighten us on what was involved getting this to work.

Robert Engelbert ported his Frogger tutorial game not only to Android put to WebGL as well:

You should totally check out his blog which is filled with all kinds of game programming tutorials. He has a series on implementing frogger with various frameworks, including libgdx. Well worth a read.

Those are just 3 recent games i discoverd, there are a lot more WebGL/libgdx games out there already, some on the Google Chrome store. Let’s hope WebGL compatibility gets even better in the coming months!

In order to reduce overhead in the Android backend when putting values into Preferences, we’ve updated the implementation to not commit changes until flush() is called on the Preferences object. Previously, every time you put a value into Preferences the Android implementation would create an Editor, put the value, then commit it. While this was good for ensuring that values would be persisted quickly, it also meant File I/O for each and every value placed into preferences. When putting more than one or two values, this could create noticeable slowness.

This may sounds like a big deal, but this actually brings the Android implementation more in line with the other backends, which have always required flush() to be called in order to persist the changes. It also mirrors the normal workflow for working with SharedPreferences in normal Android development.

TL;DR Version: You must now call flush() in all cases where you want changes to Preferences to be persisted.

Everyone becomes a Contributor!

Everyone will be capable of contributing to both the development guide/wiki as well as the javadocs. The first thing you need to do is drop me an e-mail at contact at badlogicgames dot com. Provide a valid Google account so i can add you as a contributor to libgdx on Google Code. You will be granted write permissions for the Wiki only. If you want to also contribute to Javadocs, follow the instructions below.

Next decide on what you want to work on.

Development Guide/Wiki

The wiki/development guide is currently a work in process. As you can see there’s already an outline of which topics it should cover. Check out what’s there so far to get a feel for how individual dev-guide articles should look like. Then pick one of the items and create the article for it. In general you want to give an overview of a feature, provide info on differences between platforms if any, and show a few code snippets demonstrating the usage of the feature.

The second type of wiki contributions are articles. An article illustrates a complete working example for some specific functionality, e.g. wrapping 3rd party services. You can chose to embed your code in the article and refer to the project setup article for the project creation step.

Java Docs

While libgdx’s javadocs are comparatively complete, some parts might be outdated or badly written (or actually missing). Fork libgdx on Github, load up the Java files you want to improve, push the changes back to Github and send a pull request. Please only improve on the Javadocs, do not manipulate the code itself. I’ll merge all pull requests manually, don’t try to trick me This guide shows you how to write proper Javadocs (more or less).

The best way to identify underdocumented class is to check out the online Javadocs. Browse through the classes and if anything seems bad, fire up your IDE/editor, edit the docs, commit and push. To lower merge burden, please batch up your commits into a single pull request.

What about the User Wiki?

The user wiki effort has died down somewhere around september. None of the development team ever maintained any portions of it, so it was a very undirected effort. With the outline of the TOC and articles already written as well as our commitment to curate additions by users, it is my hope that this new effort will result in a more structured, high quality result. Again, the user wiki effort is/was fantastic and we are very thankful to Radioking that he took it up. Time for user wiki 2.0!

long time no see. I’ve been sort of on a break for the past few weeks. I want to detail the reasons for this, just to clear out my head and give you insight into what happened over the last few months, explaining certain down-times.

From August 2011 to February 2012 i’ve been working for a mobile gaming startup in SF. Three months i spent at their office in SF, the rest i worked from home. It was an exhausting marathon, with work hours way beyond what’s healthy for me (can’t speak for the entire team). I was mentoring people, trying to coordinate the different sub dev-teams and come up with architectures for various parts of the application. It was an interesting ride, together with a team of very young folks, some of which i happen to think of as friends now. I eventually left the company for various reasons at the end of December. I just wasn’t happy. I continued to work with them for another month and a half on a contracting basis to help out with a few things until the middle of February or so.

Around November signs of burn out started to surface, but i largely ignored them. I just continued on working on even more stuff.

From January onwards i started working on private projects again. I rewrote Tyonar to allow multiple “instruments” and infinite steps. I never published it, not being happy with the user interface. I wrote a reddit client (APK), spent over a month on it but also never published it. I rewrote the libgdx build system, rewrote the way we handle native code, creating a tool that allows me to write JNI code faster, added tons of new extensions and finally added an entirely new backend so people can deploy HTML5 libgdx apps. I started working on the iOS backend again, completely switching it over to MonoTouch. I started a working on a pirate game with Shiu and Kalle. All of that was done in roughly 2 months. I took of maybe 2-4 days in total during that period, visiting Tamas and Nate in London. I can’t say it helped with the burn out thing.

My old company, for which i’ve been working for the last 6 years, made me a nice new offer which i couldn’t refuse. Whether this is a smart career decision i can’t tell. My record doesn’t look to diverse, i’ve been working for only 2 companies so far. However, I really like the job there, it’s a mixture of R&D and product development which allows me to get into all kinds of fields, from information retrieval solutions, to distributed computing, visual analytics, web-technologies and even some RFID work. I worked with an incredibly broad set of technologies over the years and helped ship quite a few products of our partners. The only thing i haven’t touched in depth are JavaEE technologies, which again might be a problem in terms of a future career path. I started working there at the beginning of April.

In mid April Apress approached me and asked if i wanted to write a real second edition of “Beginning Android Games”, this time without a missleading title like “Beginning Android 5 Games”. Robert and me agreed to do that, we just can’t give up our baby. The additions will mostly consist of overhauling the material that’s already there and adding chapters on integrating with in-app purchase services as well as one of the game services like Swarm or OpenFeint. That’s probably around ~60 new pages, a pretty standard delta between tech book editions. This will fill up most of my spare time for a few months i guess.

I’m in maintainance mode with libgdx, meaning i go onto the forums, fix the occassional issue on the tracker and write a bit of documentation. In terms of features there are two things that bug me: scene2d needs an overhaul in terms of API and documentation (we hinted at the former a while ago) and we need to finish the 3D API. Kalle has been doing a lot of awesome work in that regard, but i’m still responsible for the GL10 branch, and i just can’t get my ass up working on that. There’s also the problem of format support, i’d love to support FBX and make that the number one format, but FBX is a monster, and there’s only the FBX SDK which can handle most of the modeller apps out there. It’s a pain. The iOS port is also something i want to spent some time on. I would also like to see more people on the dev team, at the moment we have about 4-5 active committers. We can’t of course just let anyone contribute to core, but there’S a lot of places even inexperienced people can help out, e.g. cleaning up Javadocs and so on. Here’s a list of things that need to be done:

• Refactor Scene2d: getters/setters, exposing fields is incredibly stupid. This would mean reworking the UI framework as well. I’d also like to rework the action system, at least the interpolators.
• Complete the 3D API: implement GL10/GL20 renderer (the later is mostly done, thanks Kalle), add FBX loading support and integrate it into the core API.
• Look through the issues on the issue tracker and close as many as possible.
• Finish the development guide.
• Overhaul Javadocs where necessary.
• iOS port via MonoTouch.

If you think you can help out with any of those, we are happy to get you on board. You’ll have to follow a couple of rules of course, and if you work has a detrimental effect (breaks things, no compliance to set rules) we’ll likely revoke your contributor status. Yes, i’m a nazi.

Save for the iOS port, what do you think we should focus on? I’d really like to focus on docs for some time.

A full-time job, a book and libgdx is a lot of work. I need some time to reorganize my time schedule to make everything fit together. Rest assued that work on libgdx continues

• Tons of fixes for issues on the tracker, have a look yourself.
• Fixes and additions to the UI framework
• And all new build system that allows us to more easily integrate new extensions and backends.
• Big performance improvements for OpenGL ES 2.0 by using vertex arrays instead of VBOs for SpriteBatch and friends.
• Lifted the memory limit for native resources, see here.
• Non-continuous rendering support
• PixmapPacker, pack your images to a TextureAtlas at runtime.
• An entire new backend allowing you to target native HTML5 via GWT.
• Support for local files.
• gdx-stb-truetype, a wrapper around stb-truetype to generate BitmapFonts from Unicode characters. Sadly its visual quality is not to good for small font sizes
• gdx-jnigen, a tool that let’s you embed your JNI code in your Java files and helps you generate ant scripts to build the code for multiple platforms. All of libgdx’s native code has been converted to use this tool.
• gdx-audio, wraps libmpg123 and tremor to help you decode mp3 and ogg files to plain PCM samples, wraps SoundTouch to allow you to pitch shift and timestretch your PCM samples, wraps kissfft to give you the frequency domain of a signal.
• gdx-freetype, wraps FreeType and allows you to generate BitmapFonts on the fly from common TTF files.

There’s currently work being done on a Bullet Physics wrapper (gdx-bullet) and libjpeg/libpng/libgif wrapper (gdx-image). The Bullet Physics wrapper seems to be mostly complete but needs extensive testing. The image library wrapper is in it’s infancy, only libjpeg works for now. Both are packaged in the release for you to test them out if you wish.

We also created a few new ways to make libgdx project setup a lot easier. Check out this new Wiki page. Massive thanks to Aurelien Ribon for writting this fancy thing. I’ll add some screenshots to the article and will most likely replace the old introduction videos.

We also recognize the need for mavenization (edit: meaning everyone but Nate). We can now push artifacts to central, and as soon as i get the time, i’ll try to set things up so that happens automagically. Ruben and Arielsan of Gemserk kindly offered their help, so thanks for that as well.

I’ll write an extensive post on the new GWT backend asap. I’m working full time again since monday, so please be patient

== Game Name by [http://www.mycompany.com Company Name] ==
[http://www.link-to-my-game.com http://www.link-to-a-screenshot-of-mygame-705x345-max-resolution.jpg]
One paragraph description of your game, no longer than a hundred words. Embed additional 
links [http://www.my-other-link.com like this]. Do not include additional images or videos!

It would be preferable if you could use the banner that you uploaded to Google Play! Portrait screenshots should be scaled down to a height of 345. We’ll eventually write a thumbnailer. Also, please submit Jpegs only. The page will load like crap anyways, but with jpeg it might load a tad bit less like crap :p Your link must end in .png or .jpeg/.jpg, so do not just copy the link of your Banner on Google Play!

The result will be displayed here for now, i want that to be more structured in the future.

In your GWT project’s module file (gwt.xml), add the following line:

<set-configuration-property name="gdx.assetpath" value="path/to/your/assets"/>

That’s it. You can remove your assets.txt and the assets themselves from the war/ folder, the generator will copy them over everytime you launch or compile your HTML5 app. The path you specify can be absolute (bad if you share your project with other people) or relative to the GWT project’s root folder (e.g. “../superjumper-android/assets” for the superjumper-gwt project). The generator will output a ton of debugging messages, detailing what is going on.

The classification of assets into images, audio, text and binary files is done via an AssetFilter. If you do not specify your own, the DefaultAssetFilter is used. It’s pretty basic and might not fit your needs. If you want to overwrite that, implement the AssetFilter interface, make sure you have a public default constructor and that the class is accessible in your GWT project. Then add the following line to you GWT project’ module file:

<set-configuration-property name="gdx.assetfilterclass" value="your.package.name.and.ClassName"/>

The filter will then be instantiated by the generator and decide which files/directories to include and what AssetType they should have.

All demos and tests have been updated to use this mechanism, if in doubt, check those out.

To communicate with native code (non-Java, e.g. C/C++) one has two options. Either transfer data from the Java heap to the native heap, or allocate space on the native heap in the first place, circumnavigating the Java heap completely. One mechanism to do the later is to use direct buffers, A Java object that wraps the address and size of a native heap memory location. The VM usually doesn’t count the native heap memory of a direct buffer against it’s Java heap memory. Turns out Android’s Dalvik VM is special in that regard compared to say Hotspot.

The first, generally known, situation where the Dalvik VM counts native heap memory against the Java heap memory is the use of the Bitmap class. A Bitmap is a thin wrapper around a native heap memory area that stores pixel data. To enfore application memory limits, that native heap memory of the Bitmap is counted against the Java heap, which is limited to 16-25mb on Android. Hard to cope with for Android developers at times (see Stackoverflow), but understandable from the perspective that a mobile device has limited resources, even more so if you have true multitasking.

For direct buffers i assumed the situation to be different. Direct buffers provide a way to allocate memory outside the bounds of the Java heap memory and are not counted against the Java heap on most VMs. Let’s see what happens on Dalvik. Observe the following code:

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/java/java/nio/BufferFactory.java#L92

This method is called when one allocates a new direct ByteBuffer through ByteBuffer.allocateDirect(int numBytes), which returns a ByteBuffer that points at a native memory area of numBytes bytes. Following through we get to

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/java/java/nio/ReadWriteDirectByteBuffer.java#L47

which calls

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/java/java/nio/DirectByteBuffer.java#L64

This is where it gets interesting. The first statement in that constructor allocates the native memory through a call to PlatformAddressFactory.alloc(). The second statement tells the address wrapper object (SafeAddress) that this memory area should be automatically deallocated when the buffer instance (and thus the address wrapper instance) is garbage collected. Let’s see what the PlatformAddressFactory.alloc() method does.

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/java/org/apache/harmony/luni/platform/PlatformAddressFactory.java#L128

It calls into OSMemory.malloc(), which invokes a C++ method that actually allocates the native heap memory. Also observe line 140, where the memorySpy is informed of the newly allocated memory area. We’ll get to that later, as it has some more implications.

What happens in OSMemory.malloc()? This:

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/native/org_apache_harmony_luni_platform_OSMemory.cpp#L43

It actually tracks the native memory allocated and counts it against the Java heap:

jboolean allowed = env->CallBooleanMethod(gIDCache.runtimeInstance,
            gIDCache.method_trackExternalAllocation, static_cast<jlong>(size));

This will return false if the requested memory size would exceed the Java heap. In line 64 we see that the first 8 bytes store the size of the buffer so memory can be subtracted from the used Java heap size again if the buffer is deallocated (when it’s GCed), see

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/native/org_apache_harmony_luni_platform_OSMemory.cpp#L72

The second issue is the memory spy thing i mentioned above. What does that do? Bucket of salt: this is my understanding of it which might be wrong.

Every time we allocate a new direct buffer (and thus PlatformAddress) the memory spy is informed of that event. It keeps so called PhantomReferences to all of these PlatformAddresses. These references allow us to get information on whether a Java object was garbage collected. The problem is that you have to poll that information, as you can’t register a callback that gets invoked when the GC kills a Java object. So, the designers of that code had to come up with a mechanism to frequently do that.

https://github.com/CyanogenMod/android_libcore/blob/gingerbread/luni/src/main/java/org/apache/harmony/luni/platform/RuntimeMemorySpy.java#L50

This method is called whenever we allocate new native heap memory. The first couple of lines poll the reference queue, if a platform address was GCed, the spy can also free up the native heap memory (orphanedMemory(ref)). Due to this design you always leak one direct buffer, as you have to allocate a new buffer so that the polling mechanism is kicked off.

Games written in C/C++ do not suffer from these problems. They can allocate memory all day long without Android ever getting angry about it. Games like Shadowgun wouldn’t be possible without that ignorance of Dalvik. If you write a pure Java game for Android you’ll suffer from that problem.

For libgdx games you don’t have to worry as we added a very nasty 3 line hack that will ensure that the memory allocated for a ByteBuffer is not counted against the Java heap. While i completely understand that there have to be memory limits, the situation is different for games. Adding this little “hack” at least allows us to cheat just as the native guys do. (See BufferUtils#newUnsafeByteBuffer()).

I’d like to introduce a new change to libgdx, where we do not load any resources from disk anymore. Instead we cache everything (pixel and vertex data) in memory. This would mean we’d have to change the semantics of a few things for the better. Any unmanaged textures would be managed now, e.g. textures constructed from Pixmaps.

• Click on your Android Project
• Select Properties
• Select Java Build Path
• Select Order and Export
• Check all your references, e.g. the gdx.jar, the gdx-backend-android.jar, your main code project etc.

That’s it. Here’s a before and after image for a project that uses the jars.

You don’t necessarily have to check the .jar files in this case if they are in your Android project’s libs/ folder.

If you run from SVN, just check the referenced gdx and gdx-backend-android project in the same settings dialog.

Now i have to redo all the tutorials…

New Additions

• Reflection. Yes, that’s a stupid idea with GWT, but it enables a few things. You can’t use it for your own apps at the moment. Not sure i’ll open up that can of worms. If you are interested in how it works, check out this bozo.
• Json parsing with reflection. If you read into an ObjectMap things will just work. If you want to deserialize into your own POJOs i’ll have to add something so your POJOs are reflected.
• The entire scene2d package, including the UI stuff. This was enabled by adding basic Reflection capabilities
• All of Box2D works now, expect for GearJoint, WheelJoint and RopeJoint. The former two are currently broken in the JBox2D trunk, once those are fixed we have everything apart from RopeJoint.
• Preferences
• Fullscreen support
• Tons of other stuff under the hood that won’t affect you
• Binary file support, altough i recommend not using it, it’s slow by nature

You can try out most of our tests in HTML5 now. Some box2d tests might be slow due to ShapeRenderer. The box2d simulation itself runs blazingly fast

Todo

• Replace gwt-voices with something else, e.g. a Sound Manager 2 wrapper. I didn’t dig into the gwt-voices sources to much, but for some reason it refuses to work at all in Safari and partially in Firefox. Done, custom wrapper around SoundManager 2, a fantastic API that works perfectly.
• Fix the backspace button problem so UI textfields work. Done
• Add a very simple HttpUtils class that allows one to send POST/GET requests to a server. Note that due to the “Same Origin Policy” you’ll be restricted to send requests to the domain your app/game is hosted on.
• Go through the list of FIXMEs in the source. Done, anything that’s marked as FIXME is either undoable for now, or non-critical.

I’ll most likely not support local files for the time being. Preferences should be sufficient for most games for now.

What Won’t Work

Tilemaps, Audio recorder/device, that’s about it. If i can find a nice Gzip decoder for GWT we can add Tilemaps in as well. Other than that we’ll be pretty much feature complete.

Simple Tutorial

I didn’t have time to write a tutorial on how to port your game yet. Here’s a nice tutorial by Molded Bits on how to get started with the new backend. The markers for files in the assets.txt file are: i -> image, t -> text file, b -> binary file. For now i won’t pack the backend jar with the nightlies as i want things to mature a tiny bit. I’ll follow up with something more in depth that will also show you how you can debug the emitted Javascript easily if necessary.

Ports

Here are a few recent ports.

Pax Britannica by Stefan Wagner.

Mathematiles by Nex

Vector Pinball (see libgdx trunk/demos/)

Gdx invaders (see libgdx trunk/demos/)