{"id":6112,"library":"pyobjc-framework-gameplaykit","title":"PyObjC GameplayKit","description":"PyObjC-framework-gameplaykit provides Python bindings for Apple's GameplayKit framework on macOS. It enables Python applications to leverage game development utilities, including random number generation, pathfinding, AI behaviors, and more, directly from Python. The current version is 12.1, with releases generally aligning with macOS SDK updates.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","framework","game","objective-c","cocoa","apple"],"install":[{"cmd":"pip install pyobjc-framework-gameplaykit","lang":"bash","label":"Install pyobjc-framework-gameplaykit"}],"dependencies":[{"reason":"Core bridge between Python and Objective-C frameworks.","package":"pyobjc-core","optional":false}],"imports":[{"symbol":"GameplayKit","correct":"import GameplayKit"},{"symbol":"GKRandomSource","correct":"from GameplayKit import GKRandomSource"}],"quickstart":{"code":"import GameplayKit\nimport objc # For general PyObjC operations, though not explicitly used here beyond object instantiation\n\n# Initialize a basic random number generator from GameplayKit\n# The alloc().init() pattern is common for Objective-C object creation\nrandom_source = GameplayKit.GKARC4RandomSource.alloc().init()\n\n# Generate a random integer within a bound (0 to 99)\nrandom_int = random_source.nextIntWithUpperBound_(100)\nprint(f\"Generated random number (0-99): {random_int}\")\n\n# Example using a different random distribution\nshuffled_array = random_source.arrayByShufflingObjectsInArray_([\"apple\", \"banana\", \"cherry\", \"date\"])\nprint(f\"Shuffled array: {shuffled_array}\")","lang":"python","description":"This quickstart demonstrates how to import and use a basic GameplayKit feature, `GKARC4RandomSource`, to generate random numbers and shuffle arrays. It highlights the `alloc().init()` pattern for Objective-C object instantiation via PyObjC."},"warnings":[{"fix":"Upgrade to Python 3.10 or newer, or pin pyobjc-framework-gameplaykit to an older version compatible with your Python environment.","message":"PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8. Users upgrading should ensure their Python environment meets the new minimum requirement (currently Python 3.10+).","severity":"breaking","affected_versions":">=11.0, >=12.0"},{"fix":"Review code that directly calls `alloc().init()` or other `init` family methods, especially if custom memory management or unusual object lifecycles are involved. Most high-level usage should be unaffected.","message":"PyObjC 11.1 changed how initializer methods (like `init`) handle reference counting, aligning with `clang`'s ARC documentation. Methods in the 'init' family now correctly steal a reference to `self` and return a new one. This could subtly affect memory management or object lifecycle in applications directly interacting with low-level Objective-C object creation.","severity":"gotcha","affected_versions":">=11.1"},{"fix":"Avoid using PyObjC with Python 3.13's experimental free-threading features until explicitly announced as stable. If free-threading is critical, consider using PyObjC 12.x or later with a Python version where free-threading is stable, or use traditional threading models.","message":"Experimental free-threading support (PEP 703) in Python 3.13 is *not fully stable or supported* in PyObjC 11. While changes were made to enable it, relying on it for production or performance-critical applications is not recommended.","severity":"gotcha","affected_versions":">=11.0, <12.0 (for Python 3.13)"},{"fix":"If experiencing issues with `__init__` not being called, ensure your class or its superclasses provide a custom `__new__` if you intend to use `__init__`. Otherwise, adapt your object initialization to Objective-C patterns (e.g., using factory methods or designated initializers).","message":"In PyObjC 10.3, direct calls to `__init__` were restricted when a class used PyObjC's `__new__` implementation. Version 10.3.1 reintroduced the ability to use `__init__` if the user provided their own `__new__` or a superclass did. Code relying on PyObjC's default `__new__` still cannot use `__init__`.","severity":"gotcha","affected_versions":"10.3.x"},{"fix":"If you need to work with `NSURL` objects that might not represent local filesystem paths, avoid `os.fspath()`. Use `NSURL`'s methods (e.g., `absoluteString()`, `path()`) or convert to a Python string explicitly, verifying it's a local path first if needed.","message":"The `os.fspath()` function in Python will raise a `TypeError` when used with Cocoa URLs (`NSURL`, `CFURLRef`) that do not refer to local filesystem paths (e.g., web URLs). This change in behavior ensures `os.fspath()` correctly reflects only local filesystem paths.","severity":"gotcha","affected_versions":">=10.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}