Category Archives: Code

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

Welcome back!  This is Part 2 of Porting your LibGDX game to iOS.  I’m hoping you’ve either read Part 1, or already have a sample LibGDX project running inside iOS Simulator.  In this article we’re going to cover getting an iOS developer license, provisioning your iDevices (iPhone, iPad), and porting over your specific game code.

Fishy Business running inside the simulator
Fishy Business running inside the simulator

Achieving Developer Status

The Exclusive Club

Okay so step one, which will probably take you more time than all the other steps combined is to subscribe to the iOS developer program. Note you can totally skip this step and continue on using only the simulator, but I assume that if you’ve come this far you’ve probably got an iDevice you want to test on.

Start by getting your credit card out and heading to this page. You’ll need to register for an Apple ID if you don’t have one, and after that it’s pretty straight forward. In my case I was registering for myself, but you also have the option to register a company/organization.  Regardless of your decision, the price point is the same: $99 per year.

Roadblock Ahead! Once you submit your registration you will very quickly get an email from Apple saying, “your order is being processed.” You should also see a 10 digit confirmation code inside the email.  It usually takes Apple about 24 hours to verify your information and actually activate your membership, but there is a way to speed the process up. If you haven’t heard back in about 12-18 hours, you can call Apple’s  support line.  Their call-center is surprisingly good: during peak hours I had only a minute of wait time and after a short (5 minute)  call, the representative offered to speed up the process and activate my membership immediately.

Setting up Xcode

Alright, now minimize your browser and open up Xcode. In order to enable a phone to be used for testing you need to “provision” it. I think “provision” is Apple’s code word for “more hoops to jump through.” Anyways, it’s not a tough process once you figure it all out.

With Xcode open you should be able to plug your iPhone in and see the “Organizer” automatically pop up. If it doesn’t, click on Window->Organizer (Command+Shift+2). Next, find your iPhone/iPad under the “Devices” heading on the left hand side and click “Use for Development.”  Although this will configure your iDevice, you’re not actually out of the water yet.

Next, right click your device and click “Add to Member Center”.  You’ll have to enter your Member CenterApple ID credentials and Xcode will automatically “attempt” to provision your device. I say attempt because when I tried this I ended up in a pending state.  If you’re like me, you will see a message pop up telling you to wait a few seconds and “refresh your account”.

First attempt to refresh your account and see if that will fix the problem. You can do this by Accountsclicking Xcode (in the menu bar) -> Preferences. Select your Apple ID and click “View Details”.  Finally click the tiiinnny refresh icon in the bottom corner. You may see a message about creating a certificate/signing identity, obviously you should say yes :). If a signing identity and provisioning profile now appear in your accounts page, then congrats! Move onto the next step! Do not pass go, do not collect $200. If not, keep reading below.

Roadblock Ahead! Alright, your profile is pending and you don’t want to wait for Apple’s servers. Let’s see what we can do. Open your browser back up to the member center and
Provisioning
click on “Certificates, Identifiers, and Profiles”.  In the next page click “Provisioning
Profiles”. You should now see a screen with your “iOS Team Provisioning Profile”. It will be in the yellow “Pending” state. Eventually this will automatically turn green, but we’re far too impatient to wait :).

Instead, click the plus button and generate your own provisioning profile. I won’t hand-hold you through the process, it’s fairly straight forward. Once you’re done, download the
Provision
profile to your hard drive and import it into Xcode.   Also take this time to check the “Certificates” tab on the webpage and make sure you have a valid certificate. Xcode *should* have done this for you, but if not you can manually make it happen.

Finally, return to Xcode and repeat the instructions two paragraphs ago about refreshing your account. You should see a provisioning profile appear in your accounts page and in the dedicated “Provisioning Profiles” tab for your device.

Deploy to Device

Okay, I know this section is exciting and it’s what you’ve been waiting this whole time for, but let’s take it one step at a time. First double check with me that everything is in order by opening up a terminal and run this command:

 security find-identity -v -p codesigning

Verify that you see a signing entity returned with your name on it. Next it’s the moment of truth. Open up Eclipse, right click your test RoboVM project and click Run As-> iOS Device App. It should take a few moments to recompile everything but after it’s done it will attempt to install the executable directly onto the iPhone! If this works, fantastic! Move onto the next step! If not, stick around and i’ll help you debug.

Roadblock Ahead! Alright, so deploying to your iDevice didn’t work on the first try. No worries! It took me about four! Check the error that Eclipse returned, you may be able to debug it yourself. Here are some common ones I ran into:

  • Lock Screen Error: I saw this one when a) My Screen was locked (Duh!) or b) I hadn’t clicked “Trust” on the dialog that pops up on the iPhone. Either way, it’s pretty easy to fix
  • Unknown Error: I’ve seen this one every time I attempt to run on a new iPhone. It looks scary but oddly enough all I had to do was unplug the sucker, plug it back in, and try the process again.
  • No signing identity found matching ‘iPhone Developer” …: This one’s a doozy. It means Xcode hasn’t been setup properly and you’ll probably need to redo the steps in the last paragraph. Right click your RoboVM project in Eclipse->Run As->Run RoboVMConfigurations. In your RoboVM configuration check to see if your signing entity and provisioning profile appear correctly. Make sure it is the exact profile you want, if it says “Auto” click the drop down and select the exact one. If you can’t find your profile, go back a paragraph and re-do the Xcode setup steps :(

If you weren’t able to solve the problem with the tips above, or you have any other advice for other programmers *please* post a comment. I’d love to keep a running list of Tips & Tricks regarding deploying to an iDevice.

Port Your Game

score
Running on the iPhone!

Almost done! Now it’s finally time to port your actual game. If you followed my instructions you will have named your test project the exact same name as your actual game! This means you can copy over the RoboVM directory from the test project into your real project directory and import it directly into your eclipse workspace. If all goes well, you should have zero class path errors.

Roadblock Ahead!  I mentioned this before, but it bears repeating. Make sure you have updated your LibGDX jars in all of your projects! If you don’t do this, you may end up with some really funky errors that arise from cross-compatability issues. For more on this, see Part 1.

Now look at the RoboVMLauncher.java. For the most part, configuring this file is very similar to configuring an android application. The LibGDX team has really done a great job. If you need to go ahead and change this file up to suit your boostrapping needs. For example, my file looks like this for Fishy Business:

import org.robovm.cocoatouch.foundation.NSAutoreleasePool;
import org.robovm.cocoatouch.uikit.UIApplication;
import com.badlogic.gdx.backends.iosrobovm.IOSApplication;

import com.badlogic.gdx.backends.iosrobovm.IOSApplicationConfiguration;

public class RobovmLauncher extends IOSApplication.Delegate {

@Override

protected IOSApplication createApplication() {

IOSApplicationConfiguration config = new IOSApplicationConfiguration();

config.orientationLandscape = false;

config.orientationPortrait = true;

return new IOSApplication(new ChanseyMain(new iOSInput()), config);

}

public static void main(String[] argv) {

NSAutoreleasePool pool = new NSAutoreleasePool();

UIApplication.main(argv, null, RobovmLauncher.class);

pool.drain();

}

}

This next part is going to highly project specific and there really isn’t much advice I can give to you. Honestly if you’ve got the test app running on your iDevice and have gotten this far, I have full faith you’ll get your own project working! Good luck, and here are a few things I’ve noticed:

  • Shaders don’t work perfectly: Fishy Business uses some custom shaders in order to achieve a viscosity effect on the water particles. When I deployed to iOS I found that the shaders didn’t look nearly as nice. I’m still trying to figure out how to fix this.
  • Deferred Rendering has bad Perf: Again for our water particles, I render off screen to a separate frame buffer. I’ve deployed on a number of Android devices and I’ve never seen any performance problems but when I deployed on my iPhone I noticed immediately that it was dropping frames. Disabling the water particles completely fixed all of these issues.
  • There is a special “Data” directory: If you look closely you will find that your RoboVM Eclipse project has it’s own data directory. This isn’t for your regular art assets, it’s a special directory with images you need to replace. There are two kinds of images, one is the Icon for your game and the other functions as your loading screen.
  •  FreeTypeFonts need to be setup to work: More on this below, but like deploying to Android, you need to follow a couple steps in order to get FreeTypeFonts to work.

Bonus: Free Type Fonts

Fishy Business relies pretty heavily on generating fonts on the fly — and for this reason we use the FreeTypeFont library included with LibGDX. I highly recommend that everyone move over to generating fonts on the fly instead of relying on Hiero (but that’s for another article). If your game uses FreeTypeFonts as well, here is how I got them working on iOS:

  1. Add libgdx-freetype.a to your libs->iOS folder in the RoboVM project. You can find the file inside the zip file downloaded by GDX Project Setup or just click this link.
  2. Edit robovm.xml and add libgdx-freetype.a under <libs>:
    <libs>
    libs/ios/libgdx.a
    libs/ios/libObjectAL.a
    libs/ios/libgdx-freetype.a
    
    </libs>
    
  3. Add gdx-freetype.jar to your RoboVM project under the libs directory. (Hint: gdx-freetype.jar should already be in your Android libs directory. Just copy it over)
  4. Add gdx-freetype.jar to your classpath inside your RoboVM project
  5. ???
  6. Profit!

dragonChar

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.