iOS Developer Library

Developer

Game Controller Framework Reference GCController Class Reference

Options
Deployment Target:

On This Page
Language:

GCController

A GCController object represents a physical game controller that is communicating with the device. Controllers can be physically connected to the device or through a wireless connection.

  • Starts browsing for nearby controllers.

    Declaration

    Swift

    class func startWirelessControllerDiscoveryWithCompletionHandler(_ completionHandler: (() -> Void)?)

    Objective-C

    + (void)startWirelessControllerDiscoveryWithCompletionHandler:(void (^)(void))completionHandler

    Parameters

    completionHandler

    A block to be called when browsing ends.

    Discussion

    You should include a user interface in your game to allow the player to determine when controllers are discovered. When the user chooses to search for controllers, call this method. The device searches asynchronously for discoverable wireless controllers as well as controllers that are connected to iOS devices that have been placed in controller-forwarding mode. Whenever a new controller is connected, a GCControllerDidConnectNotification notification is posted. When no more devices can be found or the discovery process times out, the completion handler is called.

    If this method is called multiple times, only the block associated with the last invocation is called when discovery times out.

    Availability

    Available in iOS 7.0 and later.

  • Stops browsing for nearby controllers.

    Declaration

    Swift

    class func stopWirelessControllerDiscovery()

    Objective-C

    + (void)stopWirelessControllerDiscovery

    Discussion

    This method may be called at any time. If a search for new wireless controllers in progress, that search ends and its completion handler is called.

    Availability

    Available in iOS 7.0 and later.

  • The controllers connected to the device.

    Declaration

    Swift

    class func controllers() -> [GCController]

    Objective-C

    + (NSArray<GCController *> *)controllers

    Return Value

    An array of GCController objects for all currently connected controllers.

    Discussion

    Whenever a controller is connected to or disconnected from the device, the array of controllers is updated and a notification is posted.

    Availability

    Available in iOS 7.0 and later.

  • The gamepad profile. (read-only)

    Declaration

    Swift

    var gamepad: GCGamepad? { get }

    Objective-C

    @property(nonatomic, retain, readonly) GCGamepad *gamepad

    Discussion

    If the controller supports the gamepad profile, then this property holds a GCGamepad object. You use this object to access the input elements of the controller. If the controller does not support the gamepad profile, this property holds nil.

    Availability

    Available in iOS 7.0 and later.

  • The extended gamepad profile. (read-only)

    Declaration

    Swift

    var extendedGamepad: GCExtendedGamepad? { get }

    Objective-C

    @property(nonatomic, retain, readonly) GCExtendedGamepad *extendedGamepad

    Discussion

    If the controller supports the extended gamepad profile, then this property holds a GCExtendedGamepad object. You use this object to access the input elements of the controller. If the controller does not support the extended gamepad profile, this property holds nil.

    Availability

    Available in iOS 7.0 and later.

  • The motion input profile. (read-only)

    Declaration

    Swift

    var motion: GCMotion? { get }

    Objective-C

    @property(nonatomic, retain, readonly) GCMotion *motion

    Discussion

    If the controller supports the motion profile, then this property holds a GCMotion object. This profile is typically available when the controller is attached to a device that supports motion. You use this object to access the motion data of the controller. If the controller does not support the motion input profile, this property holds nil.

    Availability

    Available in iOS 8.0 and later.

  • A block called when the controller’s pause button is pressed.

    Declaration

    Swift

    var controllerPausedHandler: ((GCController) -> Void)?

    Objective-C

    @property(nonatomic, copy, nonnull) void (^controllerPausedHandler)( GCController *controller)

    Discussion

    All controllers have a button that allows the player to suspend the current gameplay. When pressed, the block associated with this property is called. Your game should toggle between pausing and resuming gameplay. When paused, your game must display a user interface that indicates that the game is paused. This interface should tell the player how to resume the game. The exact design of this user interface is up to you; typically it should match the style of the rest of your game.

    If your game is paused for other reasons defined by your game, and is in a state where it can be resumed, pressing the pause button should resume gameplay. Which is to say that the pause button on the controller as well as other things that pause gameplay should all present a seamless interface to the player.

    Availability

    Available in iOS 7.0 and later.

  • A Boolean property that indicates whether the controller is closely integrated with the device. (read-only)

    Declaration

    Swift

    var attachedToDevice: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isAttachedToDevice) BOOL attachedToDevice

    Discussion

    If YEStrue, then the controller is attached to the device or is close enough to it for the player to interact simultaneously with the controller and the device. If NOfalse, then the controller is not guaranteed to be near the device.

    Availability

    Available in iOS 7.0 and later.

  • The name of the vendor that manufactured the controller. (read-only)

    Declaration

    Swift

    var vendorName: String? { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSString *vendorName

    Discussion

    The value of this property may be nil and is not guaranteed to be unique.

    Availability

    Available in iOS 7.0 and later.

  • The player index assigned to the controller.

    Declaration

    Swift

    var playerIndex: GCControllerPlayerIndex

    Objective-C

    @property(nonatomic) GCControllerPlayerIndex playerIndex

    Discussion

    The player index is a value that determines which player is associated with the controller. Whenever your game is actively using a particular game controller, you must set the player index to a proper player index. Typically, you do this when the controller is first connected and configured by your game. You are not required to provide a unique player index for each active game controller. For example, you could have all players on the same team share a common player index. If a controller is no longer in use by your game, you must set the controller’s index value to GCControllerPlayerIndexUnset.

    The default value is GCControllerPlayerIndexUnset.

    When a player index is set, the matching LED on the controller for that player lights up.

    Availability

    Available in iOS 7.0 and later.

  • The dispatch queue to be used when the values of a game controller’s input values change.

    Declaration

    Swift

    var handlerQueue: dispatch_queue_t

    Objective-C

    @property(retain) dispatch_queue_t handlerQueue

    Discussion

    When a controller’s input values change, if there are any value-changed handlers associated with the controller’s profile objects, those handlers are called. The value of this property determines which queue those callbacks are sent on.

    By default, callbacks are made on the main dispatch queue. You typically change this value when your game’s input logic is handled on an alternate thread. You should change the value of the handlerQueue property only when there are no handlers associated with the controller; typically, you perform this step once, after your game first acquires a controller object.

    Availability

    Available in iOS 9.0 and later.

  • Predefined values for controller indices.

    Declaration

    Swift

    enum GCControllerPlayerIndex : Int { case IndexUnset case Index1 case Index2 case Index3 case Index4 }

    Objective-C

    typedef enum GCControllerPlayerIndex : NSInteger { GCControllerPlayerIndexUnset = -1, GCControllerPlayerIndex1 = 0, GCControllerPlayerIndex2, GCControllerPlayerIndex3, GCControllerPlayerIndex4, } GCControllerPlayerIndex;

    Constants

    • IndexUnset

      GCControllerPlayerIndexUnset

      The default index for a player on a controller. No lights are lit on the controller.

      Available in iOS 7.0 and later.

    • Index1

      GCControllerPlayerIndex1

      Specifies that player one is using this controller.

      Available in iOS 9.0 and later.

    • Index2

      GCControllerPlayerIndex2

      Specifies that player two is using this controller.

      Available in iOS 9.0 and later.

    • Index3

      GCControllerPlayerIndex3

      Specifies that player three is using this controller.

      Available in iOS 9.0 and later.

    • Index4

      GCControllerPlayerIndex4

      Specifies that player four is using this controller.

      Available in iOS 9.0 and later.

    Import Statement

    Objective-C

    @import GameController;

    Swift

    import GameController

    Availability

    Available in iOS 9.0 and later.

  • Posted immediately after a new controller is connected to the device.

    The notification object is the GCController object that represents the connected device.

    Declaration

    Swift

    let GCControllerDidConnectNotification: String

    Import Statement

    Objective-C

    @import GameController;

    Swift

    import GameController

    Availability

    Available in iOS 7.0 and later.

  • Posted immediately after a controller is disconnected from the device.

    The notification object is the GCController object that represented the disconnected device.

    Declaration

    Swift

    let GCControllerDidDisconnectNotification: String

    Import Statement

    Objective-C

    @import GameController;

    Swift

    import GameController

    Availability

    Available in iOS 7.0 and later.