Spritekit

SpriteKit

Build 2D games and interactive animations for iOS 26+ using SpriteKit and Swift 6.3. Covers scene lifecycle, node hierarchy, actions, physics, particles, camera, touch handling, and SwiftUI integration.

Contents

• Scene Setup
• Nodes and Sprites
• Actions and Animation
• Physics
• Touch Handling
• Camera
• Particle Effects
• SwiftUI Integration
• Common Mistakes
• Review Checklist
• References

Scene Setup

SpriteKit renders content through SKView, which presents an SKScene -- the root node of a tree that the framework animates and renders each frame.

Creating a Scene

Subclass SKScene and override lifecycle methods. The coordinate system origin is at the bottom-left by default.

import SpriteKit
final class GameScene: SKScene {    override func didMove(to view: SKView) {        backgroundColor = .darkGray        physicsWorld.contactDelegate = self        physicsBody = SKPhysicsBody(edgeLoopFrom: frame)        setupNodes()    }
    override func update(_ currentTime: TimeInterval) {        // Called once per frame before actions are evaluated.    }}

Presenting a Scene (UIKit)

guard let skView = view as? SKView else { return }skView.ignoresSiblingOrder = true
let scene = GameScene(size: skView.bounds.size)scene.scaleMode = .resizeFillskView.presentScene(scene)

Scale Modes

Use .resizeFill when the scene should adapt to view size changes (rotation, multitasking). Use .aspectFill for fixed-design game scenes. .aspectFit letterboxes; .fill stretches and may distort.

Frame Cycle

Each frame follows this order:

1. update(_:) -- game logic
2. Evaluate actions
3. didEvaluateActions() -- post-action logic
4. Simulate physics
5. didSimulatePhysics() -- post-physics adjustments
6. Apply constraints
7. didApplyConstraints()
8. didFinishUpdate() -- final adjustments before rendering

Override only the callbacks where work is needed.

Nodes and Sprites

Use SKNode (without a visual) as an invisible container or layout group. Child nodes inherit parent position, scale, rotation, alpha, and speed. SKSpriteNode is the primary visual node.

Common Node Types

Creating Sprites

let player = SKSpriteNode(imageNamed: "hero")player.position = CGPoint(x: frame.midX, y: frame.midY)player.name = "player"addChild(player)

Drawing Order

Set ignoresSiblingOrder = true on SKView for better performance; SpriteKit then uses zPosition to determine order. Without it, nodes draw in tree order.

background.zPosition = -1player.zPosition = 0foregroundUI.zPosition = 10

Naming and Searching

Assign name to find nodes without instance variables. Use childNode(withName:), enumerateChildNodes(withName:using:), or subscript. Patterns: // searches the entire tree, * matches any characters, .. refers to the parent.

player.name = "player"if let found = childNode(withName: "player") as? SKSpriteNode { /* ... */ }

Actions and Animation

SKAction objects define changes applied to nodes over time. Actions are immutable and reusable. Run with node.run(_:).

Basic Actions

let moveUp = SKAction.moveBy(x: 0, y: 100, duration: 0.5)let grow = SKAction.scale(to: 1.5, duration: 0.3)let spin = SKAction.rotate(byAngle: .pi * 2, duration: 1.0)let fadeOut = SKAction.fadeOut(withDuration: 0.3)let remove = SKAction.removeFromParent()

Combining Actions

// Sequential: run one after anotherlet dropAndRemove = SKAction.sequence([    SKAction.moveBy(x: 0, y: -500, duration: 1.0),    SKAction.removeFromParent()])
// Parallel: run simultaneouslylet scaleAndFade = SKAction.group([    SKAction.scale(to: 0.0, duration: 0.3),    SKAction.fadeOut(withDuration: 0.3)])
// Repeatlet pulse = SKAction.repeatForever(    SKAction.sequence([        SKAction.scale(to: 1.2, duration: 0.5),        SKAction.scale(to: 1.0, duration: 0.5)    ]))

Texture Animation

let walkFrames = (1...8).map { SKTexture(imageNamed: "walk_\($0)") }let walkAction = SKAction.animate(with: walkFrames, timePerFrame: 0.1)player.run(SKAction.repeatForever(walkAction))

Control the speed curve with timingMode (.linear, .easeIn, .easeOut, .easeInEaseOut). Assign keys to actions for later access:

let easeIn = SKAction.moveTo(x: 300, duration: 1.0)easeIn.timingMode = .easeInEaseOut
player.run(pulse, withKey: "pulse")player.removeAction(forKey: "pulse") // stop later

Physics

SpriteKit provides a built-in 2D physics engine. The scene's physicsWorld manages gravity and collision detection.

Adding Physics Bodies

// Circle bodyplayer.physicsBody = SKPhysicsBody(circleOfRadius: player.size.width / 2)player.physicsBody?.restitution = 0.3
// Static rectangleground.physicsBody = SKPhysicsBody(rectangleOf: ground.size)ground.physicsBody?.isDynamic = false
// Texture-based body for irregular shapesplayer.physicsBody = SKPhysicsBody(texture: player.texture!, size: player.size)

Category and Contact Masks

Use bit masks to control collisions and contact callbacks:

struct PhysicsCategory {    static let player:  UInt32 = 0b0001    static let enemy:   UInt32 = 0b0010    static let ground:  UInt32 = 0b0100}
player.physicsBody?.categoryBitMask = PhysicsCategory.playerplayer.physicsBody?.contactTestBitMask = PhysicsCategory.enemyplayer.physicsBody?.collisionBitMask = PhysicsCategory.ground

categoryBitMask identifies the body. collisionBitMask controls physics response (bouncing). contactTestBitMask triggers didBegin/didEnd.

Contact Detection

Implement SKPhysicsContactDelegate and set physicsWorld.contactDelegate = self in didMove(to:):

extension GameScene: SKPhysicsContactDelegate {    func didBegin(_ contact: SKPhysicsContact) {        let mask = contact.bodyA.categoryBitMask | contact.bodyB.categoryBitMask        if mask == PhysicsCategory.player | PhysicsCategory.enemy {            queuePlayerHit()        }    }}

Contact callbacks run during physics simulation. Make queuePlayerHit() set a flag or append an event, then apply node/body/world mutations in update(_:).

Forces and Impulses

player.physicsBody?.applyForce(CGVector(dx: 0, dy: 50))      // continuousplayer.physicsBody?.applyImpulse(CGVector(dx: 0, dy: 200))   // instantplayer.physicsBody?.applyAngularImpulse(0.5)                  // spin

Use .applyImpulse for jumps and projectile launches. Configure gravity with physicsWorld.gravity = CGVector(dx: 0, dy: -9.8) and per-body with affectedByGravity.

Touch Handling

SKScene inherits from UIResponder. Override touchesBegan, touchesMoved, touchesEnded on the scene. Use nodes(at:) to hit-test.

override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {    guard let touch = touches.first else { return }    let location = touch.location(in: self)    let tappedNodes = nodes(at: location)
    if tappedNodes.contains(where: { $0.name == "playButton" }) {        startGame()    }}

For node-level touch handling, subclass the node and set isUserInteractionEnabled = true. That node then receives touches directly instead of the scene.

Camera

SKCameraNode controls the visible portion of the scene. Add it as a child and assign to scene.camera.

let cameraNode = SKCameraNode()addChild(cameraNode)camera = cameraNodecameraNode.position = CGPoint(x: frame.midX, y: frame.midY)

Following a Character

Update the camera position in didSimulatePhysics() or use constraints:

override func didSimulatePhysics() {    cameraNode.position = player.position}
// Constrain camera to world boundslet xRange = SKRange(lowerLimit: frame.midX, upperLimit: worldWidth - frame.midX)let yRange = SKRange(lowerLimit: frame.midY, upperLimit: worldHeight - frame.midY)cameraNode.constraints = [SKConstraint.positionX(xRange, y: yRange)]

Camera Zoom and HUD

Scale the camera node inversely: setScale(0.5) zooms in 2x, setScale(2.0) zooms out 2x. Nodes added as children of the camera stay fixed on screen (HUD elements):

let scoreLabel = SKLabelNode(text: "Score: 0")scoreLabel.position = CGPoint(x: 0, y: frame.height / 2 - 40)scoreLabel.fontName = "AvenirNext-Bold"scoreLabel.fontSize = 24cameraNode.addChild(scoreLabel)

Particle Effects

SKEmitterNode generates particle effects. Design emitters in Xcode's SpriteKit Particle File editor (.sks) or configure in code.

// Load from fileguard let emitter = SKEmitterNode(fileNamed: "Fire") else { return }emitter.position = CGPoint(x: frame.midX, y: 100)addChild(emitter)

One-Shot Emitters

Set numParticlesToEmit for finite effects and remove after completion:

func spawnExplosion(at position: CGPoint) {    guard let explosion = SKEmitterNode(fileNamed: "Explosion") else { return }    explosion.position = position    explosion.numParticlesToEmit = 100    addChild(explosion)
    let wait = SKAction.wait(forDuration: TimeInterval(explosion.particleLifetime))    explosion.run(SKAction.sequence([wait, .removeFromParent()]))}

Set targetNode to the scene so particles stay in world space when the emitter moves: emitter.targetNode = self.

SwiftUI Integration

SpriteView embeds a SpriteKit scene in SwiftUI.

import SwiftUIimport SpriteKit
struct GameView: View {    @State private var scene: GameScene = {        let s = GameScene()        s.size = CGSize(width: 390, height: 844)        s.scaleMode = .resizeFill        return s    }()
    var body: some View {        SpriteView(scene: scene)            .ignoresSafeArea()    }}

SpriteView Options

Pass options: [.allowsTransparency] for transparent backgrounds, .shouldCullNonVisibleNodes for offscreen culling, or .ignoresSiblingOrder for zPosition-based draw order. Use debugOptions: [.showsFPS, .showsNodeCount] during development.

Communicating Between SwiftUI and the Scene

Pass data through a shared @Observable object. Store the scene in @State to avoid re-creation on view re-renders:

@Observable final class GameState {    var score = 0    var isPaused = false}
struct GameContainerView: View {    @State private var gameState = GameState()    @State private var scene = GameScene()
    var body: some View {        SpriteView(scene: scene, isPaused: gameState.isPaused)            .onAppear { scene.gameState = gameState }    }}

Common Mistakes

Creating a new scene on every SwiftUI re-render

// DON'T: Scene is recreated on every body evaluationvar body: some View {    SpriteView(scene: GameScene(size: CGSize(width: 390, height: 844)))}
// DO: Create once and reuse@State private var scene = GameScene(size: CGSize(width: 390, height: 844))var body: some View {    SpriteView(scene: scene)}

Adding a child node that already has a parent

A node can only have one parent. Remove from the current parent first or create a separate instance. Adding a node that already has a parent crashes.

Forgetting to set contactTestBitMask

// DON'T: Bodies collide but didBegin is never calledplayer.physicsBody?.categoryBitMask = PhysicsCategory.playerenemy.physicsBody?.categoryBitMask = PhysicsCategory.enemy
// DO: Set contactTestBitMask to receive contact callbacksplayer.physicsBody?.contactTestBitMask = PhysicsCategory.enemy

Using SKShapeNode for performance-critical rendering

SKShapeNode uses a separate draw call per instance. Prefer SKSpriteNode with a texture for repeated elements to enable batched rendering.

Not removing nodes that leave the screen

// DON'Tenemy.run(SKAction.moveBy(x: -800, y: 0, duration: 3.0))addChild(enemy)
// DO: Remove after leaving the visible areaenemy.run(SKAction.sequence([    SKAction.moveBy(x: -800, y: 0, duration: 3.0),    SKAction.removeFromParent()]))addChild(enemy)

Setting physicsWorld.contactDelegate too late

Set physicsWorld.contactDelegate = self in didMove(to:), not in update(_:) or after a delay.

Review Checklist

• Scene subclass overrides didMove(to:) for setup, not init
• scaleMode chosen appropriately for the game's design
• ignoresSiblingOrder set to true on SKView for performance
• zPosition used consistently when ignoresSiblingOrder is enabled
• Physics contactDelegate set in didMove(to:)
• Category, collision, and contact bit masks configured correctly
• contactTestBitMask set for any pair needing didBegin/didEnd callbacks
• Contact callbacks queue changes instead of mutating the physics world directly
• Static bodies use isDynamic = false
• SKShapeNode avoided in performance-critical paths; SKSpriteNode preferred
• Actions that move nodes offscreen include .removeFromParent() in sequence
• One-shot emitters remove themselves after particle lifetime expires
• Emitter targetNode set when particles should stay in world space
• Scene stored in @State when used with SpriteView in SwiftUI
• Texture atlases used for related sprites to reduce draw calls
• update(_:) uses delta time for frame-rate-independent movement
• Nodes removed from parent before being re-added elsewhere

References

• See references/spritekit-patterns.md [blocked] for tile maps, texture atlases, shaders, scene transitions, game loop patterns, audio, and SceneKit embedding.
• SpriteKit documentation
• SKScene
• SKSpriteNode
• SKAction
• SKPhysicsBody
• SKEmitterNode
• SKCameraNode
• SpriteView
• SKTileMapNode