scenekit-game

SceneKit 3D Game Development

ARCHITECTURE OVERRIDE: 3D games use SceneKit (SCNScene + SceneView), NOT SpriteKit or plain SwiftUI views with timers or Canvas. The standard @main App → RootView → MainView pattern still applies, but MainView hosts a SceneView instead of standard SwiftUI content. AppTheme rules apply to SwiftUI parts (menus, overlays, HUD) but NOT to SceneKit scene internals where you use SCNVector3, SCNMaterial colors, etc. directly.

Also load the game-assets skill for downloading 3D models and textures via nw_download_asset. Also load the game-ui skill for SwiftUI HUD overlays, menus, and virtual controls.

SceneView — SwiftUI Bridge

import SceneKit
import SwiftUI

struct GameView: View {
    @State var gameState = GameState()
    @State private var scene = GameScene()

    var body: some View {
        ZStack {
            SceneView(
                scene: scene.scnScene,
                pointOfView: scene.cameraNode,
                options: [.allowsCameraControl, .autoenablesDefaultLighting]
            )
            .ignoresSafeArea()

            // SwiftUI overlays for HUD, menus (use AppTheme here)
            if gameState.phase == .paused {
                PauseMenuView(gameState: gameState)
            }
        }
        .onAppear { scene.gameState = gameState }
    }
}

Rules:

• Use SceneView(scene:pointOfView:options:) — the native SwiftUI bridge for SceneKit
• .allowsCameraControl enables orbit/pan/zoom (remove for fixed-camera games)
• .autoenablesDefaultLighting adds ambient + directional light (remove when adding custom lights)
• Pass data between SwiftUI and SceneKit via @Observable game state objects
• SwiftUI overlays (menus, HUD, pause) sit in a ZStack above SceneView
• SwiftUI parts use AppTheme. SceneKit scene internals use SCNMaterial/SCNVector3 directly.

Scene Architecture

@Observable
class GameScene: NSObject, SCNSceneRendererDelegate {
    let scnScene = SCNScene()
    let cameraNode = SCNNode()
    var gameState: GameState?

    override init() {
        super.init()
        setupCamera()
        setupLighting()
        setupEnvironment()
    }

    private func setupCamera() {
        cameraNode.camera = SCNCamera()
        cameraNode.position = SCNVector3(0, 10, 15)
        cameraNode.look(at: SCNVector3Zero)
        scnScene.rootNode.addChildNode(cameraNode)
    }

    private func setupLighting() {
        let ambientLight = SCNNode()
        ambientLight.light = SCNLight()
        ambientLight.light?.type = .ambient
        ambientLight.light?.intensity = 500
        scnScene.rootNode.addChildNode(ambientLight)

        let directionalLight = SCNNode()
        directionalLight.light = SCNLight()
        directionalLight.light?.type = .directional
        directionalLight.light?.intensity = 1000
        directionalLight.light?.castsShadow = true
        directionalLight.eulerAngles = SCNVector3(-Float.pi / 4, 0, 0)
        scnScene.rootNode.addChildNode(directionalLight)
    }
}