Build 2D games and animations using SpriteKit. Use when creating game scenes with SKScene and SKView, adding sprites with SKSpriteNode, animating with SKAction sequences, simulating physics with SKPhysicsBody and contact detection, creating particle effects with SKEmitterNode, building tile maps, using SKCameraNode, or integrating SpriteKit scenes in SwiftUI with SpriteView.
SKILL.md
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.
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.
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:
Contact callbacks run during physics simulation. Make queuePlayerHit() set a
flag or append an event, then apply node/body/world mutations in update(_:).
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):
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
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.
