CommunityCodierung & Entwicklunggithub.com

SpriteKit

Programmier-Kit für 2D iOS Spiele mit SpriteKit in SwiftUI (iOS 26+, Swift 6) – Szenen, Frameschleife, Aktionen, Physik, Kameras, Kachelkarten, Partikel, Shader, Beleuchtung und Draw-Call-Performance. Verwenden Sie es zum Schreiben oder Debuggen von SpriteKit-Code (SKScene, SKNode, SpriteView) oder wenn ein 2D-Spiel langsam rendert oder falsch aussieht.

Was ist SpriteKit?

Dieses Skill bietet Entwicklern eine vollständige Anleitung zur Erstellung von 2D-Spielen mit SpriteKit, gehostet in SwiftUI, für iOS 26 und Swift 6. Es behandelt die Grundlagen wie Szenen-Setup, Frameschleife, Aktionen, Physik, Kameras, Kachelkarten, Partikel, Shader und Beleuchtung. Der Fokus liegt auf der Optimierung der Zeichenleistung durch Minimierung von Draw-Calls und effizientem Ressourcenmanagement. Das Skill enthält spezifische Anleitungen zur Swift 6-Konkurrenzsicherheit, zur Vermeidung veralteter APIs wie SK3DNode und zur Performance-Profilerstellung auf dem Gerät. Es unterstützt die Integration in SwiftUI über die SpriteView-Komponente und bietet praktische Codebeispiele sowie Hinweise zu häufigen Fallstricken.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andersmoldin/ios-game-creator-skills/tree/HEAD/skills/spritekit

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht SpriteKit?

SpriteKit ist der Standard-Renderer für 2D-iOS-Spiele. Er wird unterstützt und ist nicht veraltet, aber die API ist seit iOS 12 eingefroren, sodass jeder SpriteKit-Aufruf unter iOS 26 ohne #available-Prüfungen funktioniert. Projektweite Einstellungen (Game Mode, ProMotion, App-Kategorie) befinden sich im Skill ios-game-design.

Vermeiden Sie SK3DNode: Es bindet SceneKit ein, das seit iOS 26 veraltet ist. Verwenden Sie das Skill realitykit für 3D.

Szene in SwiftUI hosten

import SwiftUI
import SpriteKit

struct GameView: View {
    @State private var scene: GameScene = {          // einmal erstellen; niemals innerhalb von 'body'
        let s = GameScene(size: CGSize(width: 390, height: 844))
        s.scaleMode = .resizeFill
        s.anchorPoint = CGPoint(x: 0.5, y: 0.5)
        return s
    }()
    @State private var paused = false

    var body: some View {
        SpriteView(scene: scene, isPaused: paused, preferredFramesPerSecond: 120,
                   options: [.ignoresSiblingOrder, .shouldCullNonVisibleNodes],
                   debugOptions: [.showsFPS, .showsNodeCount, .showsDrawCount]) // nur Debug-Builds
            .ignoresSafeArea()
            .statusBarHidden()
            .persistentSystemOverlays(.hidden)
    }
}

Die Standardeinstellungen von SpriteView sind für Spiele falsch; überschreiben Sie sie:

  • preferredFramesPerSecond standardmäßig 60. Übergeben Sie 120 und fügen Sie CADisableMinimumFrameDurationOnPhone zur Info.plist hinzu, sonst bleibt das iPhone bei 60 Hz.
  • options standardmäßig [.shouldCullNonVisibleNodes], daher ist .ignoresSiblingOrder ausgeschaltet. Schalten Sie es ein und setzen Sie zPosition, wo die Zeichenreihenfolge wichtig ist.

Skalierungsmodi: .aspectFit letterboxt, .aspectFill beschneidet, .resizeFill folgt der Ansichtsgröße (erneutes Layout in didChangeSize(_:)). Wählen Sie eine feste Designgröße mit einem Seitenverhältnismodus oder .resizeFill mit adaptivem Layout. Halten Sie die Welt randlos und blenden Sie nur HUD und Touch-Ziele durch view.safeAreaInsets ein, oder zeichnen Sie das HUD als SwiftUI-Overlay.

Swift 6 Konkurrenz

  • SKNode (und damit SKScene) ist @MainActor, vererbt von UIResponder. Closures, die in einer Szene erstellt werden (SKAction.run, customAction), übernehmen den Haupt-Actor.
  • SKPhysicsContactDelegate ist nicht isoliert, daher schlägt ohne Standard-Main-Actor-Isolation class GameScene: SKScene, SKPhysicsContactDelegate in Swift 6 fehl. Schreiben Sie eine isolierte Konformität, die unter jeder Einstellung kompiliert: SKScene, @MainActor SKPhysicsContactDelegate.
  • Vorladen mit den asynchronen Formen (await atlas.preload(), await SKTexture.preload(textures)); die Completion-Handler-Formen sind @Sendable und warnen, wenn sie Nodes berühren.
  • await node.run(action) wird fortgesetzt, wenn die Aktion endet, geeignet für kurze Sequenzen. Es wird nie für repeatForever fortgesetzt.
  • Neue Xcode-Projekte verwenden standardmäßig den Swift 5 Sprachmodus; setzen Sie SWIFT_VERSION = 6 explizit.

Frameschleife

Reihenfolge pro Frame: update(_:) → Aktionen → didEvaluateActions() → Physik (Kontakt-Callbacks werden hier ausgelöst) → didSimulatePhysics() → Constraints → didApplyConstraints() → didFinishUpdate() → rendern.

  • currentTime ist absolut. Berechnen Sie dt selbst und begrenzen Sie es (z.B. auf 1/30 s), damit eine Pause oder ein Aussetzer niemals Objekte teleportiert.
  • Die Bildrate variiert mit dem Energiesparmodus und dem thermischen Zustand. Skalieren Sie alle Bewegungen mit dt.
  • Fügen Sie Physik-Körper niemals innerhalb von didBegin/didEnd hinzu, entfernen Sie sie oder ändern Sie ihre Form. Warteschlangen Sie die Änderung und wenden Sie sie in didSimulatePhysics() oder der nächsten update-Methode an.
  • Die Reihenfolge der Aktionen innerhalb eines Frames ist nicht spezifiziert. Lesen Sie endgültige Positionen in didEvaluateActions() oder später aus.

Szenen-Skelett

enum Category { static let player: UInt32 = 1 << 0; static let enemy: UInt32 = 1 << 1; static let wall: UInt32 = 1 << 2 }

final class GameScene: SKScene, @MainActor SKPhysicsContactDelegate {
    private var lastTime: TimeInterval = 0
    private let cam = SKCameraNode()
    private let player = SKSpriteNode(imageNamed: "player")
    private var pendingRemovals: [SKNode] = []

    override func didMove(to view: SKView) {
        physicsWorld.contactDelegate = self          // wird unowned gehalten: Die Szene muss am Leben bleiben
        addChild(cam); camera = cam                  // Kinder von cam bilden ein bildschirmfestes HUD
        let body = SKPhysicsBody(circleOfRadius: 12)
        body.categoryBitMask = Category.player
        body.collisionBitMask = Category.wall
        body.contactTestBitMask = Category.enemy     // Standard 0: keine didBegin-Aufrufe
        player.physicsBody = body
        addChild(player)
    }

    override func update(_ currentTime: TimeInterval) {
        let dt = lastTime == 0 ? 0 : min(currentTime - lastTime, 1.0 / 30.0)
        lastTime = currentTime
        step(dt)
        cam.position = player.position
    }

    override func didSimulatePhysics() {             // sicherer Punkt, um Physik zu mutieren
        pendingRemovals.forEach { $0.removeFromParent() }
        pendingRemovals.removeAll()
    }

    func didBegin(_ contact: SKPhysicsContact) {     // nur aufzeichnen; niemals hier mutieren
        let a = contact.bodyA, b = contact.bodyB
        guard a.categoryBitMask | b.categoryBitMask == Category.player | Category.enemy,
              let enemy = (a.categoryBitMask == Category.enemy ? a : b).node else { return }
        pendingRemovals.append(enemy)
    }

    private func step(_ dt: TimeInterval) { /* Spiel-Logik, skaliert mit dt */ }
}

Bausteine

BedarfVerwendung
Kamera, HUDSKCameraNode; HUD-Nodes als Kamera-Kinder
Tweens, EasingSKAction mit timingMode oder einer benutzerdefinierten timingFunction
Sprite-AnimationSKAction.animate(with:timePerFrame:) über Atlas-Texturen
PhysikSKPhysicsBody (Kreis/Rechteck am günstigsten), Masken explizit setzen, usesPreciseCollisionDetection für kleine schnelle Körper
Gitter-LevelsSKTileMapNode + SKTileSet; Kacheln sind keine Nodes, daher Kollision separat aufbauen
TexturenSprite-Atlas im Asset-Katalog, SKTextureAtlas(named:); vor dem Spiel laden
Pixel-Arttexture.filteringMode = .nearest auf jeder Textur, einschließlich jedes Atlas-Frames
Partikel.sks Emitter-Dateien, SKEmitterNode(fileNamed:); targetNode = scene für Spuren setzen
Shader, Lichter, Filter, WarpsLesen Sie references/effects.md
Einmaliger SoundSKAction.playSoundFileNamed; alles Weitere verwendet das Skill game-audio-engine
Metal-IntegrationSKRenderer zeichnet eine Szene innerhalb eines eigenen Metal-Passes

Performance

  • Batching: Nodes, die eine Textur oder einen Atlas teilen, zeichnen in einem Aufruf. Gemischte Atlanten und überlappende Nodes mit unterschiedlichen zPositions teilen Batches. Achten Sie auf showsDrawCount.
  • Entfernen Sie Nodes außerhalb des Bildschirms mit removeFromParent(); Culling besucht trotzdem jeden Node pro Frame.
  • Aufwändig, sparsam verwenden: SKEffectNode mit CIFilter, SKCropNode, viele SKShapeNodes, ein SKShader pro Sprite und Shader-Quellcode-Änderungen zur Laufzeit (jede Neukompilierung).
  • SKShapeNode dient dem Debug-Zeichnen. Backen Sie eine Form einmal mit view.texture(from:) und zeichnen Sie Sprites.
  • Profilen Sie auf einem Gerät mit der Instruments-Vorlage Game Performance und dem Metal Performance HUD (Scheme > Run > Diagnostics > Show Graphics Overview).

Fallstricke

  • contactTestBitMask standardmäßig 0, während categoryBitMask und collisionBitMask standardmäßig alle Bits sind. Setzen Sie alle drei für jeden Körper.
  • UIScreen.main ist in iOS 26 veraltet. Lesen Sie die Bildwiederholfrequenz von view.window?.windowScene?.screen.maximumFramesPerSecond.
  • SKShader-Quellcode ist GLSL ES, nicht die Metal Shading Language.
  • physicsWorld.contactDelegate wird nicht gehalten.
  • Mit .ignoresSiblingOrder zeichnen Nodes mit gleichem zPosition in beliebiger Reihenfolge.

Verwandte Skills

Eingabe und Haptik: game-controller. Sound: game-audio-engine. Look, Palette und Juice: game-art-direction. Gitter- und Raum-Layout: game-level-design.

Verwandte Skills