Adding iCade Support to Your Game

This is a blog post by iOS Tutorial Team member Jacob Gundersen, an indie game developer who runs the Indie Ambitions blog. Check out his latest app – Factor Samurai!

The iCade is a miniature arcade cabinet for your iPad. It communicates with the iPad over Bluetooth, and allows you to play iCade-compatible games with button-mashing fun!

The iCade may be the most widely-supported external game controller for iOS devices today. Over 70 games are iCade-compatible, and more coming all the time!

Recently the creators of the iCade announced several new types of iCade devices. I’m excited to see these new devices, and I hope that more developers will integrate iCade support into their games.

And that got me thinking… I should write a quick tutorial showing you guys how to do exactly that! :]

Making your game iCade-compatible has the following benefits:

• Widespread support. Besides the iCade (and now the new devices) the iControlPad and even this retro NES controller can emulate the iCade interface. So if you’re compatible with one, you’re compatible with all!
• Good for indies. As indie developers trying to get our games noticed, adding iCade support isn’t a bad strategy, as the list of games that do support it is still relatively small. Only about 70 games are currently listed, so your game could be this small list for iCade owners hungry for compatible games!
• Joysticks rule! Perhaps the biggest reason to support the iCade is that touchscreen joysticks are a miserable way to play a game that’s designed to use a joystick interface. I’ve been itching to create a game that uses the iCade since I got one a few months ago, so as part of the Platformer Starter Kit I’m working on (and announcing this very second!), I’m integrating support for the iCade.

To run through this tutorial, you will need an iCade. You can get one on Amazon.com for about $80. But if you’re a retro gamer, it’s worth it ;]

Convinced yet? Bring out your iCade and let’s get started! :]

Getting Started

The game we will be making iCade compatible.

In this project, you’re going to modify the Raycast game from this tutorial.

However, don’t download the project from that tutorial! Instead, download this slightly modified version.

Here I’ve added some extra files we need for the tutorial – some button images, and the iCade interface library (which we’ll discuss in a minute).

In this tutorial, first you’re going to refactor the controls to use an on-screen joystick instead of the current simple touch interface. Then you’ll integrate iCade support as well!

Note that your game will still work with the on-screen joystick, so you won’t absolutely need iCade to play it. It will just be a nice bonus for those who have it :]

Note: According to the iCade support document, you can’t mention iCade in any way in the iTunes description of your app. Does anyone know if this is true (or can you get away with it)?

By the end of this tutorial, users will be able to play your game with the onscreen controls or the iCade, and the interface will function similarly in both cases.

iCade Overview

Before we begin, let’s discuss the basics of how iCade and its interface library work.

The iCade emulates a Bluetooth keyboard. There are four joystick directions (up, down, left, right) and there are eight arcade buttons. Each press or release of a button sends a character as if it had been pressed on a Bluetooth keyboard.

So, for example, pressing the joystick up sends ‘W’ and releasing the joystick back to center sends ‘E’, as you can see in this diagram from the iCade Developer’s PDF:

The characters are only sent once, not continuously. So it is up to your code to keep track of which buttons are currently pressed or released. You can see all the key mappings here.

In order to receive button-presses from the iCade (again, which acts as a Bluetooth keyboard), you have to create a view that receives this text input. Luckily, you don’t have to write this code yourself though, because there’s a great library you can use!

iCade Interface Library Overview

Stuart Carnie has written a great library that makes it much easier to work with iCade input, and he deserves the thanks of all who are reading this tutorial!

I’ve already integrated his library into the starter project, but you should download the project from Github anyway, because you’ll need the test project that comes with it in a second.

The main class you’ll be using is the iCadeReaderView. This is a UIView subclass that implements the UIKeyInput delegate protocol. You will create this view and add it as a subclass to your glView. It will receive these keystrokes (invisibly) and keep track of the state information.

There are two ways of accessing the state of the iCadeReaderView class:

1. The iCadeState property. This property is a bitmask that keeps track of all the buttons that are currently pressed.
2. The iCadeEventDelegate protocol. You can also implement the iCadeEventDelegate protocol and set yourself as the delegate. The delegate will receive messages every time the state changes (both when buttons are pressed and when they are released).

I find that this second method is easier to use. If we were to query the iCadeState property, we’d need do so within each update method. If we use the delegate, we can push the information from the iCadeReaderView class to whatever class we want (like the HUD) and keep track of the state there.

To get started, let’s go through the process of testing the iCade Bluetooth pairing and looking at the properties you can use in the class.

We’ll go over pairing the iCade as a Bluetooth device and using the iCadeReaderView test project to take a look at how it works. You can safely skip this section if you’re comfortable with Bluetooth pairing and the basic communication with the iCadeReaderView class.

Pairing the iCade with Your iOS Device

On your iPad (or iPhone – this all works there as well), go into your Settings app and choose General, then Bluetooth. Switch Bluetooth on if it’s not already. Your iPad will say Searching… under the devices list. Now we’ll go to the iCade.

Press the bottom four buttons and the top white button (far right) and hold them down at the same time. This puts the iCade into pairing mode. The coin slot will start to blink if this is done right.

On your iPad, an alertview will pop up and give you a four-digit pin to enter into the iCade. This is done with the buttons and the joystick. There’s a graphic that illustrates the mapping between the numbers and the buttons.

Once you’ve put in the pin and pressed enter (either white button), the iPad should have a device in the list named ‘ION iCade Game Controller,’ and the status should be connected. If it’s not connected, choose the device from the devices list on the iPad, and iPad will search for it.

Also, the iCade may have turned itself off. Press any button on the iCade to turn it back on. You’ll know it’s on because the coin slot will be lit. That should do it – you are now paired with your iCade.

All of these pairing instructions are written on the underside of the top of the iCade cabinet, along with the graphic that shows the numbers mapping for the pin entry.

Keep in mind that this is a Bluetooth keyboard, so any text input will no longer bring up the onscreen keyboard. In order to get it back, you’ll have to disconnect from the iCade, so download any games or anything that requires you type before you do all of this. The easiest way (that I’ve found) to disconnect the iCade is to turn Bluetooth off.