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
GCControllerobjects for connected controllers
Configure a connected 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.
The discovery process follows these steps:
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.
The discovery process eventually stops after some time has passed, but to end it early, you can call the
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
controllerPausedHandlerproperty 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
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
0or any positive integer value, but usually you use the numbers ranging from
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.