Scenekit

SceneKit

Apple's high-level 3D rendering framework for maintaining existing scenes and visualizations on iOS using Swift 6.3. Provides a node-based scene graph, built-in geometry primitives, physically based materials, lighting, animation, and physics.

Deprecation notice (WWDC 2025): SceneKit is officially deprecated across all Apple platforms and is now in maintenance mode (critical bug fixes only). Existing apps continue to work. For new projects or major updates, Apple recommends RealityKit. See WWDC 2025 session 288 for migration guidance.

Contents

• Scene Setup
• Nodes and Geometry
• Materials
• Lighting
• Cameras
• Animation
• Physics
• Particle Systems
• Loading Models
• SwiftUI Integration
• Common Mistakes
• Review Checklist
• References

Scene Setup

SCNView in UIKit

import SceneKit

let sceneView = SCNView(frame: view.bounds)
sceneView.scene = SCNScene()
sceneView.allowsCameraControl = true
sceneView.autoenablesDefaultLighting = true
sceneView.backgroundColor = .black
view.addSubview(sceneView)

allowsCameraControl adds built-in orbit, pan, and zoom gestures. Typically disabled in production where custom camera control is needed.

Creating an SCNScene

let scene = SCNScene()                                          // Empty
guard let scene = SCNScene(named: "art.scnassets/ship.scn")     // .scn in .scnassets
    else { fatalError("Missing scene asset") }
let url = Bundle.main.url(forResource: "ship", withExtension: "dae")!
let scene = try SCNScene(url: url, options: [.checkConsistency: true])

Nodes and Geometry

Every scene has a rootNode. All content exists as descendant nodes. Nodes define position, orientation, and scale in their parent's coordinate system. SceneKit uses a right-handed coordinate system: +X right, +Y up, +Z toward the camera.

let parentNode = SCNNode()
scene.rootNode.addChildNode(parentNode)

let childNode = SCNNode()
childNode.position = SCNVector3(0, 1, 0)  // 1 unit above parent
parentNode.addChildNode(childNode)

Transforms

node.position = SCNVector3(x: 0, y: 2, z: -5)
node.eulerAngles = SCNVector3(x: 0, y: .pi / 4, z: 0)  // 45-degree Y rotation
node.scale = SCNVector3(2, 2, 2)
node.simdPosition = SIMD3<Float>(0, 2, -5)  // Prefer simd for performance

Built-in Primitives

SCNBox, SCNSphere, SCNCylinder, SCNCone, SCNTorus, SCNCapsule, SCNTube, SCNPlane, SCNFloor, SCNText, SCNShape (extruded Bezier path).

let node = SCNNode(geometry: SCNSphere(radius: 0.5))

Finding Nodes

let maxNode = scene.rootNode.childNode(withName: "Max", recursively: true)
let enemies = scene.rootNode.childNodes { node, _ in
    node.name?.hasPrefix("enemy") == true
}

Materials

SCNMaterial defines surface appearance. Use firstMaterial for single-material geometries or the materials array for multi-material.

Color and Texture

let material = SCNMaterial()
material.diffuse.contents = UIColor.systemBlue     // Solid color
material.diffuse.contents = UIImage(named: "brick") // Texture
material.normal.contents = UIImage(named: "brick_normal")
sphere.firstMaterial = material

Physically Based Rendering (PBR)

let pbr = SCNMaterial()
pbr.lightingModel = .physicallyBased
pbr.diffuse.contents = UIImage(named: "albedo")
pbr.metalness.contents = 0.8       // Scalar or texture
pbr.roughness.contents = 0.2       // Scalar or texture
pbr.normal.contents = UIImage(named: "normal")
pbr.ambientOcclusion.contents = UIImage(named: "ao")

Lighting Models

.physicallyBased (metalness/roughness), .blinn (default), .phong, .lambert (diffuse-only), .constant (unlit), .shadowOnly.

Each material property is an SCNMaterialProperty accepting UIColor, UIImage, CGFloat scalar, SKTexture, CALayer, or AVPlayer.

Transparency

material.transparency = 0.5
material.transparencyMode = .dualLayer
material.isDoubleSided = true

Lighting

Attach an SCNLight to a node. The light's direction follows the node's negative Z-axis.

Light Types

// Ambient: uniform, no direction
let ambient = SCNLight()
ambient.type = .ambient
ambient.color = UIColor(white: 0.3, alpha: 1)

// Directional: parallel rays (sunlight)
let directional = SCNLight()
directional.type = .directional
directional.castsShadow = true

// Omni: point light, all directions
let omni = SCNLight()
omni.type = .omni
omni.attenuationEndDistance = 20

// Spot: cone-shaped
let spot = SCNLight()
spot.type = .spot
spot.spotInnerAngle = 20
spot.spotOuterAngle = 60

Attach to a node:

let lightNode = SCNNode()
lightNode.light = directional
lightNode.eulerAngles = SCNVector3(-Float.pi / 3, 0, 0)
lightNode.position = SCNVector3(0, 10, 10)
scene.rootNode.addChildNode(lightNode)

Shadows

light.castsShadow = true
light.shadowMapSize = CGSize(width: 2048, height: 2048)
light.shadowSampleCount = 8
light.shadowRadius = 3.0
light.shadowColor = UIColor(white: 0, alpha: 0.5)

Category Bit Masks

light.categoryBitMask = 1 << 1     // Category 2
node.categoryBitMask = 1 << 1      // Only lit by category-2 lights

SceneKit renders a maximum of 8 lights per node. Use attenuationEndDistance on point/spot lights so SceneKit skips them for distant nodes.

Cameras

Attach an SCNCamera to a node to define a viewpoint.

let cameraNode = SCNNode()
cameraNode.camera = SCNCamera()
cameraNode.position = SCNVector3(0, 5, 15)
cameraNode.look(at: SCNVector3Zero)
scene.rootNode.addChildNode(cameraNode)
sceneView.pointOfView = cameraNode

Configuration

camera.fieldOfView = 60                        // Degrees
camera.zNear = 0.1
camera.zFar = 500
camera.automaticallyAdjustsZRange = true

// Orthographic
camera.usesOrthographicProjection = true
camera.orthographicScale = 10

Depth-of-field (wantsDepthOfField, focusDistance, fStop) and HDR effects (wantsHDR, bloomIntensity, bloomThreshold, screenSpaceAmbientOcclusionIntensity) are configured directly on SCNCamera.

Animation

SceneKit provides three animation approaches.

SCNAction (Declarative, Game-Oriented)

Reusable, composable animation objects attached to nodes.

let move = SCNAction.move(by: SCNVector3(0, 2, 0), duration: 1)
let rotate = SCNAction.rotateBy(x: 0, y: .pi, z: 0, duration: 1)
node.runAction(.group([move, rotate]))

// Sequential
node.runAction(.sequence([.fadeOut(duration: 0.3), .removeFromParentNode()]))

// Infinite loop
let pulse = SCNAction.sequence([
    .scale(to: 1.2, duration: 0.5),
    .scale(to: 1.0, duration: 0.5)
])
node.runAction(.repeatForever(pulse))

SCNTransaction (Implicit Animation)

SCNTransaction.begin()
SCNTransaction.animationDuration = 1.0
node.position = SCNVector3(5, 0, 0)
node.opacity = 0.5
SCNTransaction.completionBlock = { print("Done") }
SCNTransaction.commit()

Explicit Animations (Core Animation)

let animation = CABasicAnimation(keyPath: "rotation")
animation.toValue = NSValue(scnVector4: SCNVector4(0, 1, 0, Float.pi * 2))
animation.duration = 2
animation.repeatCount = .infinity
node.addAnimation(animation, forKey: "spin")

Physics

Physics Bodies

node.physicsBody = SCNPhysicsBody(type: .dynamic, shape: nil)   // Forces + collisions
floor.physicsBody = SCNPhysicsBody(type: .static, shape: nil)    // Immovable
platform.physicsBody = SCNPhysicsBody(type: .kinematic, shape: nil) // Code-driven

When shape is nil, SceneKit derives it from geometry. For performance, use simplified shapes:

let shape = SCNPhysicsShape(
    geometry: SCNBox(width: 1, height: 2, length: 1, chamferRadius: 0),
    options: nil
)
node.physicsBody = SCNPhysicsBody(type: .dynamic, shape: shape)
node.physicsBody?.mass = 2.0
node.physicsBody?.restitution = 0.3

Applying Forces

node.physicsBody?.applyForce(SCNVector3(0, 10, 0), asImpulse: false) // Continuous
node.physicsBody?.applyForce(SCNVector3(0, 5, 0), asImpulse: true)   // Instant
node.physicsBody?.applyTorque(SCNVector4(0, 1, 0, 2), asImpulse: true)

Collision Detection

struct PhysicsCategory {
    static let player:     Int = 1 << 0
    static let enemy:      Int = 1 << 1
    static let ground:     Int = 1 << 2
}

playerNode.physicsBody?.categoryBitMask = PhysicsCategory.player
playerNode.physicsBody?.collisionBitMask = PhysicsCategory.ground | PhysicsCategory.enemy
playerNode.physicsBody?.contactTestBitMask = PhysicsCategory.enemy

scene.physicsWorld.contactDelegate = self

func physicsWorld(_ world: SCNPhysicsWorld, didBegin contact: SCNPhysicsContact) {
    handleCollision(between: contact.nodeA, and: contact.nodeB)
}

Gravity

scene.physicsWorld.gravity = SCNVector3(0, -9.8, 0)
node.physicsBody?.isAffectedByGravity = false

Particle Systems

SCNParticleSystem creates effects like fire, smoke, rain, and sparks.

let particles = SCNParticleSystem()
particles.birthRate = 100
particles.particleLifeSpan = 2
particles.particleSize = 0.1
particles.particleColor = .orange
particles.emitterShape = SCNSphere(radius: 0.5)
particles.particleVelocity = 2
particles.isAffectedByGravity = true
particles.blendMode = .additive

let emitterNode = SCNNode()
emitterNode.addParticleSystem(particles)
scene.rootNode.addChildNode(emitterNode)

Load from Xcode particle editor with SCNParticleSystem(named: "fire.scnp", inDirectory: nil). Particles can collide with geometry via colliderNodes.

Loading Models

SceneKit's documented scene-source formats are .scn, .dae, and .abc. For bundled assets, place scene files in a .scnassets folder and texture images in asset catalogs so Xcode can optimize them for target devices.

USD/USDZ is the RealityKit migration path, not the default SceneKit loading path. For new projects, significant updates, or SCN-to-USD asset conversion, handoff to the RealityKit skill.

guard let scene = SCNScene(named: "art.scnassets/ship.scn") else { return }
let scene = try SCNScene(url: Bundle.main.url(
    forResource: "model", withExtension: "dae")!,
    options: [.checkConsistency: true])
guard let modelNode = scene.rootNode.childNode(withName: "mesh", recursively: true) else { return }

Use SCNReferenceNode with .onDemand loading policy for large models. For import-time unit conversion, use SCNSceneSource.LoadingOption:

let source = SCNSceneSource(url: url, options: nil)!
let scene = try source.scene(options: [.convertUnitsToMeters: 1.0])

Do not use SCNScene.Attribute.unit or UnitMetersPerUnit. SCNScene.Attribute is metadata only: .startTime, .endTime, .frameRate, and .upAxis.

SwiftUI Integration

SceneView embeds SceneKit in SwiftUI:

import SwiftUI
import SceneKit

struct SceneKitView: View {
    let scene: SCNScene = {
        let scene = SCNScene()
        let sphere = SCNNode(geometry: SCNSphere(radius: 1))
        sphere.geometry?.firstMaterial?.lightingModel = .physicallyBased
        sphere.geometry?.firstMaterial?.diffuse.contents = UIColor.systemBlue
        sphere.geometry?.firstMaterial?.metalness.contents = 0.8
        scene.rootNode.addChildNode(sphere)
        return scene
    }()

    var body: some View {
        SceneView(scene: scene,
                  options: [.allowsCameraControl, .autoenablesDefaultLighting])
    }
}

Options: .allowsCameraControl, .autoenablesDefaultLighting, .jitteringEnabled, .temporalAntialiasingEnabled.

For render loop control, wrap SCNView in UIViewRepresentable with an SCNSceneRendererDelegate coordinator. See references/scenekit-patterns.md.

Common Mistakes

Not adding a camera or lights

// DON'T: Scene renders blank or black -- no camera, no lights
sceneView.scene = scene

// DO: Add camera + lights, or use convenience flags
let cameraNode = SCNNode()
cameraNode.camera = SCNCamera()
cameraNode.position = SCNVector3(0, 5, 15)
scene.rootNode.addChildNode(cameraNode)
sceneView.pointOfView = cameraNode
sceneView.autoenablesDefaultLighting = true

Using exact geometry for physics shapes

// DON'T
node.physicsBody = SCNPhysicsBody(type: .dynamic,
    shape: SCNPhysicsShape(geometry: complexMesh, options: nil))

// DO: Simplified primitive
node.physicsBody = SCNPhysicsBody(type: .dynamic,
    shape: SCNPhysicsShape(
        geometry: SCNBox(width: 1, height: 2, length: 1, chamferRadius: 0),
        options: nil))

Modifying transforms on dynamic bodies

// DON'T: Resets physics simulation
dynamicNode.position = SCNVector3(5, 0, 0)

// DO: Use forces/impulses
dynamicNode.physicsBody?.applyForce(SCNVector3(10, 0, 0), asImpulse: true)

Review Checklist

• [ ] Scene has at least one camera node set as pointOfView
• [ ] Scene has appropriate lighting (or autoenablesDefaultLighting for prototyping)
• [ ] Physics shapes use simplified geometry, not full mesh detail
• [ ] contactTestBitMask set for bodies that need collision callbacks
• [ ] SCNPhysicsContactDelegate assigned to scene.physicsWorld.contactDelegate
• [ ] Dynamic body transforms changed via forces/impulses, not direct position
• [ ] Lights limited to 8 per node; attenuationEndDistance set on point/spot lights
• [ ] Materials use .physicallyBased lighting model for realistic rendering
• [ ] SceneKit assets use documented .scn, .dae, or .abc scene-source formats
• [ ] Bundled SceneKit textures/images use asset catalogs or Xcode-optimized resources
• [ ] Scene metadata/import options use documented API; no invented SCNScene.Attribute.unit
• [ ] New USD/USDZ pipelines or significant updates are routed to RealityKit
• [ ] Game Center authentication, leaderboards, achievements, or multiplayer are handed off to GameKit
• [ ] SCNReferenceNode used for large models to enable lazy loading
• [ ] Particle birthRate and particleLifeSpan balanced to control particle count
• [ ] categoryBitMask used to scope lights and cameras to relevant nodes
• [ ] SwiftUI scenes use SceneView or UIViewRepresentable-wrapped SCNView
• [ ] Deprecation acknowledged; RealityKit evaluated for new projects

References

• See references/scenekit-patterns.md for custom geometry, shader modifiers, constraints, morph targets, hit testing, scene serialization, render loop delegates, performance, SpriteKit overlay, LOD, and Metal shaders.
• SceneKit documentation, SCNSceneSource, SCNView, SceneView
• SCNPhysicsShape, SCNShadable
• WWDC 2025 session 288: Bring your SceneKit project to RealityKit

SceneKit Patterns

Advanced patterns and techniques for SceneKit development. Covers custom geometry construction, shader modifiers, node constraints, morph targets, hit testing, scene serialization, performance optimization, and SpriteKit overlay rendering.

Contents

• Custom Geometry
• Shader Modifiers
• Node Constraints
• Morph Targets
• Hit Testing
• Scene Serialization
• Render Loop and Delegates
• Performance Optimization
• SpriteKit Overlay
• Level of Detail
• SCNProgram and Metal Shaders

Custom Geometry

Build geometry from vertex data using SCNGeometrySource and SCNGeometryElement.

Triangle Mesh

import SceneKit

func makeTriangle() -> SCNGeometry {
    let vertices: [SCNVector3] = [
        SCNVector3(-0.5, 0, 0),
        SCNVector3( 0.5, 0, 0),
        SCNVector3( 0,   1, 0)
    ]
    let normals: [SCNVector3] = [
        SCNVector3(0, 0, 1),
        SCNVector3(0, 0, 1),
        SCNVector3(0, 0, 1)
    ]
    let texCoords: [CGPoint] = [
        CGPoint(x: 0, y: 0),
        CGPoint(x: 1, y: 0),
        CGPoint(x: 0.5, y: 1)
    ]
    let indices: [UInt16] = [0, 1, 2]

    let vertexSource = SCNGeometrySource(vertices: vertices)
    let normalSource = SCNGeometrySource(normals: normals)
    let uvSource = SCNGeometrySource(textureCoordinates: texCoords)

    let element = SCNGeometryElement(
        indices: indices,
        primitiveType: .triangles
    )

    return SCNGeometry(sources: [vertexSource, normalSource, uvSource],
                       elements: [element])
}

Generic Data Source

For custom attributes or interleaved data, use the general-purpose initializer:

let data = Data(bytes: vertexData, count: vertexData.count * MemoryLayout<Float>.stride)

let source = SCNGeometrySource(
    data: data,
    semantic: .vertex,
    vectorCount: vertexCount,
    usesFloatComponents: true,
    componentsPerVector: 3,
    bytesPerComponent: MemoryLayout<Float>.stride,
    dataOffset: 0,
    dataStride: MemoryLayout<Float>.stride * 3
)

Updating Geometry Per Frame

For dynamic meshes, recreate geometry sources each frame. Alternatively, use Metal buffers directly for zero-copy updates:

let device = MTLCreateSystemDefaultDevice()!
let buffer = device.makeBuffer(
    bytes: vertices,
    length: vertices.count * MemoryLayout<SIMD3<Float>>.stride,
    options: .storageModeShared
)!

let source = SCNGeometrySource(
    buffer: buffer,
    vertexFormat: .float3,
    semantic: .vertex,
    vertexCount: vertices.count,
    dataOffset: 0,
    dataStride: MemoryLayout<SIMD3<Float>>.stride
)

Primitive Types

Shader Modifiers

Shader modifiers inject GLSL or Metal Shading Language snippets into SceneKit's rendering pipeline at specific entry points.

Entry Points

Vertex Displacement (Geometry Modifier)

let waveShader = """
#pragma arguments
float amplitude;
float frequency;

float wave = amplitude * sin(frequency * _geometry.position.x + u_time);
_geometry.position.y += wave;
"""

material.shaderModifiers = [.geometry: waveShader]
material.setValue(Float(0.2), forKey: "amplitude")
material.setValue(Float(5.0), forKey: "frequency")

Surface Color Modifier

let desatShader = """
float gray = dot(_surface.diffuse.rgb, float3(0.299, 0.587, 0.114));
_surface.diffuse.rgb = mix(_surface.diffuse.rgb, float3(gray), 0.5);
"""

material.shaderModifiers = [.surface: desatShader]

Fragment Modifier

let scanlineShader = """
float line = step(0.5, fract(_surface.position.y * 50.0));
_output.color.rgb *= mix(0.8, 1.0, line);
"""

material.shaderModifiers = [.fragment: scanlineShader]

Passing Values to Shaders

Use setValue(_:forKey:) on the material or geometry. SceneKit matches the key name to #pragma arguments declarations:

material.setValue(NSValue(scnVector3: SCNVector3(1, 0, 0)), forKey: "customDirection")
material.setValue(Float(0.25), forKey: "amplitude")

Shader modifiers receive documented SceneKit uniforms such as u_time, u_modelTransform, u_viewTransform, and u_projectionTransform. scn_frame is for custom SCNProgram Metal shader functions, not shader modifiers.

Node Constraints

Constraints automatically adjust a node's transform each frame.

Look-At Constraint

let lookAt = SCNLookAtConstraint(target: targetNode)
lookAt.isGimbalLockEnabled = true  // Prevent upside-down flipping
cameraNode.constraints = [lookAt]

Distance Constraint

Keep a node within a distance range of another:

let distance = SCNDistanceConstraint(target: targetNode)
distance.minimumDistance = 3
distance.maximumDistance = 10
followerNode.constraints = [distance]

Billboard Constraint

Make a node always face the camera:

let billboard = SCNBillboardConstraint()
billboard.freeAxes = .Y  // Only rotate around Y axis
labelNode.constraints = [billboard]

Replicator Constraint

Copy position/orientation from another node:

let replicator = SCNReplicatorConstraint(target: leaderNode)
replicator.positionOffset = SCNVector3(2, 0, 0)
replicator.replicatesOrientation = true
followerNode.constraints = [replicator]

IK Constraint

Inverse kinematics for skeletal animation:

let ik = SCNIKConstraint.inverseKinematicsConstraint(chainRootNode: shoulderNode)
ik.setMaxAllowedRotationAngle(90, forJoint: elbowNode)
handNode.constraints = [ik]

// Move the target to trigger IK
ik.targetPosition = SCNVector3(1, 2, 0)

Combining Constraints

Constraints are evaluated in order. Use influenceFactor (0-1) to blend:

lookAt.influenceFactor = 0.8
distance.influenceFactor = 1.0
cameraNode.constraints = [lookAt, distance]

Morph Targets

SCNMorpher blends between base geometry and target geometries for facial expressions, shape keys, or procedural deformation.

let morpher = SCNMorpher()

// Target geometries must share the same vertex count and topology
morpher.targets = [smileGeometry, frownGeometry, blinkGeometry]

// Names for programmatic access
morpher.targets[0].name = "smile"
morpher.targets[1].name = "frown"
morpher.targets[2].name = "blink"

node.morpher = morpher

// Set blend weights (0.0 = base, 1.0 = full target shape)
node.morpher?.setWeight(0.5, forTargetAt: 0)          // 50% smile
node.morpher?.setWeight(0.0, forTargetNamed: "frown")  // No frown

Animating Morph Weights

let animation = CABasicAnimation(keyPath: "morpher.weights[0]")
animation.fromValue = 0.0
animation.toValue = 1.0
animation.duration = 0.5
animation.autoreverses = true
node.addAnimation(animation, forKey: "smile")

Morph Calculation Modes

morpher.calculationMode = .additive     // Weights add to base (default)
morpher.calculationMode = .normalized   // Weights normalized to sum to 1

Hit Testing

Determine which nodes a screen point or ray intersects.

Screen-Space Hit Testing

// From a tap gesture
let location = gesture.location(in: sceneView)
let hits = sceneView.hitTest(location, options: [
    .searchMode: SCNHitTestSearchMode.all.rawValue,
    .boundingBoxOnly: false,
    .firstFoundOnly: false
])

if let first = hits.first {
    let node = first.node
    let worldPoint = first.worldCoordinates
    let localPoint = first.localCoordinates
    let normal = first.worldNormal
    let texCoord = first.textureCoordinates(withMappingChannel: 0)
}

Ray-Based Hit Testing

let hits = scene.rootNode.hitTestWithSegment(
    from: SCNVector3(0, 10, 0),
    to: SCNVector3(0, -10, 0),
    options: [
        .searchMode: SCNHitTestSearchMode.closest.rawValue
    ]
)

Hit Test Options

Filtering Hits by Category

let interactableCategory = 1 << 2
node.categoryBitMask = interactableCategory

let hits = sceneView.hitTest(location, options: [
    .categoryBitMask: interactableCategory
])

Scene Serialization

Writing a Scene to File

let scene = SCNScene()
// ... populate scene ...

let url = FileManager.default.temporaryDirectory.appendingPathComponent("scene.scn")
let success = scene.write(to: url, options: nil, delegate: nil) { totalProgress, error, _ in
    print("Export progress: \(totalProgress)")
}

Loading Options and Scene Attributes

Use SCNSceneSource.LoadingOption when importing files that need unit or axis conversion:

let source = SCNSceneSource(url: url, options: nil)!
let scene = try source.scene(options: [
    .checkConsistency: true,
    .convertToYUp: true,
    .convertUnitsToMeters: 1.0
])

Use SCNScene.Attribute only for documented scene metadata such as .startTime, .endTime, .frameRate, and .upAxis.

Archiving Nodes

Individual nodes conform to NSSecureCoding:

let data = try NSKeyedArchiver.archivedData(
    withRootObject: node,
    requiringSecureCoding: true
)

let restored = try NSKeyedUnarchiver.unarchivedObject(
    ofClass: SCNNode.self,
    from: data
)

Render Loop and Delegates

SCNSceneRendererDelegate

Hook into the render loop for per-frame updates:

class GameController: NSObject, SCNSceneRendererDelegate {
    var previousTime: TimeInterval = 0

    func renderer(_ renderer: any SCNSceneRenderer, updateAtTime time: TimeInterval) {
        let deltaTime = time - previousTime
        previousTime = time
        updateGameLogic(deltaTime: deltaTime)
    }

    func renderer(_ renderer: any SCNSceneRenderer, didApplyAnimationsAtTime time: TimeInterval) {
        // After animations are applied, before physics
    }

    func renderer(_ renderer: any SCNSceneRenderer, didSimulatePhysicsAtTime time: TimeInterval) {
        // After physics simulation
    }

    func renderer(_ renderer: any SCNSceneRenderer, willRenderScene scene: SCNScene,
                  atTime time: TimeInterval) {
        // Just before rendering
    }

    func renderer(_ renderer: any SCNSceneRenderer, didRenderScene scene: SCNScene,
                  atTime time: TimeInterval) {
        // After rendering completes
    }
}

sceneView.delegate = gameController

Render Loop Order

1. updateAtTime -- game logic 2. Actions and animations applied 3. didApplyAnimationsAtTime 4. Constraints evaluated 5. didApplyConstraintsAtTime 6. Physics simulation 7. didSimulatePhysicsAtTime 8. willRenderScene 9. GPU render 10. didRenderScene

Frame Rate Control

sceneView.preferredFramesPerSecond = 60
sceneView.isPlaying = true          // Enable continuous rendering
sceneView.rendersContinuously = true // Render even without changes

Performance Optimization

Geometry

• Flatten hierarchies: node.flattenedClone() merges child geometries sharing

the same material into a single draw call.

• Reduce polygon count: Use lower-poly meshes for distant or small objects.
• Share geometry: Assign the same SCNGeometry instance to multiple nodes.
• Level of Detail: Use SCNLevelOfDetail for automatic LOD switching.

Materials

• Share materials: Reuse SCNMaterial instances across geometries.
• Minimize transparent surfaces: Transparency is expensive; use

writesToDepthBuffer and sort render order.

• Use texture atlases: Reduce draw calls by combining textures.
• Avoid unnecessary PBR: Use .lambert or .constant for objects where

lighting detail is not needed.

Lighting and Shadows

• Limit light count: SceneKit processes up to 8 lights per node.
• Use `attenuationEndDistance`: Let SceneKit skip lights for distant nodes.
• Bake static lighting: Use light maps (multiply property) for immovable

environments instead of real-time lights.

• Shadow map size: Smaller shadowMapSize improves performance at the cost

of shadow quality.

Physics

• Simplified shapes: Always use primitive shapes (box, sphere, capsule) for

physics, not mesh-accurate shapes.

• Allow resting: Keep allowsResting = true so static bodies are skipped.
• Disable when off-screen: Set physicsBody = nil for inactive bodies.
• Category masks: Use collision and contact masks to reduce pairwise checks.

Scene Graph

• Minimize node count: Each node has overhead. Use flattenedClone() or

combine meshes in a DCC tool when possible.

• `movabilityHint`: Set .fixed on static objects so SceneKit can optimize

rendering.

• `renderingOrder`: Render opaque objects first (lower values), then

transparent objects.

• Culling: SceneKit frustum-culls automatically. Ensure bounding volumes are

reasonable for effective culling.

Debugging

sceneView.showsStatistics = true  // FPS, draw calls, triangles
sceneView.debugOptions = [
    .showBoundingBoxes,
    .showWireframe,
    .showPhysicsShapes,
    .showLightInfluences,
    .showLightExtents,
    .renderAsWireframe
]

Statistics panel fields:

• fps: Frames per second
• draws: Number of draw calls (target: < 100 for 60 fps)
• tris: Triangle count
• verts: Vertex count

SpriteKit Overlay

Render 2D HUD content on top of the 3D scene using a SpriteKit overlay scene.

import SpriteKit

let overlay = SKScene(size: sceneView.bounds.size)
overlay.scaleMode = .resizeFill

let scoreLabel = SKLabelNode(text: "Score: 0")
scoreLabel.fontName = "Helvetica-Bold"
scoreLabel.fontSize = 24
scoreLabel.position = CGPoint(x: 100, y: overlay.size.height - 50)
overlay.addChild(scoreLabel)

sceneView.overlaySKScene = overlay

Update the overlay from the render loop:

func renderer(_ renderer: any SCNSceneRenderer, updateAtTime time: TimeInterval) {
    DispatchQueue.main.async {
        self.scoreLabel.text = "Score: \(self.score)"
    }
}

SpriteKit Inside 3D Geometry

Render a SpriteKit scene as a material texture:

let spriteScene = SKScene(size: CGSize(width: 512, height: 512))
// ... add SpriteKit nodes ...

let material = SCNMaterial()
material.diffuse.contents = spriteScene
planeNode.geometry?.firstMaterial = material

Level of Detail

SCNLevelOfDetail automatically switches geometry based on distance or screen coverage.

let highDetail = SCNSphere(radius: 1)    // 48 segments
let medDetail = SCNSphere(radius: 1)     // 24 segments
medDetail.segmentCount = 24
let lowDetail = SCNSphere(radius: 1)     // 12 segments
lowDetail.segmentCount = 12

highDetail.levelsOfDetail = [
    SCNLevelOfDetail(geometry: medDetail, screenSpaceRadius: 50),   // < 50px on screen
    SCNLevelOfDetail(geometry: lowDetail, screenSpaceRadius: 20)    // < 20px on screen
]

// Or use world-space distance
highDetail.levelsOfDetail = [
    SCNLevelOfDetail(geometry: medDetail, worldSpaceDistance: 20),
    SCNLevelOfDetail(geometry: lowDetail, worldSpaceDistance: 50)
]

SCNProgram and Metal Shaders

Replace SceneKit's entire rendering pipeline for a geometry with a custom Metal shader program.

let program = SCNProgram()
program.vertexFunctionName = "myVertex"
program.fragmentFunctionName = "myFragment"

// Map SceneKit semantics to shader inputs
program.setSemantic(.modelViewProjectionTransform, forSymbol: "mvpTransform", options: nil)
program.setSemantic(.modelViewTransform, forSymbol: "mvTransform", options: nil)
program.setSemantic(.normalTransform, forSymbol: "normalTransform", options: nil)

material.program = program

Metal shader example:

#include <metal_stdlib>
using namespace metal;
#include <SceneKit/scn_metal>

struct VertexIn {
    float3 position [[attribute(SCNVertexSemanticPosition)]];
    float3 normal   [[attribute(SCNVertexSemanticNormal)]];
    float2 texcoord [[attribute(SCNVertexSemanticTexcoord0)]];
};

struct NodeBuffer {
    float4x4 modelTransform;
    float4x4 normalTransform;
};

struct VertexOut {
    float4 position [[position]];
    float2 texcoord;
    float3 normal;
};

vertex VertexOut myVertex(VertexIn in [[stage_in]],
                          constant SCNSceneBuffer& scn_frame [[buffer(0)]],
                          constant NodeBuffer& scn_node [[buffer(1)]]) {
    VertexOut out;
    out.position = scn_frame.viewProjectionTransform
                   * scn_node.modelTransform
                   * float4(in.position, 1.0);
    out.texcoord = in.texcoord;
    out.normal = (scn_node.normalTransform * float4(in.normal, 0.0)).xyz;
    return out;
}

fragment float4 myFragment(VertexOut in [[stage_in]]) {
    float3 lightDir = normalize(float3(1, 1, 1));
    float diffuse = max(dot(normalize(in.normal), lightDir), 0.0);
    return float4(float3(diffuse), 1.0);
}

Passing Textures to Custom Programs

material.setValue(SCNMaterialProperty(contents: UIImage(named: "texture")!),
                  forKey: "diffuseTexture")

In the shader, declare the texture parameter with a matching name:

fragment float4 myFragment(VertexOut in [[stage_in]],
                           texture2d<float> diffuseTexture [[texture(0)]]) {
    constexpr sampler s(filter::linear);
    float4 color = diffuseTexture.sample(s, in.texcoord);
    return color;
}