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
- 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
SKSceneidentity stable when hosted bySpriteView. - 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, notinit -
scaleModechosen appropriately for the game's design -
ignoresSiblingOrderset totrueonSKViewfor performance -
zPositionused consistently whenignoresSiblingOrderis enabled - Physics
contactDelegateset indidMove(to:) - Category, collision, and contact bit masks configured correctly
-
contactTestBitMaskset for any pair needingdidBegin/didEndcallbacks - Contact callbacks queue changes instead of mutating the physics world directly
- Static bodies use
isDynamic = false -
SKShapeNodeavoided in performance-critical paths;SKSpriteNodepreferred - Actions that move nodes offscreen include
.removeFromParent()in sequence - One-shot emitters remove themselves after particle lifetime expires
- Emitter
targetNodeset when particles should stay in world space - Scene stored in
@Statewhen used withSpriteViewin 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.