Game Controller Programming Guide

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:

Learn how your game help a user discover an unpaired wireless controller

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.

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 to be called when the player presses the pause button

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

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.