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

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)
        }
    }
}

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)
        }
    }
}

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()
        }
    }
}

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)
    }
}

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 }
    }
}

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)