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.

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.