Establish scene size, scale mode, coordinate system, and ownership before adding gameplay nodes.
Keep gameplay state in the scene or a stable model; do not recreate the scene during SwiftUI updates.
Configure node names, z-order, actions, physics categories, and contact masks deliberately.
Separate camera/HUD coordinates from world coordinates and remove transient nodes predictably.
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

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.

spritekit

SpriteKit

Contents

Workflow