
spritekit
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.
- Installs
- 3.2K
- Last 24h
- +17
- Trending rank
- #6608
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/dpearson2699/swift-ios-skills --skill spritekit- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads spritekit automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 {
queuePlayerHit()
}
}
}
Contact callbacks run during physics simulation. Make queuePlayerHit() set a
flag or append an event, then apply node/body/world mutations in update(_:).
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, 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
FAQ
What does the spritekit skill do?
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.
How do I install spritekit?
Run npx skills add https://github.com/dpearson2699/swift-ios-skills --skill spritekit in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spritekit/ (personal) or .claude/skills/spritekit/ (project).
Which AI agents can use spritekit?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is spritekit safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains spritekit?
It is published by dpearson2699 in dpearson2699/swift-ios-skills. It has 3,195 recorded installs.
More from dpearson2699/swift-ios-skills
swiftui-animation
dpearson2699/swift-ios-skills
Implement, diagnose, or review SwiftUI motion using explicit and scoped implicit animations, springs, transitions, PhaseAnimator, KeyframeAnimator, matched geometry or navigation zoom, SF Symbol effects, and custom Animation types. Use when views should animate on state changes, insertion, removal, navigation, or multi-step choreography, or when motion must respect Reduce Motion and Swift concurrency.
ios-accessibility
dpearson2699/swift-ios-skills
Build and audit SwiftUI, UIKit, and AppKit accessibility for VoiceOver, Voice Control, Switch Control, Full Keyboard Access, Dynamic Type, focus restoration, labels/traits/actions, traversal, custom rotors, NSAccessibility, XCTest checks, adaptive system preferences, and App Store accessibility declarations. Use when implementing accessible UI, fixing an accessibility audit, testing assistive-technology behavior, or substantiating App Store Accessibility Nutrition Labels.
swiftui-performance
dpearson2699/swift-ios-skills
Profile, diagnose, and remediate SwiftUI runtime performance using code review, Instruments, and repeatable measurements. Use when a SwiftUI screen renders slowly, scrolling or animations hitch, view bodies update excessively, list identity churns, layout work spikes, or broad Observation dependencies raise CPU cost. Covers evidence-based triage, SwiftUI Instruments lanes, lazy-container guardrails, state lifetime, and before/after verification.
swiftui-patterns
dpearson2699/swift-ios-skills
Builds and reviews SwiftUI views with modern MV architecture, state, composition, isolated previews, and migration guidance. Covers @Observable ownership, @State/@Bindable/@Environment wiring, view decomposition, ViewModifiers, environment values, .task loading, iOS 26+ handoffs, Writing Tools, clipboard availability, and performance. Use when structuring SwiftUI state, managing @Observable, composing views, previewing meaningful UI states, or correcting SwiftUI patterns.
app-store-review
dpearson2699/swift-ios-skills
Audits App Store submission readiness and rejection risk across current review guidelines, PrivacyInfo.xcprivacy and required-reason APIs, privacy labels, ATT, StoreKit payments, metadata, entitlements, widgets, and Live Activities. Use when preparing a submission, responding to rejection, reconciling privacy evidence, or separating upload blockers from cleanup.
ios-networking
dpearson2699/swift-ios-skills
Build, review, or improve networking code in iOS/macOS apps using URLSession with async/await, structured concurrency, and modern Swift patterns. Use when working with REST APIs, downloading files, uploading data, WebSocket connections, pagination, retry logic, request middleware, caching, background transfers, or network reachability monitoring. Also use when handling HTTP requests, API clients, network error handling, or data fetching in Swift apps.
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.