PyObjC SpriteKit Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions to align with active Python maintenance. PyObjC 12.0 dropped Python 3.9, and PyObjC 11.0 dropped Python 3.8. Always check the `requires_python` metadata or release notes to ensure compatibility with your Python environment.
  Fix: Ensure your Python environment meets the `requires_python` specification (e.g., `>=3.10` for PyObjC 12.1) before upgrading PyObjC. Use a virtual environment to manage Python versions.
• breaking PyObjC 11.1 aligned its core bridge with `clang`'s Automatic Reference Counting (ARC) documentation for initializer methods. Methods in the 'init' family now correctly steal a reference to `self` and return a new reference. This changed behavior for `[NSObject alloc]` proxies and can affect custom `init` implementations in Python subclasses, potentially leading to crashes if old reference counting patterns are assumed.
  Fix: Review custom `init` implementations in Python subclasses of Objective-C objects. PyObjC 10.3 introduced a Pythonic `Class(...)` instantiation pattern that is generally safer. Consult PyObjC's documentation on reference counting and object instantiation.
• gotcha PyObjC 10.3 initially broke `__init__` usage for Python subclasses of Objective-C classes, particularly when a user implemented `__new__` or when relying on PyObjC's `__new__` behavior. This was partially reverted in 10.3.1 to reintroduce `__init__` support when a user explicitly implements `__new__`. Code relying on PyObjC's provided `__new__` still cannot use `__init__` as before.
  Fix: When subclassing Objective-C classes, implement Objective-C style `init` methods (e.g., `initWithFoo_:`). If overriding `__new__` in a Python subclass, be aware of the interaction with `__init__` and refer to PyObjC documentation on object instantiation.
• gotcha PyObjC 11.0 introduced experimental support for free-threading (PEP 703) with Python 3.13+. While PyObjC protects its own implementation, Apple's Cocoa and SpriteKit frameworks are not inherently thread-safe. Concurrent updates to GUI elements or non-atomic properties from multiple Python threads can lead to undefined behavior or crashes.
  Fix: When using PyObjC in a free-threaded Python environment, ensure all interactions with Apple's frameworks, especially GUI and mutable data structures, occur on the main thread. Use `performSelectorOnMainThread` or similar mechanisms for thread-safe access.
• gotcha PyObjC provides bindings to macOS frameworks, but it does not provide explicit documentation for every Objective-C API. Developers must refer to Apple's official SpriteKit and Cocoa documentation for detailed API usage, paying attention to how PyObjC translates Objective-C conventions (e.g., `someMethod:withArg:` becomes `someMethod_withArg_` in Python).
  Fix: Consult Apple's developer documentation for SpriteKit and related frameworks. Refer to the PyObjC documentation for general guidance on the Python-Objective-C bridge and translation rules.

Install

• pip install pyobjc-framework-spritekit Install PyObjC SpriteKit

Imports

• SpriteKit

  import SpriteKit

  All SpriteKit classes and functions are available under the `SpriteKit` namespace.
• AppKit

  import AppKit

  Required for basic macOS application structure (windows, views, application delegate).
• AppHelper

  from PyObjCTools import AppHelper

  Utility to run the Cocoa application event loop.

Quickstart

This quickstart demonstrates how to create a basic macOS application using PyObjC, display an `SKView` within an `NSWindow`, and present a simple `SpriteKit.SKScene` with a 'Hello, PyObjC SpriteKit!' label. It requires a running macOS environment. The `PyObjCTools.AppHelper` is used to manage the Cocoa event loop.

import AppKit
import SpriteKit
from PyObjCTools import AppHelper

# Define a simple SpriteKit scene
class MyScene(SpriteKit.SKScene):
    def didMoveToView_(self, view):
        if not self.contentCreated:
            self.createSceneContents()
            self.contentCreated = True

    def createSceneContents(self):
        self.backgroundColor = SpriteKit.SKColor.redColor()
        self.scaleMode = SpriteKit.SKSceneScaleMode.aspectFit

        helloNode = SpriteKit.SKLabelNode.labelNodeWithFontNamed_('Chalkduster')
        helloNode.text = 'Hello, PyObjC SpriteKit!'
        helloNode.fontSize = 24
        helloNode.position = AppKit.CGPointMake(self.frame().size.width / 2, self.frame().size.height / 2)
        self.addChild_(helloNode)

# Define an Application Delegate to set up the window and scene
class AppDelegate(AppKit.NSObject):
    def applicationDidFinishLaunching_(self, notification):
        rect = AppKit.NSMakeRect(0, 0, 800, 600)
        self.window = AppKit.NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
            rect, 
            AppKit.NSWindowStyleMaskTitled | AppKit.NSWindowStyleMaskClosable | AppKit.NSWindowStyleMaskMiniaturizable | AppKit.NSWindowStyleMaskResizable,
            AppKit.NSBackingStoreBuffered,
            False
        )
        self.window.center()
        self.window.setTitle_('PyObjC SpriteKit Example')

        # Create an SKView and set it as the window's content view
        skView = SpriteKit.SKView.alloc().initWithFrame_(rect)
        self.window.setContentView_(skView)

        # Create and present the scene
        scene = MyScene.sceneWithSize_(skView.bounds().size)
        skView.presentScene_(scene)
        skView.setShowsFPS_(True)
        skView.setShowsNodeCount_(True)

        self.window.makeKeyAndOrderFront_(None)

    def applicationShouldTerminateAfterLastWindowClosed_(self, sender):
        return True

# Start the Cocoa application
if __name__ == '__main__':
    app = AppKit.NSApplication.sharedApplication()
    delegate = AppDelegate.alloc().init()
    app.setDelegate_(delegate)
    AppHelper.runEventLoop()