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 can be connected to an iOS device, Apple TV, 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

A player index associates a controller with a specific player. Whenever your game uses a particular controller, you must set the playerIndex property to reflect which player is using that controller. For example, in a game between two players, both using controllers, you would set one controller to GCControllerPlayerIndex1 and the other to GCControllerPlayerIndex2. When you set the player index, it causes a matching LED on the controller to light up. Similarly, if your game stops using a particular controller, it should set the index to GCControllerPlayerIndexUnset. This value guarantees that the LEDs on the controller are not lit.