GameController — Apple framework reference

GameController lets your app discover, connect to, and read input from game controllers, remotes, keyboards, and mice across iOS, macOS, tvOS, and visionOS. You work with a GCController to access its profiles, reading buttons through GCControllerButtonInput, analog sticks and triggers through GCControllerAxisInput and GCControllerDirectionPad, and extended layouts via GCExtendedGamepad, including device-specific types such as GCDualSenseGamepad and GCDualShockGamepad. Beyond input, the framework exposes device features like GCDeviceBattery, GCDeviceLight, and GCDeviceHaptics for haptic feedback, and supports adaptive triggers through GCDualSenseAdaptiveTrigger.

Essentials 4

Discover, connect to, and identify the controllers and devices providing input to your app.

Cl
GCControlleriOS 7.0+
Controllers are available to an application that links to GameController.framework. There are 2 ways to access controllers
Pr
GCDeviceiOS 14.0+
A protocol that defines the common properties of all input devices, such as controllers and keyboards.
Cl
GCDeviceType
A class representing a type of spatial accessory.
En
GCControllerPlayerIndexiOS 7.0+
This is the player index that a connected controller will have if it has never been assigned a player index on the current system.

Gamepad Profiles 4

Standard gamepad layouts that expose buttons, sticks, triggers, and direction pads across device families.

Cl
GCExtendedGamepadiOS 7.0+
An object that represents the standard extended gamepad profile with two sticks, triggers, and a full button set.
Cl
GCMicroGamepadiOS 9.0+
An object that represents the micro gamepad profile used by remotes and minimal controllers.
Cl
GCDirectionalGamepadiOS 14.3+
Directional Gamepad profile.
Cl
GCGamepad
An object that represents the legacy standard gamepad profile with a direction pad and face and shoulder buttons.

Device-Specific Controllers 4

Profiles tailored to specific hardware such as DualSense, DualShock, and Xbox controllers.

Cl
GCDualSenseGamepadiOS 14.5+
The GCDualSenseGamepad profile represents any supported DualSense controller.
Cl
GCDualShockGamepadiOS 14.0+
The GCDualShockGamepad profile represents any supported DualShock 4 controller.
Cl
GCXboxGamepadiOS 14.0+
The GCXboxGamepad profile represents any supported Xbox controller.
Cl
GCDualSenseAdaptiveTriggeriOS 14.5+
DualSense triggers are required to be analog inputs. Common uses would be acceleration and decelleration in a driving game for example.

Reading Input Elements 8

Read values from individual controller elements like buttons, axes, direction pads, and touchpads.

Cl
GCControllerElementiOS 7.0+
Every controller element knows which collection it belongs to and whether its input value is analog or digital.
Cl
GCControllerButtonInputiOS 7.0+
An object that reads the pressed state and analog value of a controller button.
Cl
GCControllerAxisInputiOS 7.0+
An object that reads the value of a single analog axis, such as a trigger or one dimension of a stick.
Cl
GCControllerDirectionPadiOS 7.0+
A direction pad is a common grouping of 2 axis inputs where the input can also be interpreted as 2 sets of mutually exclusive button pairs.
Cl
GCControllerTouchpadiOS 13.0+
A touchpad is a touch-based two axis input with a notion of "touch state". It keeps track of
Cl
GCPhysicalInputProfileiOS 14.0+
A game controller profile representing physical buttons, thumbsticks, dpads, etc... on a controller.
Cl
GCControllerLiveInputiOS 17.0+
An object that provides continuously updated input from a connected controller.
Cl
GCControllerInputStateiOS 17.0+
An object that captures the state of a controller's input elements at a moment in time.

Physical Input Model 9

Protocols and types that describe controller elements, their state, and changes in a hardware-agnostic way.

Pr
GCDevicePhysicalInputiOS 16.0+
An objecting conforming to \c GCDevicePhysicalInput provides properties and
Pr
GCDevicePhysicalInputStateiOS 16.0+
An object conforming to \c GCDevicePhysicalInputState contains the state of
Pr
GCDevicePhysicalInputStateDiffiOS 16.0+
An object conforming to the \c GCDevicePhysicalInputStateDiff protocol
Pr
GCPhysicalInputElementiOS 16.0+
The \c GCPhysicalInputElement protocol is a base protocol for specific types
St
GCPhysicalInputElementCollectioniOS 16.0+
A structure that holds a collection of a device's physical input elements keyed by name.
Pr
GCPhysicalInputSourceiOS 17.0+
A description of the actual physical input element that a user interacts
Pr
GCPhysicalInputExtentsiOS 26.2+
Physical extents scale the normalized value reported by `GCLinearInput`
En
GCDevicePhysicalInputElementChangeiOS 16.0+
Constants that describe how a physical input element changed between states.
St
GCPhysicalInputSourceDirectioniOS 17.0+
One or more directions associated with a \c GCPhysicalInputSource.

Element Protocols 11

Protocols that classify input elements by their behavior, such as buttons, axes, switches, and direction pads.

Pr
GCButtonElementiOS 16.0+
An object conforming to \c GCButtonElement represents a momentary switch,
Pr
GCAxisElementiOS 16.0+
A protocol for input elements that behave as one-dimensional analog axes.
Pr
GCAxis2DInputiOS 17.4+
An object conforming to \c GCAxis2DInput represents an input that produces a
Pr
GCAxisInputiOS 16.0+
An object conforming to \c GCAxisInput represents an input that produces
Pr
GCDirectionPadElementiOS 16.0+
An object conforming to \c GCDirectionPadElement represents a four-way
Pr
GCSwitchElementiOS 16.0+
An object conforming to \c GCSwitchElement represents a latching switch.
Pr
GCLinearInputiOS 16.0+
An object conforming to \c GCLinearInput represents an input that produces
Pr
GCPressedStateInputiOS 16.0+
An object conforming to \c GCPressedStateInput represents the pressed state of
Pr
GCTouchedStateInputiOS 16.0+
An object conforming to \c GCTouchedStateInput represents the touched state of
Pr
GCRelativeInputiOS 16.0+
An object conforming to \c GCRelativeInput represents an input that reports
Pr
GCSwitchPositionInputiOS 16.0+
A protocol for reading the discrete position of a switch input.

Element Names 6

Typed identifiers that name standard buttons, axes, direction pads, and switches.

St
GCPhysicalInputElementNameiOS 16.0+
A structure that provides typed names for standard physical input elements.
St
GCButtonElementNameiOS 16.0+
A structure that provides typed names for standard button input elements.
St
GCAxisElementNameiOS 16.0+
A structure that provides typed names for standard axis input elements.
St
GCDirectionPadElementNameiOS 16.0+
A structure that provides typed names for standard direction pad input elements.
St
GCSwitchElementNameiOS 16.0+
A structure that provides typed names for standard switch input elements.
Pr
GCPhysicalInputElementTypedNameiOS 17.0+
A type-safe key for accessing elements of a `GCPhysicalInputElementCollection`.

Keyboard and Pointer Input 8

Read input from connected keyboards, mice, styluses, and on-screen cursors.

Cl
GCKeyboardiOS 14.0+
GCKeyboard is available to an application that links to GameController.framework
Cl
GCKeyboardInputiOS 14.0+
Keyboard profile. Contains the current state of buttons specified in GCKeyCodes.h.
St
GCKeyCodeiOS 14.0+
A set of low level key codes that can be used to access keyboard buttons
Cl
GCMouseiOS 14.0+
Mice are available to an application that links to GameController.framework. There are 2 ways to access mice
Cl
GCMouseInputiOS 14.0+
Mouse profile that represent a physical mouse object with two axis cursor, two axis scroll,
Cl
GCDeviceCursoriOS 14.0+
A cursor is a Direction Pad that has its axis extended from [-1; 1] to [width; height] range
Cl
GCStylus
An object that represents a physical stylus connected to the device.
Cl
GCSpatialAccessory
An object that represents a spatial accessory and reports its tracked input.

Motion Sensing 6

Read accelerometer, gyroscope, and attitude data from controllers that report motion.

Cl
GCMotioniOS 8.0+
A profile for getting motion input from a controller that has the ability to measure acceleration
St
GCAccelerationiOS 8.0+
A 3 dimensional acceleration vector measured as scalar multiples of earth's gravitational acceleration, G.
St
GCRotationRateiOS 8.0+
A structure containing 3-axis rotation rate data.
St
GCEulerAnglesiOS 8.0+
A structure containing 3-axis rotation data. The angles are rotated in order or pitch then yaw then roll.
St
GCQuaternioniOS 8.0+
Represents a quaternion (one way of parameterizing attitude).
St
GCPoint2iOS 17.4+
A structure that represents a two-dimensional point with x and y components.

Device Features 5

Access controller hardware features such as the battery, light, color, and haptic feedback.

Cl
GCDeviceBatteryiOS 14.0+
A controller battery is an abstract representation of the battery level and battery status of a GCController instance.
Cl
GCDeviceLightiOS 14.0+
A controller light is an abstract representation of the light-emitting capabilities of a GCController instance.
Cl
GCColoriOS 14.0+
Represents a color used by a GCDeviceLight.
Cl
GCDeviceHapticsiOS 14.0+
An object that creates and plays haptic feedback on a controller that supports it.
St
GCHapticsLocalityiOS 14.0+
A GCHapticsLocality represents the locations of haptic actuators on a

Snapshots 10

Capture and serialize the state of a gamepad profile for recording, replay, or transmission.

Cl
GCExtendedGamepadSnapshot
A GCExtendedGamepadSnapshot snapshot is a concrete GCExtendedGamepad implementation. It can be used directly in an
St
GCExtendedGamepadSnapshotData
A structure that holds the serialized state of an extended gamepad profile.
St
GCExtendedGamepadSnapShotDataV100
A structure that holds version 1.0.0 serialized state of an extended gamepad profile.
En
GCExtendedGamepadSnapshotDataVersion
Constants that identify the version of an extended gamepad snapshot data format.
Cl
GCMicroGamepadSnapshot
A GCMicroGamepadSnapshot snapshot is a concrete GCMicroGamepad implementation. It can be used directly in an
St
GCMicroGamepadSnapshotData
A structure that holds the serialized state of a micro gamepad profile.
St
GCMicroGamepadSnapShotDataV100
A structure that holds version 1.0.0 serialized state of a micro gamepad profile.
En
GCMicroGamepadSnapshotDataVersion
Constants that identify the version of a micro gamepad snapshot data format.
Cl
GCGamepadSnapshot
A GCGamepadSnapshot snapshot is a concrete GCGamepad implementation. It can be used directly in an
St
GCGamepadSnapShotDataV100
A structure that holds version 1.0.0 serialized state of a standard gamepad profile.

Event Handling and Settings 5

Route controller events through your app and manage controller-related system settings.

Cl
GCEventViewControlleriOS 9.0+
A view controller subclass that allows fine grained control of the user interface system's handling
Cl
GCEventInteractioniOS 18.0+
An interaction that indicates the view's intent to receive game controller
Cl
GCControllerHomeButtonSettingsManageriOS 27.0+
Access the game controller system Home button settings.
St
GCUIEventTypesiOS 18.0+
Constants that represent types of events.
St
GameControllerEventHandlingOptions
An option set that configures how the system delivers game controller events to your app.

Type Aliases 16

Ty
GCControllerAxisValueChangedHandler
Set this block if you want to be notified when the value on this axis changes.
Ty
GCControllerButtonValueChangedHandler
Set this block if you want to be notified when the value on this button changes.
Ty
GCControllerButtonTouchedChangedHandler
Set this block if you want to be notified when the touched state on this button changes.
Ty
GCControllerDirectionPadValueChangedHandler
Set this block if you want to be notified when the value on this axis changes.
Ty
GCControllerTouchpadHandler
Set this block if you want to be notified when an axis or the touch state changes.
Ty
GCExtendedGamepadValueChangedHandler
Set this block if you want to be notified when a value on a element changed. If multiple elements have changed this block will be called
Ty
GCGamepadValueChangedHandler
Set this block if you want to be notified when a value on a element changed. If multiple elements have changed this block will be called
Ty
GCKeyboardValueChangedHandler
Set this block if you want to be notified when a value of a key changed. If multiple keys have changed this block will be called
Ty
GCMicroGamepadValueChangedHandler
Set this block if you want to be notified when a value on a element changed. If multiple elements have changed this block will be called
Ty
GCMotionValueChangedHandler
Called whenever a motion value changed.
Ty
GCMouseMoved
Set this block if you want to be notified when the mouse was moved
Ty
GCDeviceElement
Ty
GCDeviceButtonInput
Ty
GCDeviceAxisInput
Ty
GCDeviceDirectionPad
Ty
GCDeviceTouchpad

Extends 6

← Games & 3D