Porting your LibGDX game over to iPhone (via RoboVM) [Part 1]

I recently spent the better part of the last two days porting Fishy Business over to iPhone.  Performance is surprisingly superb with minimal code changes but the process was far from painless.

In some ways, I get the get the feeling that Murphy’s Law applies to everything I do, so I doubt anyone else will run into as many roadblocks as I did, but with a serious lack of LibGDX +RoboVM tutorials out right now, I feel compelled to give back to the community.

Prerequisites:

Functioning in the loosest sense…

(1) Functioning LibGDX game. Optimally, you’ve got your game compiling and running well on Android devices. I’ve noticed that custom shaders, deferred rendering, and FreeTypeFonts require some more effort to work properly, but almost everything else should work right out of the box! I’ll also go over some tips for using FreeTypeFonts later in the article.

(1) Apple MacBook/iMac/iDesktop – This is the deal breaker. If you want to publish on Apple’s ecosystem, you have to prove you’re part of the club by dropping a cool grand on an iDevice.  If you don’t have one of these, a) I don’t blame you, and b) you should probably stop reading this article.

(1) Optional: Subscription to iOS Developer Program. For just one annual payment of $99, you too can publish games on the app store! Luckily you can test your games out on the virtual machine without paying for the program. Unfortunately, if you want to install on your own iPhone/iPad or release on the app store you’re gonna have to pony up.

Step 1: Download/Update Xcode

Xcode Version 5.0.2
While you wait for it to download/update, ask yourself why Apple didn’t call it “iCode”…

Porting to iOS requires RoboVM which is dependent on Xcode. Do yourself a favor and make sure you have the latest version. At the very least you will need Version 5.0.1.

You can find Xcode on the Mac App Store.

Roadblock Ahead! When I attempted this process, I repeatedly had Xcode fail to update for no reason at all. It would download and install the whole package but never update the program! If this happens to you, try deleting your current installation. This will force the app store to download the latest version instead of trying to update.

Step 2: Install RoboVM Eclipse Plugin

I hope no one else suffers through this

RoboVM is awesome. Everything you need to compile onto an iPhone/iPad is contained in single Eclipse Plugin.  You can find the plugin here: http://download.robovm.org/eclipse/

For those on the remedial course, you can install plug-ins in Eclipse by clicking Help ->Install New Software. Then enter the URL above into the address bar.

Roadblock Ahead! Once the plug-in is installed, Eclipse will attempt to restart itself. A small number of you may see the following error:


Errors occurred during the build.
Error instantiating builder 'org.robovm.eclipse.RoboVMClassBuilder'
Plug-in org.robovm.eclipse.ui was unable to load class org.robovm.eclipse.internal.RoboVMClassBuilder.
An error occurred while automatically activating bundle org.robovm.eclipse.ui (244).
Plug-in org.robovm.eclipse.ui was unable to load class org.robovm.eclipse.internal.RoboVMClassBuilder.

Have no fear! This is because you have Java 6 installed on your system and the RoboVM plugin requires Java 7 (crazy!).  The easiest way to proceed is to update your version of Java. If you’re like me and keep Java 6 installed on your computer on purpose, then you can alternatively download the Java 7 JDK and use terminal to launch eclipse.

cd ~/<Eclipse Download Location>
./eclipse -vm ~/Desktop/jdk1.7.0_025.jdk/Contents/Home/bin/java

You can verify that everything properly installed by opening the “Preferences” window in Eclipse and finding the RoboVM line. On a Mac this is under “Eclipse” in the title bar.

Step 3: Download Gdx-Setup-Ui

It’s absolutely critical that you download the latest setup UI. Trust me, this was the first

Make sure you have a "robovm" project being generated!
Make sure you have a “robovm” project being generated!

mistake I made when embarking on this journey.  LibGDX is awesome because it’s constantly being updated by the team (thank you Mario!), the downside is that you’re constantly out of date.  At the time of this writing, I used Gdx-Setup-UI 3.0.0.

We’ll be using a dummy project to test our porting process to LibGDX, and to do that you can simply use the UI to create a new project with the exact same name as your real project in a temp directory. Once that’s done, copy over the new robo-vm folder into your regular project directory.  Now you can import the new robovm project into your workspace and you shouldn’t have any classpath errors!

Roadblock Ahead! If you downloaded the latest setup UI (like I told you to!), take the time now to update all of your LibGDX Jars! Your newly minted roboVM project is going to use the latest libgdx jar so it will expect the rest of your projects to have been updated as well. Copy over the jars from the other project directories you just created (desktop, android, etc), and overwrite the ones in your existing project. Failure to do this might lead to some crazy errors that you will not be able to debug! If you need more help on this step, check out this link.

Step 4: Verify Everything Worked!

Remember how I told you to use the LibGDX Setup UI to create a dummy project in a temp directory? Well I hope you did that because we’re going to use it to verify everything worked before porting our real game over.

Start by opening Eclipse into a new workspace. Import all the projects that you just generated using the Setup UI. These should be completely untouched files that the UI  created for you. Verify that everything worked by running the desktop version. 

Next right click your robovm project, select “Run As” -> “iOS Simulator App (iPhone)”.  Give it about 5 minutes to compile all of Java and LibGDX into Objective C and Voila! You’ve got an App running inside a simulator! Pat yourself on the back!

Hoorah!!

Now go to Part 2

Hopefully at this point you have something running inside the simulator! Now it’s time to move onto Part 2, where I’ll talk about getting registered as an iOS developer and running the app on your personal iPhone/iPad. I’ll also explain how to get LibGDX TrueTypeFonts running inside your iOS apps.  So what are you waiting for? Click the link to move on! I’ll see you after the break.

2 thoughts on “Porting your LibGDX game over to iPhone (via RoboVM) [Part 1]