game-feel

name

game-feel

description

Make iOS apps and games FEEL responsive, satisfying, alive — haptics, particle/spring animation, sound feedback, screen shake, celebrations, and SpriteKit (iOS 26 / Swift 6). Use for: "game feel", "juice it up", "make it feel good / punchy", "add haptics", Core Haptics / CHHapticEngine / AHAP, sensoryFeedback, "add confetti", "celebrate achievement", "particle effect", "screen shake", "hit pause", "build a 2D game", SpriteKit / SKScene / SKAction / SpriteView, SwiftUI Metal shader effects (colorEffect / distortionEffect / layerEffect), ripple / shimmer, audio-reactive visualizer, error shake, GCController, Game Center / GameKit, "my app feels flat". HIG layout → apple-hig; general SwiftUI screens → swiftui-ui.

Game Feel

The difference between an app that works and an app that feels alive is game feel — the moment-to-moment tactile, visual, and audible response to every interaction. A button that bounces, taps that you can feel, a milestone that erupts in confetti, an enemy that flashes and the screen that kicks back when you hit it. This skill is the craft of "juice": adding feedback that makes interactions satisfying without making them slower or less accessible.

It covers three feedback channels that fire together — haptics (what you feel), animation/juice (what you see), audio (what you hear) — plus the SpriteKit 2D engine and reward systems (confetti, badges, celebrations) that package them into game-like experiences. It applies to any iOS app, not just games: a fitness app celebrating a streak, a finance app confirming a transfer, a to-do app checking off a task all benefit from deliberate feel.

---

Phase 0 — Context & capability check (do this FIRST)

Before generating any feel code, establish the ground truth:

1. Deployment target. sensoryFeedback, @Observable, .symbolEffect, spring presets need iOS 17+. MPNowPlayingSession, modern Photos picker need iOS 16+. SpriteKit + SpriteView work iOS 13+. State the floor you target.
2. Swift version. This skill targets Swift 6 strict concurrency / iOS 26. If the project is older, note which patterns degrade gracefully.
3. Platform & hardware. Haptics exist only on iPhone (Taptic Engine) — not iPad, not Mac, not Simulator. Always gate with CHHapticEngine.capabilitiesForHardware().supportsHaptics. macOS gets visual juice + audio but no haptics.
4. Accessibility is non-negotiable. Every animated celebration MUST honor Reduce Motion (@Environment(\.accessibilityReduceMotion) / UIAccessibility.isReduceMotionEnabled) with an equally rewarding non-animated fallback. Some users enable Reduce Motion for sensory reasons — also skip sounds in that path.
5. Existing code. Search before adding — don't duplicate a confetti view, haptic manager, or game scene that already exists:

   Glob: **/*Confetti*.swift, **/*Haptic*.swift, **/*Celebration*.swift, **/*Scene*.swift, **/*Emitter*.swift
   Grep: "CAEmitterLayer", "CHHapticEngine", "UIImpactFeedbackGenerator", "SKScene", "sensoryFeedback"
   

   If one exists, advise on improving it rather than generating a parallel system.

---

Triage mode — when the ask is "make this app feel better"

If the request is broad ("make it feel good / add polish") rather than a specific moment, do not start coding. Inspect first, present a numbered candidate table (# · Area · Opportunity · Suggested feel · Likely APIs · Effort), and let the user pick rows — unless they asked for direct implementation. Read references/feel-judgment.md before a broad pass.

---

The three pillars of feel

Feel comes from causality (feedback at the exact instant of the cause), harmony (the three channels agreeing — a heavy impact = heavy haptic + low thud + big shake), and restraint (feel reserved for moments that matter; if everything is juicy, nothing is). Fire all three channels from the same code path so they stay in sync.

Restraint is context-specific. Some contexts forbid delight — finance/medical/legal, reading-heavy screens, many-times-per-session actions. Shake the container, not the window; propose opt-out toggles. Full exclusion + good-fit lists in references/feel-judgment.md.

INTERACTION (tap, hit, unlock, success)
        │  fire all three at the SAME moment — never delayed
        ├──▶ HAPTIC   what you feel   (UIFeedbackGenerator / Core Haptics)
        ├──▶ VISUAL   what you see    (spring anim, particles, flash, shake)
        └──▶ AUDIO    what you hear   (sound effect, AVAudioEngine, SKAction)

Pillar 1 — Haptics (what you feel)

The fastest, cheapest win in all of game feel. Three tiers, pick the lightest that fits — all code + the full engine lifecycle in references/haptics.md:

• Tier 1 — UIFeedbackGenerator (UIKit, the 90% case). Pre-canned, system-tuned, one line: UIImpactFeedbackGenerator (.light….rigid, call prepare() ~0.1 s before), UISelectionFeedbackGenerator for detents, UINotificationFeedbackGenerator for .success/.warning/.error outcomes.
• Tier 2 — SwiftUI .sensoryFeedback (iOS 17+). Declarative, no generator lifecycle: .sensoryFeedback(.success, trigger: didSave).
• Tier 3 — Core Haptics (CHHapticEngine). Custom patterns + audio sync (charging meter, textured rumble) — transient vs continuous events, dynamic parameters, AHAP files, and the stoppedHandler/resetHandler recovery handlers you MUST set.

Haptic design rules (WWDC "Practice audio haptic design"; expanded in references/haptics.md): causality — fire at the instant of the visual change, NEVER asyncAfter a haptic; harmony — match weight to meaning (heavy object → .heavy/.rigid, success → .success); utility — reserve for significant moments; gate on supportsHaptics, respect Low Power Mode and the system "System Haptics" setting.

Pillar 2 — Visual juice (what you see)

Motion that exaggerates cause and effect. The toolbox, lightest → heaviest:

Spring animations — the single most important juice primitive. Overshoot + settle reads as "alive". Use .spring(response:dampingFraction:): lower dampingFraction = bouncier (0.5–0.6 for playful, 0.8 for subtle).

Symbol effects (iOS 17+) — instant juice on SF Symbols, zero layout work: .symbolEffect(.bounce, value:) (.wiggle on iOS 18).

Squash & stretch on press — .scaleEffect(isPressed ? 0.94 : 1.0) + a spring. Code for all three primitives (and flash & color pop) is in references/view-layer-juice.md ("Juice primitives").

Particles — confetti for celebrations (SwiftUI CAEmitterLayer, references/celebrations.md) or SKEmitterNode for in-scene effects (explosions, sparks, trails — see SpriteKit below).

Screen shake & hitstop — the heavy-impact pair: a brief randomized offset on impact, and freezing the action 1–3 frames so a big hit lands harder. SpriteKit game-loop versions in references/spritekit.md; the SwiftUI/UIKit container-shake path (incl. the "wrong-password" shake, constants, shake↔haptic pairing) in references/view-layer-juice.md.

GPU fragment-shader effects (iOS 17+) — per-pixel feel nothing else can do: tap ripple, shimmer sweep, RGB-split glitch, organic blobs, via colorEffect/distortionEffect/layerEffect: references/gpu-shaders.md.

Rhythm — primary instant, secondary staggered. The primary hit (squash + haptic) is instant per causality, but a second visual layer staggered ~80–180 ms after reads as more alive — stagger visuals only, the haptic never leaves the interaction frame (references/view-layer-juice.md).

The Reduce Motion rule applies to ALL of the above: when on, replace springs with .easeIn, skip particles/shake, show a static reveal. Never lose the information (the badge still appears, the success still confirms) — only drop the motion.

Pillar 3 — Audio feedback (what you hear)

Sound closes the feedback loop. Three options by weight (code in references/haptics.md "Playing feedback sounds"): AudioServicesPlaySystemSound (lightest, honors the silent switch), SKAction.playSoundFileNamed (in-scene one-shot), AVAudioEngine (pitch shift, mixing, layering).

Rules: keep effect files short (CAF/WAV, < a few seconds), respect the mute switch for non-essential SFX, don't play sounds when Reduce Motion is on, and sync the sound to the same trigger frame as the haptic and visual.

Reacting to audio (visuals driven by live sound — visualizer, beat-synced game, voice-level ring): AVAudioEngine tap → vDSP FFT → mel bins + onset/BPM, smoothed with the frame-rate-independent k = 1 - exp(-dt/tau) EMA. Pipeline, tau table, and raw-vs-smoothed rule in references/audio-reactive.md.

---

SpriteKit — the 2D game engine for feel

For anything genuinely game-like (a 2D game, an interactive animated scene, a physics toy), SpriteKit is the native, battery-efficient choice. It renders a tree of nodes (SKScene → SKSpriteNode/SKLabelNode/SKEmitterNode…) and gives you actions, physics, particles, and a camera — exactly the primitives juice is built from. Current for iOS 26 / Swift 6.3.

Scene setup rules (skeleton code in references/spritekit.md): set physicsWorld.contactDelegate in didMove(to:) — never in update() or after a delay; use delta time in update() for frame-rate-independent movement. Embed in SwiftUI with SpriteView — but store the scene in @State so a re-render doesn't recreate it (the #1 SwiftUI+SpriteKit bug).

The juice primitives SpriteKit gives you — actions (SKAction.sequence/ .group/.repeatForever), physics (applyImpulse for snappy jumps), particles (SKEmitterNode), camera (SKCameraNode for shake + follow), shaders (SKShader), lighting. The full API walkthrough + game-loop patterns (screen shake / hitstop / delta-time / object pooling), tile maps, atlases, transitions, joints, and fields: references/spritekit.md.

Before shipping a SpriteKit scene, run the SpriteKit auditor — a structured detector for the bugs that silently kill feel and frame rate (phantom collisions, contacts that never fire, leaked scenes, node accumulation, draw-call waste, time-step bombs): references/spritekit-auditor.md.

Game input & social layers. A real game also needs controller input (references/game-controllers.md) and a social layer (references/game-center-gamekit.md — Game Center + GameKit multiplayer, with the auth-first/silent-failure gotcha).

---

Reward systems — confetti, badges, celebrations

The packaged payoff: when a user hits a milestone (10 workouts, a 7-day streak, a level-up), erupt in a coordinated celebration — CAEmitterLayer confetti, a spring badge reveal fired with .sensoryFeedback(.success), an @Observable milestone tracker that celebrates only once per milestone (persisted), and a Reduce-Motion fade-in fallback. The complete ready-to-drop implementation (confetti for iOS and macOS, overlay, badge views + collection grid, haptic manager, persistent tracker, the one-line .celebrateOnMilestone modifier) is in references/celebrations.md.

Confetti performance gotcha: cap birthRate at 50–80 and use 3–5 distinct particle shapes — 200+ particles drop frames on older chips. Stop emission after the burst; never leave the emitter running.

---

Decision tree — what do I reach for?

I want to…
│
├── review a whole app for feel ("make it feel better")
│     → references/feel-judgment.md (triage table + when-NOT-to-add-feel guardrails)
│
├── add feel to a single interaction (tap / toggle / success / error)
│     → Haptic: .sensoryFeedback (iOS 17+) or UIFeedbackGenerator
│     → Visual: spring scaleEffect, or .symbolEffect on an SF Symbol
│     → Audio:  AudioServicesPlaySystemSound (optional)
│
├── shake on error / reject (form field, card), NO SpriteKit → view-layer-juice.md
├── a GPU per-pixel effect (ripple, shimmer, glitch, blob) → gpu-shaders.md
├── visuals reacting to live audio (visualizer, beat-sync) → audio-reactive.md
│
├── an achievement / milestone / level-up
│     → references/celebrations.md (confetti + badge + overlay + haptic)
│       (report to Game Center too → references/game-center-gamekit.md)
│
├── a custom tactile pattern (charge-up, texture, audio-synced rumble)
│     → Core Haptics → references/haptics.md
│
├── a 2D game or interactive animated scene
│     → SpriteKit → references/spritekit.md (actions, physics, shake, hitstop,
│        emitters) · controllers → game-controllers.md · leaderboards/multiplayer
│        → game-center-gamekit.md · before shipping → spritekit-auditor.md
│
└── lock-screen / Now-Playing media controls, photo picker
      → broader "media & audio" surface; see references/haptics.md "Audio session"
        notes, otherwise a media-specific skill

---

Anti-patterns (the things that kill feel)

The full 17-row anti-pattern/why/fix table is in references/feel-judgment.md. Headlines: never delay a haptic (asyncAfter breaks causality); don't haptic every scroll/keystroke; always gate on supportsHaptics and Reduce Motion; cap confetti birthRate at 50–80; fire all three channels from one trigger; store SpriteView scenes in @State; named PhysicsCategory bitmasks; remove spawned nodes; [weak self] in .repeatForever; honor the mute switch; celebrate milestones once (persisted); no drama in high-trust flows; one haptic per shake (not per oscillation); thumbstick spawns where the thumb lands; authenticate Game Center before matchmaking.

---

Self-audit checklist

Before calling a feel implementation done, run the full checklist in references/feel-judgment.md ("Self-audit checklist") — it gates haptics (interaction-frame timing, supportsHaptics, prepare(), recovery handlers), visuals (springs, squash, capped confetti), audio (short SFX, mute switch, Reduce Motion), accessibility (no information lost when motion is off, Low Power Mode), and SpriteKit (@State scene, bitmasks, delta time, node cleanup, atlases, the auditor pass).

---

References

File	Covers
haptics.md	Core Haptics engine lifecycle, transient vs continuous events, dynamic parameters & curves, AHAP, audio-synced patterns, HapticManager, capability/diagnostics, audio-session notes, feedback-sound options
spritekit.md	Scene lifecycle, nodes, actions, physics, touch, camera, particles, SwiftUI integration, mistakes; tile maps, atlases, transitions, game-loop / delta-time / screen-shake / hitstop / object pooling, audio, lighting, shaders, constraints, joints, fields, performance
spritekit-auditor.md	Structured bug detector: bitmask issues, contact-delegate gaps, leaked scenes, node accumulation, action leaks, coordinate confusion, draw-call waste, time-step bombs, health score, false-positive list
celebrations.md	CAEmitterLayer confetti (iOS + macOS), celebration overlay, badge views + collection grid, @Observable persistent milestone tracker, HapticManager, .celebrateOnMilestone — all Reduce-Motion aware
view-layer-juice.md	Non-SpriteKit juice: container shake (phaseAnimator/keyframeAnimator/CAKeyframeAnimation), wrong-password field shake, duration/amplitude/decay constants, shake↔haptic pairing, primary-instant/secondary-staggered rhythm, juice primitives
gpu-shaders.md	3-modifier decision table, [[stitchable]]/SwiftUI_Metal.h skeleton + Swift→MSL arg mapping, WWDC24 tap-ripple, Inferno recipes (shimmer/water/RGB-split/swirl, MIT), MSL perf rules, shader-math toolkit (smooth-min, centered FBM, two-layer displacement, dual-time drift)
audio-reactive.md	AVAudioEngine tap → vDSP FFT → mel bins + onset/BPM → AudioFrame; frame-rate-independent k = 1 - exp(-dt/tau) EMA, tau table, raw-vs-smoothed accent rule
game-controllers.md	Menu button→UI map, thumbstick-follows-touch, press-under-thumb, brand-correct glyphs, GCController discovery + ContentUnavailableView prompt, keyboard-for-games, visionOS spatial controllers, require-or-not platform table
game-center-gamekit.md	Auth-first (silent failure), access point, achievement/leaderboard/challenge specs (1465×767 crop, recent-score-not-best), real-time vs turn-based multiplayer (reliable/unreliable + Codable envelope, expectedPlayerCount == 0, saveCurrentTurn), sandbox separation, trap + terminology tables
feel-judgment.md	Triage workflow (audit checklist, candidate table, strong/weak heuristics, effort bands), "when NOT to add feel" guardrails (high-trust/reading-heavy/repeated, container-not-window, opt-out toggles), Motion.animate Reduce-Motion helper, anti-pattern table, self-audit checklist