SceneKit
Maintain existing SceneKit scenes only. Apple deprecated SceneKit at WWDC 2025 and limits it to maintenance; route new projects, major modernization, and USD/USDZ pipelines to RealityKit. Existing apps continue to work.
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
allowsCameraControl adds built-in orbit, pan, and zoom gestures. Typically
disabled in production where custom camera control is needed.
Creating an SCNScene
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.
Transforms
Built-in Primitives
SCNBox, SCNSphere, SCNCylinder, SCNCone, SCNTorus, SCNCapsule,
SCNTube, SCNPlane, SCNFloor, SCNText, SCNShape (extruded Bezier path).
Finding Nodes
Materials
SCNMaterial defines surface appearance. Use firstMaterial for single-material
geometries or the materials array for multi-material.
Color and Texture
Physically Based Rendering (PBR)
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
Lighting
Attach an SCNLight to a node. The light's direction follows the node's
negative Z-axis.
Light Types
Attach to a node:
Shadows
Category Bit Masks
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.
Configuration
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.
SCNTransaction (Implicit Animation)
Explicit Animations (Core Animation)
Physics
Physics Bodies
When shape is nil, SceneKit derives it from geometry. For performance, use
simplified shapes:
Applying Forces
Collision Detection
Gravity
Particle Systems
SCNParticleSystem creates effects like fire, smoke, rain, and sparks.
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.
Use this as an authoring/import gate: stop on a consistency or required-node
failure, fix the source asset or import options, then repeat the same check.
For generated .scn files, load
Scene Serialization [blocked] and
require both export success and a checked reload before commit.
Use SCNReferenceNode with .onDemand loading policy for large models. For
import-time unit conversion, use SCNSceneSource.LoadingOption:
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:
Options: .allowsCameraControl, .autoenablesDefaultLighting,
.jitteringEnabled, .temporalAntialiasingEnabled.
For render loop control, wrap SCNView in UIViewRepresentable with an
SCNSceneRendererDelegate coordinator. See references/scenekit-patterns.md [blocked].
Common Mistakes
Not adding a camera or lights
Using exact geometry for physics shapes
Modifying transforms on dynamic bodies
Review Checklist
- Scene has at least one camera node set as
pointOfView - Scene has appropriate lighting (or
autoenablesDefaultLightingfor prototyping) - Physics shapes use simplified geometry, not full mesh detail
-
contactTestBitMaskset for bodies that need collision callbacks -
SCNPhysicsContactDelegateassigned toscene.physicsWorld.contactDelegate - Dynamic body transforms changed via forces/impulses, not direct position
- Lights limited to 8 per node;
attenuationEndDistanceset on point/spot lights - Materials use
.physicallyBasedlighting model for realistic rendering - SceneKit assets use documented
.scn,.dae, or.abcscene-source formats - Imported and exported assets pass consistency and required-node checks before commit
- 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
-
SCNReferenceNodeused for large models to enable lazy loading - Particle
birthRateandparticleLifeSpanbalanced to control particle count -
categoryBitMaskused to scope lights and cameras to relevant nodes - SwiftUI scenes use
SceneVieworUIViewRepresentable-wrappedSCNView - Deprecation acknowledged; RealityKit evaluated for new projects
References
- See references/scenekit-patterns.md [blocked] 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
