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

• Workflow
• Route by Task
• Core Decisions
• Common Mistakes
• Review Checklist
• References

Workflow

1. Establish scene size, scale mode, coordinate system, and ownership before adding gameplay nodes.
2. Keep gameplay state in the scene or a stable model; do not recreate the scene during SwiftUI updates.
3. Configure node names, z-order, actions, physics categories, and contact masks deliberately.
4. Separate camera/HUD coordinates from world coordinates and remove transient nodes predictably.
5. Verify frame-rate behavior, contact delivery, pause/resume, resizing, and scene teardown.

Route by Task

• Read core implementation details for scene setup, sprites, actions, physics, touch handling, camera, particles, and SwiftUI integration.
• Read extended SpriteKit patterns for tile maps, atlases, shaders, advanced camera work, audio, and performance recipes.

Core Decisions

• Choose the scene coordinate and scaling contract before positioning content.
• Use category and contact masks as a reviewed collision matrix.
• Keep SKScene identity stable when hosted by SpriteView.
• Prefer textures and atlases over expensive shape-node rendering in repeated content.

Common Mistakes

Creating a new scene on every SwiftUI re-render

// DON'T: Scene is recreated on every body evaluation
var 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 called
player.physicsBody?.categoryBitMask = PhysicsCategory.player
enemy.physicsBody?.categoryBitMask = PhysicsCategory.enemy

// DO: Set contactTestBitMask to receive contact callbacks
player.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'T
enemy.run(SKAction.moveBy(x: -800, y: 0, duration: 3.0))
addChild(enemy)

// DO: Remove after leaving the visible area
enemy.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 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
• Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.