vfx-spell-effects

# VFX Spell Effects — Game-Quality Visual Effects for Apple Platforms ## Decision Tree ``` What effect do you want? | |-- Smoke / Fog / Clouds? | |-- Soft procedural blobs? -> Canvas noise blobs (like OCMiniOrb smoke) | |-- Volumetric 3D fog? -> Ray marching (Metal fragment shader) | |-- Quick particle smoke? -> SpriteKit SKEmitterNode or Vortex | \-- Fluid dynamics? -> Metal compute (Navier-Stokes, advanced) | -> See: references/smoke-fog.md | |-- Lightning / Electricity? | |-- Single bolt? -> Midpoint displacement (most practical) | |-- Smooth arc? -> Lissajous curves | |-- Branching tree? -> Recursive fractal (Lichtenberg figures) | \-- Glow on bolt? -> Additive bloom post-process | -> See: references/lightning-electricity.md | |-- Particles (fire, sparks, magic)? | |-- Quick preset? -> Vortex (SwiftUI-native) | |-- 2D overlay? -> CAEmitterLayer or SpriteKit | |-- Full GPU control? -> Metal compute shader pipeline | |-- SwiftUI-only? -> Canvas + TimelineView | -> See: references/particles.md | |-- Bloom / Glow / Post-processing? | |-- SwiftUI quick glow? -> .shadow() + .blur() stacking | |-- HDR bloom pipeline? -> Threshold -> Gaussian blur -> Composite (Metal) | |-- Per-object glow? -> Render to texture + blur + additive blend | -> See: references/bloom-glow.md | |-- Composing a full spell? | |-- State machine? -> .idle -> .charging -> .casting -> .impact -> .dissipating | |-- Layer ordering? -> base + particles + glow + screen shake + audio | |-- Audio-reactive? -> Bind intensity to RMS amplitude | -> See: references/spell-composition.md | \-- Performance issue? |-- Dropped frames? -> Check particle count, blur radius, draw calls |-- GPU bottleneck? -> Profile with Xcode GPU debugger |-- CPU bottleneck? -> Move particle update to compute shader -> See: Performance Budget Rules below ``` ## Quick Reference | Effect | Best API | Approach | Ref | |--------|----------|----------|-----| | Soft smoke blobs | SwiftUI Canvas | Noise-offset circles + alpha blend | `references/smoke-fog.md` | | Volumetric fog | Metal fragment | Ray march density field, 4-8 samples | `references/smoke-fog.md` | | Lightning bolt | SwiftUI Canvas / Metal | Midpoint displacement, 4-5 levels | `references/lightning-electricity.md` | | Branching lightning | Canvas + recursion | Fractal tree, angle +/-30deg | `references/lightning-electricity.md` | | Fire particles | Vortex / SpriteKit | Pre-built emitter, warm palette | `references/particles.md` | | Magic sparks | Metal compute | GPU particle pool, 500-2000 particles | `references/particles.md` | | Impact explosion | Vortex + Canvas | Burst emit + radial force + fade | `references/particles.md` | | Object glow | SwiftUI `.shadow` | Stacked `.shadow(radius:)` calls | `references/bloom-glow.md` | | HDR bloom | Metal render pass | Threshold + separable Gaussian + composite | `references/bloom-glow.md` | | Full spell | Composite pattern | State machine + layer stack + timeline | `references/spell-composition.md` | ## Performance Budget Rules (NON-NEGOTIABLE) 1. **16ms frame budget** -- Target 60fps. All VFX layers combined must complete within 16ms GPU + CPU time. 2. **Particle limits** -- Mobile: 500-2000 active particles max. Desktop: up to 10,000 with compute shader. Never allocate mid-frame. 3. **Blur radius cap** -- `.blur(radius:)` over 20pt on mobile tanks performance. Use downscaled render targets for large blurs. 4. **Draw call budget** -- Keep under 10 draw calls for VFX overlay. Use Canvas (1 draw call per layer) or instanced rendering. 5. **Compute shader particles** -- Mandatory for >500 particles. CPU-side `for` loops over particle arrays cause frame drops on mobile. 6. **Ray march samples** -- 4-8 samples per ray for real-time fog. More than 12 is offline-quality territory. 7. **Bloom passes** -- 3-5 blur passes with ping-pong buffers. Downscale to half/quarter resolution for blur. 8. **Pool, never allocate** -- Pre-allocate particle arrays. Use recycle-bin pattern (free list). Zero heap allocation during gameplay. 9. **Reduce motion** -- `@Environment(\.accessibilityReduceMotion)` guards ALL effect starts. Provide static fallback. 10. **Profile on device** -- Simulator GPU timing is meaningless. Test on oldest supported hardware. ## Key Patterns ### State Machine for Spell Lifecycle ```swift enum SpellPhase: String, CaseIterable { case idle, charging, casting, impact, dissipating } @Observable class SpellState { var phase: SpellPhase = .idle var intensity: Float = 0.0 // 0.0-1.0 var elapsed: TimeInterval = 0.0 func advance(dt: TimeInterval) { elapsed += dt switch phase { case .charging: intensity = min(1.0, Float(elapsed / 0.5)) case .casting: intensity = 1.0 case .impact: intensity = max(0.0, 1.0 - Float(elapsed / 0.3)) case .dissipating: intensity = max(0.0, 0.5 - Float(elapsed / 0.6)) case .idle: intensity = 0.0 } } } ``` ### Canvas-Based Effect Layer ```swift struct EffectLayer: View { let state: SpellState @Environment(\.accessibilityReduceMotion) private var reduceMotion var body: some View { if !reduceMotion && state.phase != .idle { TimelineView(.animation(minimumInterval: 1.0 / 60.0)) { ctx in Canvas { context, size in // Draw effect here -- single draw call let t = ctx.date.timeIntervalSinceReferenceDate drawEffect(context: context, size: size, time: t, intensity: state.intensity) } } } } } ``` ### Midpoint Displacement Lightning (Minimal) ```swift func generateBolt(from: CGPoint, to: CGPoint, levels: Int = 5, jaggedness: CGFloat = 0.4) -> [CGPoint] { var points = [from, to] for level in 0..<levels { var newPoints = [points[0]] let scale = jaggedness * pow(0.5, CGFloat(level)) for i in 0..<(points.count - 1) { let mid = CGPoint( x: (points[i].x + points[i+1].x) / 2 + CGFloat.random(in: -1...1) * scale * from.distance(to: to), y: (points[i].y + points[i+1].y) / 2 + CGFloat.random(in: -1...1) * scale * from.distance(to: to) ) newPoints.append(mid) newPoints.append(points[i+1]) } points = newPoints } return points } ``` ## References | File | Content | |------|---------| | `references/smoke-fog.md` | Noise-based smoke, ray marching fog, Canvas blobs, Metal fluid dynamics | | `references/lightning-electricity.md` | Fractal midpoint displacement, Lissajous arcs, branching trees, glow rendering | | `references/particles.md` | API comparison, GPU particle architecture, emission patterns, pool pattern, Vortex presets | | `references/bloom-glow.md` | HDR bloom pipeline, threshold/blur/composite, Metal + SwiftUI integration | | `references/spell-composition.md` | State machine, layer stacking, audio-reactive binding, timing curves, full spell examples | ## External Resources - [Vortex](https://github.com/twostraws/Vortex) -- SwiftUI-native particle system - [Inferno](https://github.com/twostraws/Inferno) -- Metal shader collection for SwiftUI - [MetalNoise](https://github.com/jmade/MetalNoise) -- Perlin/Simplex noise in Metal - [The Book of Shaders: Noise](https://thebookofshaders.com/11/) -- Noise function fundamentals - [Ray Marching SDFs](https://jamie-wong.com/2016/07/15/ray-marching-signed-distance-functions/) -- Ray marching primer - [2D Lightning Effects](https://gamedevelopment.tutsplus.com/tutorials/how-to-generate-shockingly-good-2d-lightning-effects--gamedev-2681) -- Midpoint displacement tutorial - [LearnOpenGL: Bloom](https://learnopengl.com/Advanced-Lighting/Bloom) -- HDR bloom pipeline reference - [Realtime Fire Rendering](https://andrewkchan.dev/posts/fire.html) -- Procedural fire techniques ## Related Skills - **orb** -- OCMiniOrb implementation (smoke layer, fractal layer, glow compositing) - **swiftui-animation** -- Animation curves, springs, Metal shader integration in SwiftUI - **swiftui-performance-audit** -- Runtime GPU/CPU profiling when effects cause frame drops ## Technique Map - **Effect type routing** — Smoke/fog, lightning, particles, bloom, full spell; because each has distinct API and approach. - **State machine for lifecycle** — idle→charging→casting→impact→dissipating; because spells have phases; state drives intensity. - **16ms frame budget** — 60fps non-negotiable; because dropped frames break immersion. - **Particle limits** — 500-2000 mobile; 10k desktop with compute; because CPU particle loops tank mobile. - **Canvas for overlay** — Single draw call per layer; because draw call budget matters. - **Pool, never allocate** — Recycle bin pattern; because mid-frame allocation causes hitches. - **Reduce motion guard** — Static fallback when accessibilityReduceMotion; because necessary for compliance. - **Midpoint displacement** — For lightning; 4-5 levels; because simple, effective, performant. ## Technique Notes References: smoke-fog, lightning-electricity, particles, bloom-glow, spell-composition. APIs: Vortex, SpriteKit, Metal compute, Canvas. Profile on device; simulator GPU timing meaningless. Related: orb, swiftui-animation, swiftui-performance-audit. --- ## Prompt Architect Overlay **Role Definition:** VFX spell effects builder. Game-quality smoke, lightning, particles, bloom, spell composition. 60fps performance rules. Apple platforms. **Input Contract:** Accepts effect type (smoke, lightning, fire, glow, full spell), target API (Vortex, Metal, Canvas), or performance issue. Platform, particle count, style. **Output Contract:** Decision tree result. Quick reference row. Code pattern (state machine, canvas layer, midpoint displacement). Performance budget rules. Reference to deep-dive. Related skills. **Edge Cases & Fallbacks:** If performance issue→check particle count, blur radius, draw calls. If >500 particles→compute shader mandatory. If bloom→downscale for blur passes. If reduce motion→guard all effects; provide static fallback.