PyObjC GameController Framework

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9. PyObjC 11.0 dropped support for Python 3.8. Ensure your Python version meets the `requires_python` specification.
  Fix: Upgrade to Python 3.10+ for PyObjC 12.x, or use an older PyObjC version (e.g., PyObjC 10.x for Python 3.9).
• breaking PyObjC 11.1 changed how initializer methods (e.g., `init` family) handle references to align with Automatic Reference Counting (ARC) behavior. These methods now correctly model stealing a reference to `self` and returning a new one. Code relying on the previous, less accurate reference counting behavior for initializers might experience issues.
  Fix: Review code that interacts with Objective-C `init` methods, especially custom Python subclasses, to ensure correct reference handling under ARC rules.
• gotcha PyObjC and its framework wrappers are built exclusively for macOS. This library will not function on Linux, Windows, or other operating systems.
  Fix: Ensure your development and deployment environment is macOS.
• gotcha PyObjC 10.3 temporarily removed support for calling `__init__` when a class or its superclasses provided a custom `__new__` method. While partially reverted in 10.3.1, users with custom `__new__` implementations should test carefully and adapt `__init__` logic if needed.
  Fix: If using a custom `__new__`, carefully verify `__init__` behavior and potentially adjust how objects are initialized or ensure `__new__` is handled consistently with PyObjC's expectations. Consider upgrading to a later version if possible.
• gotcha PyObjC 11.0 introduced experimental support for Python 3.13's free-threading (PEP 703). While this is a significant enhancement, it is noted as experimental and may have limitations or require careful usage in multithreaded scenarios.
  Fix: When utilizing Python 3.13's free-threading with PyObjC, consult the PyObjC documentation for any specific guidelines or known issues related to threading and Objective-C interactions.

Install

• pip install pyobjc-framework-gamecontroller Install `GameController` framework bindings

Imports

• GCController

  from GameController import GCController

  Symbols from Objective-C frameworks are typically imported directly from a module named after the framework.

Quickstart

This quickstart demonstrates how to list currently connected game controllers using the `GameController` framework. It iterates through available controllers and prints basic information about them.

import objc
from GameController import GCController

def list_game_controllers():
    controllers = GCController.controllers()
    if controllers:
        print(f"Found {len(controllers)} game controllers:")
        for controller in controllers:
            vendor_name = controller.vendorName() or 'Unknown Vendor'
            print(f"  - {vendor_name} {controller.productCategory()} (Type: {controller.controllerType()})")
            if controller.extendedGamepad():
                print("    Extended Gamepad available.")
            elif controller.microGamepad():
                print("    Micro Gamepad available.")
    else:
        print("No game controllers found.")

if __name__ == "__main__":
    list_game_controllers()
    # In a persistent application, you would typically register for
    # GCControllerDidConnectNotification and GCControllerDidDisconnectNotification
    # to dynamically track controller connections/disconnections.