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 = . resizeFill skView . 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: update(:) -- game logic Evaluate actions didEvaluateActions() -- post-action logic Simulate physics didSimulatePhysics() -- post-physics adjustments Apply constraints didApplyConstraints() 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 Class Purpose SKSpriteNode Textured image or solid color SKLabelNode Text rendering SKShapeNode Vector paths (expensive per draw call) SKEmitterNode Particle effects SKCameraNode Viewport control SKTileMapNode Grid-based tiles SKAudioNode Positional audio SKCropNode / SKEffectNode Masking / CIFilter SK3DNode Embedded SceneKit content 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 = - 1 player . zPosition = 0 foregroundUI . 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 another let dropAndRemove = SKAction . sequence ( [ SKAction . moveBy ( x : 0 , y : - 500 , duration : 1.0 ) , SKAction . removeFromParent ( ) ] ) // Parallel: run simultaneously let scaleAndFade = SKAction . group ( [ SKAction . scale ( to : 0.0 , duration : 0.3 ) , SKAction . fadeOut ( withDuration : 0.3 ) ] ) // Repeat let 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 body player . physicsBody = SKPhysicsBody ( circleOfRadius : player . size . width / 2 ) player . physicsBody ? . restitution = 0.3 // Static rectangle ground . physicsBody = SKPhysicsBody ( rectangleOf : ground . size ) ground . physicsBody ? . isDynamic = false // Texture-based body for irregular shapes player . 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 . player player . physicsBody ? . contactTestBitMask = PhysicsCategory . enemy player . 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 { handlePlayerHit ( contact ) } } } Forces and Impulses player . physicsBody ? . applyForce ( CGVector ( dx : 0 , dy : 50 ) ) // continuous player . physicsBody ? . applyImpulse ( CGVector ( dx : 0 , dy : 200 ) ) // instant player . 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 = cameraNode cameraNode . 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 bounds let 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 = 24 cameraNode . addChild ( scoreLabel ) Particle Effects SKEmitterNode generates particle effects. Design emitters in Xcode's SpriteKit Particle File editor ( .sks ) or configure in code. // Load from file guard 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 SwiftUI import 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 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 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