swift-game-engine

# Swift Game Engine Selection & VFX Architecture ## Decision Tree ``` What are you building? | |-- 2D Game / 2D Effects? | |-- Simple sprites + physics? -> SpriteKit (built-in, battle-tested) | |-- UI particle overlays in SwiftUI? -> Vortex (zero Metal knowledge) | |-- GPU shader effects on SwiftUI views? -> Inferno (Metal fragments) | |-- Declarative particles (no Metal)? -> SwiftUI-Particles (Canvas-based) | |-- Cross-platform 2D? -> GateEngine (macOS/Win/Linux/iOS/Android/Web) | -> See: references/apple-frameworks.md#spritekit | |-- 3D Game / 3D Scene? | |-- AR / visionOS / spatial? -> RealityKit (Apple's primary 3D) | |-- Quick 3D prototype (non-AR)? -> RealityKit (SceneKit is deprecated) | |-- Pure Swift 3D engine? -> Untold Engine (custom Metal renderer) | |-- Cross-platform 3D? -> GateEngine or SwiftVVD | |-- AAA-quality custom pipeline? -> Metal direct (maximum control) | -> See: references/apple-frameworks.md#realitykit | |-- VFX / Post-Processing Pipeline? | |-- SwiftUI shader effects? -> .colorEffect / .layerEffect / .distortionEffect (iOS 17+) | |-- Full post-process stack? -> Metal render passes (effect compositor) | |-- Console-quality techniques? -> references/ps5-techniques.md | |-- Bloom / glow / TAA / SSR? -> Metal compute + render passes | -> See: references/architecture-patterns.md#effect-stack | |-- Game Logic / AI (renderer-agnostic)? | |-- State machines? -> GameplayKit GKStateMachine | |-- Pathfinding / nav mesh? -> GameplayKit GKGraphNode | |-- AI opponents? -> GameplayKit GKMinMaxStrategist | |-- Procedural noise? -> GameplayKit GKNoise | |-- ECS architecture? -> RealityKit (native) or Fireblade ECS (standalone) | -> See: references/apple-frameworks.md#gameplaykit | |-- Custom Render Engine? | |-- From scratch, maximum GPU control? -> Metal direct | |-- Need ECS but not RealityKit? -> Fireblade ECS + Metal | |-- Cross-API (Vulkan + Metal)? -> SwiftVVD | |-- Render graph architecture? -> references/architecture-patterns.md | -> See: references/apple-frameworks.md#metal | \-- Unsure / Need Comparison? -> See: Comparison Matrix below ``` ## Comparison Matrix | Framework | VFX Cap | SwiftUI | 3D | Perf Ceiling | Learning | Status | |-----------|---------|---------|----|----|----------|--------| | **SpriteKit** | Mid | SpriteView | No | Mid | Low | Active | | **SceneKit** | Mid-High | SceneView | Yes | Mid | Mid | **Deprecated** (WWDC25) | | **RealityKit** | High | RealityView | Yes | High | Mid-High | Active (primary) | | **Metal** | Maximum | MTKView/UIViewRep | Yes | Maximum | High | Active (Metal 4) | | **GameplayKit** | N/A (logic) | N/A | N/A | N/A | Low | Active | | **Vortex** | Low-Mid | Native | No | Low | Very Low | Active | | **Inferno** | Mid | Native | No | Mid | Low | Active | | **SwiftUI-Particles** | Low | Native | No | Low | Very Low | Community | | **GateEngine** | Mid | No | Yes | Mid | Mid | Active | | **Untold Engine** | Mid-High | No | Yes | Mid-High | Mid-High | Active | | **SwiftVVD** | High | No | Yes | High | High | Niche | | **Fireblade ECS** | N/A (arch) | N/A | N/A | N/A | Mid | Active | **Rating key:** VFX Cap = range of visual effects achievable. Perf Ceiling = maximum rendering throughput. Learning = time to first meaningful output. Status as of 2025. **SceneKit warning:** Deprecated at WWDC 2025. Critical-bug-only maintenance. Do NOT start new projects with SceneKit. Migrate existing projects to RealityKit. ## Quick-Start Patterns ### SpriteKit (2D Game) ```swift import SpriteKit import SwiftUI struct GameView: View { var body: some View { SpriteView(scene: makeScene()) .ignoresSafeArea() } func makeScene() -> SKScene { let scene = GameScene(size: CGSize(width: 390, height: 844)) scene.scaleMode = .aspectFill return scene } } class GameScene: SKScene { override func didMove(to view: SKView) { // Particle emitter if let emitter = SKEmitterNode(fileNamed: "Fire") { emitter.position = CGPoint(x: size.width / 2, y: size.height / 2) addChild(emitter) } } } ``` ### RealityKit (3D / AR) ```swift import RealityKit import SwiftUI struct Scene3DView: View { var body: some View { RealityView { content in let sphere = MeshResource.generateSphere(radius: 0.1) var material = PhysicallyBasedMaterial() material.baseColor = .init(tint: .blue) material.roughness = .init(floatLiteral: 0.2) material.metallic = .init(floatLiteral: 0.8) let entity = ModelEntity(mesh: sphere, materials: [material]) content.add(entity) } } } ``` ### Metal (Custom Pipeline) ```swift import MetalKit import SwiftUI struct MetalView: UIViewRepresentable { func makeUIView(context: Context) -> MTKView { let view = MTKView() view.device = MTLCreateSystemDefaultDevice() view.delegate = context.coordinator view.preferredFramesPerSecond = 60 view.colorPixelFormat = .bgra8Unorm return view } func updateUIView(_ uiView: MTKView, context: Context) {} func makeCoordinator() -> Renderer { Renderer() } class Renderer: NSObject, MTKViewDelegate { var device: MTLDevice! var commandQueue: MTLCommandQueue! var pipelineState: MTLRenderPipelineState! override init() { super.init() device = MTLCreateSystemDefaultDevice()! commandQueue = device.makeCommandQueue()! // Build pipeline from .metal shader file } func mtkView(_ view: MTKView, drawableSizeWillChange size: CGSize) {} func draw(in view: MTKView) { guard let drawable = view.currentDrawable, let descriptor = view.currentRenderPassDescriptor, let buffer = commandQueue.makeCommandBuffer(), let encoder = buffer.makeRenderCommandEncoder(descriptor: descriptor) else { return } encoder.setRenderPipelineState(pipelineState) // Draw calls here encoder.endEncoding() buffer.present(drawable) buffer.commit() } } } ``` ### Vortex (SwiftUI Particles) ```swift import Vortex import SwiftUI struct FireView: View { var body: some View { VortexView(.fire) { Circle() .fill(.orange) .frame(width: 16, height: 16) .blur(radius: 3) .tag("circle") } .frame(width: 200, height: 300) } } ``` ### Inferno (Metal Shader on SwiftUI View) ```swift import Inferno import SwiftUI struct GlowingCard: View { @State private var time: Float = 0 let timer = Timer.publish(every: 1/60, on: .main, in: .common).autoconnect() var body: some View { RoundedRectangle(cornerRadius: 16) .fill(.blue) .frame(width: 200, height: 120) .colorEffect(ShaderLibrary.emboss(.float(time))) .onReceive(timer) { _ in time += 1/60 } } } ``` ## Architecture Patterns (Summary) | Pattern | Use Case | Key Idea | Reference | |---------|----------|----------|-----------| | **ECS** | Games, simulations | Entities = IDs, Components = data, Systems = logic | `references/architecture-patterns.md#ecs` | | **Render Graph** | Custom Metal pipelines | DAG of render passes, auto resource management | `references/architecture-patterns.md#render-graph` | | **Effect Stack** | Post-processing | Ordered list: bloom -> color grade -> vignette -> FXAA | `references/architecture-patterns.md#effect-stack` | | **VFX Manager** | Spawning effects | Centralized pool + spawn API | `references/architecture-patterns.md#vfx-manager` | | **Audio-Visual Sync** | Reactive effects | FFT/RMS -> parameter bridge -> VFX intensity | `references/architecture-patterns.md#audio-visual-sync` | | **State-Driven** | Spell lifecycles | enum state machine drives VFX transitions | `references/architecture-patterns.md#state-driven-effects` | | **Composition** | Complex effects | SpellEffect = [Particle + Shader + Audio + Shake] | `references/architecture-patterns.md#composition` | ## Console-Quality on Apple Silicon (Summary) | Technique | M1 | M2 | M3/M4 | PS5 Equivalent | |-----------|----|----|-------|----------------| | TAA | Yes | Yes | Yes | Yes | | MetalFX Upscaling | Yes | Yes | Yes | PSSR/DLSS/FSR | | Screen-Space Reflections | Yes | Yes | Yes | Yes | | Mesh Shaders | No | Partial | Yes | Yes | | Variable Rate Shading | No | No | Yes | Yes | | Ray Tracing | Basic | Better | Full | Yes | **Feasibility:** M1 = 60-80% PS5 quality. M2 = 70-85%. M3/M4 = 80-90%. Key bottleneck: memory bandwidth. See `references/ps5-techniques.md` for implementation details. ## Framework Selection Cheat Sheet ``` Need SwiftUI integration? |-- Yes + 2D particles? -> Vortex |-- Yes + shader effects? -> Inferno or .colorEffect/.layerEffect |-- Yes + 3D scene? -> RealityView (RealityKit) |-- Yes + 2D game? -> SpriteView (SpriteKit) |-- Yes + custom GPU? -> MTKView in UIViewRepresentable \-- No? -> Metal direct, GateEngine, or Untold Engine Need cross-platform? |-- Apple only? -> SpriteKit / RealityKit / Metal |-- Apple + Windows + Linux? -> GateEngine |-- Apple + Vulkan platforms? -> SwiftVVD \-- Apple + Web? -> GateEngine Need ECS? |-- Built into renderer? -> RealityKit |-- Standalone (any renderer)? -> Fireblade ECS \-- With SpriteKit? -> OctopusKit (archived, use cautiously) ``` ## References | File | Content | |------|---------| | `references/apple-frameworks.md` | Deep dive on SpriteKit, SceneKit, RealityKit, Metal, GameplayKit | | `references/third-party-engines.md` | Vortex, Inferno, GateEngine, Untold, SwiftVVD, Fireblade ECS, OctopusKit | | `references/ps5-techniques.md` | TAA, MetalFX, SSR, mesh shaders, VRS, ray tracing, feasibility matrix | | `references/architecture-patterns.md` | ECS, render graph, effect stack, VFX manager, audio-visual sync, state-driven, composition | ## Related Skills - **vfx-spell-effects** -- Specific VFX implementations (smoke, lightning, particles, bloom, spell composition) - **metal-shaders** -- Shader authoring for any engine (MSL, vertex/fragment/compute) - **orb** -- Practical multi-layer VFX composition in SwiftUI (OCMiniOrb) - **swiftui-animation** -- Animation integration with engine rendering ## External Resources - [Apple Metal](https://developer.apple.com/metal/) - [Apple SpriteKit](https://developer.apple.com/documentation/spritekit/) - [Apple SceneKit](https://developer.apple.com/documentation/scenekit/) - [Apple RealityKit](https://developer.apple.com/documentation/realitykit/) - [Apple MetalFX](https://developer.apple.com/documentation/metalfx) - [Vortex](https://github.com/twostraws/Vortex) -- SwiftUI particles - [Inferno](https://github.com/twostraws/Inferno) -- Metal shaders for SwiftUI - [GateEngine](https://github.com/STREGAsGate/GateEngine) -- Cross-platform Swift - [Untold Engine](https://github.com/untoldengine/UntoldEngine) -- Pure Swift 3D - [Fireblade ECS](https://github.com/fireblade-engine/ecs) -- Standalone ECS - [SpriteKit vs SceneKit vs Metal](https://www.brsoftech.com/blog/spritekit-vs-scenekit-vs-metal/) ## Technique Map - **Decision tree by target** — 2D game, 3D/AR, VFX pipeline, game logic, custom renderer; because framework choice depends on use case.