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:

• Design and display an appropriate interface to the user. There is no built-in user interface displayed when in discovery mode. The framework manages only the discovery process. You might provide a button in your user interface to start the process and change it to a cancel button while the discovery process is active.

• Pause active gameplay until the discovery process completes.The discovery process may take a long time to complete, and the player may be unable to interact with your game while pairing the controller.

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:

• If no controllers are connected, use your standard user interface to control your game.

• If a single controller is connected, always use it.

• If multiple controllers are connected and one of them is a formfitting controller, make it the default controller. If all of the connected controllers are standalone, provide a way for players to select a controller.

• If multiple controllers are connected and your game supports multiple players, assign a controller to each player.

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:

• Get information about the controller, such as whether or not it is a formfitting controller

• Configure a player index on the controller so that you can associate it with a specific player

• Assign a block to a controller object’s controllerPausedHandler property

• Read the controller object’s profile properties to obtain controller input; see Working with Controller Elements

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