Discovering and Connecting to Controllers

In your game, a physical controller is represented by a GCController object. When a controller is connected, an object is automatically created by the Game Controller framework. You then use this object to configure the controller and read its inputs.

In this chapter, you:

Discovering Wireless Controllers

A wireless controller must be discovered before it will connect to an iOS device or Mac. The discovery process is triggered on both the controller and the device, and the two are allowed to connect to each other. After discovery is complete, the devices are paired and the controller is connected. A new controller is discovered only once. After that, if the device and the controller are both turned on simultaneously, they automatically find and connect to each other.

Normally, discovery occurs outside your game—that is, a player usually pairs the controller before launching your game. However, you can let a player discover new controllers from within your game.

The discovery process follows these steps:

  1. To start discovering new controllers, call the startWirelessControllerDiscoveryWithCompletionHandler: class method, passing in a completion handler. New controllers are automatically discovered and paired with the device.

  2. The discovery process eventually stops after some time has passed, but to end it early, you can call the stopWirelessControllerDiscovery class method.

  3. After the discovery process ends, the Game Controller framework calls your completion handler.

Here are some useful guidelines to consider when implementing support for discovery:

Finding Connected Controllers

After your app has finished launching, the operating system automatically creates a list of connected controllers. Call the controllers class method to retrieve an array of GCController objects for all connected controllers. Next, use these objects to configure the controllers or read the controller’s inputs. If there are no connected controllers or you call this method while your app is launching, the array will be empty.

After the initial list of controllers is populated, the Game Controller framework posts notifications when a controller is connected (GCControllerDidConnectNotification) or disconnected (GCControllerDidDisconnectNotification). Your game should almost always register for both notifications to provide a proper user experience. The notification object’s object property holds the GCController object for the controller whose status has just changed.

Because the number of controllers may vary, you need the appropriate behavior for your game. Here are some guidelines:

Using a Controller Object

Typically, you want to maintain a strong reference to controller objects for connected controllers used by your game. Use these objects to perform controller-related tasks. For example, you often need to:

Some of these tasks are introduced here. For specific details, see GCController Class Reference.

Player Indices Identify a Controller Persistently

A player index associates a controller with a specific player. The playerIndex property is a persistent value stored in the physical controller. It keeps the same index value until a game on the device changes its value.

Here are some guidelines for player indices:

  • When a controller is connected and your game is in the foreground, set the controller’s index to a value that makes sense in your game.

  • An index value can be 0 or any positive integer value, but usually you use the numbers ranging from 0 through 3. Using a value in this range causes the matching LED on the controller to light up.

  • If you do not want to identify a controller, assign it the value GCControllerPlayerIndexUnset. This value guarantees that the LEDs on the controller are not lit. For example, you might do this for a controller that is connected but not currently being used by your game.