SceneKit API Reference & Migration Mapping
Complete API reference for SceneKit with RealityKit equivalents for every major concept.
When to Use This Reference
Use this reference when:
- Looking up SceneKit → RealityKit API equivalents during migration
- Checking specific SceneKit class properties or methods
- Planning which SceneKit features have direct RealityKit counterparts
- Understanding architectural differences between scene graph and ECS
Part 1: SceneKit → RealityKit Concept Mapping
Core Architecture
| SceneKit | RealityKit | Notes |
|---|
SCNScene | RealityViewContent / Entity (root) | RealityKit scenes are entity hierarchies |
SCNNode | Entity | Lightweight container in both |
SCNView | RealityView (SwiftUI) | ARView for UIKit on iOS |
SceneView (SwiftUI) | RealityView | SceneView deprecated iOS 26 |
SCNRenderer | RealityRenderer | Low-level Metal rendering |
| Node properties | Components | ECS separates data from hierarchy |
SCNSceneRendererDelegate | System / SceneEvents.Update | Frame-level updates |
.scn files | .usdz / .usda files | Convert with xcrun scntool |
Geometry & Rendering
| SceneKit | RealityKit | Notes |
|---|
SCNGeometry | MeshResource | RealityKit generates from code or loads USD |
SCNBox, SCNSphere, etc. | MeshResource.generateBox(), .generateSphere() | Similar built-in shapes |
SCNMaterial | SimpleMaterial, PhysicallyBasedMaterial | PBR-first in RealityKit |
SCNMaterial.lightingModel = .physicallyBased | PhysicallyBasedMaterial | Default in RealityKit |
SCNMaterial.diffuse | PhysicallyBasedMaterial.baseColor | Different property name |
SCNMaterial.metalness | PhysicallyBasedMaterial.metallic | Different property name |
SCNMaterial.roughness | PhysicallyBasedMaterial.roughness | Same concept |
SCNMaterial.normal | PhysicallyBasedMaterial.normal | Same concept |
| Shader modifiers | ShaderGraphMaterial / CustomMaterial | No direct port — must rewrite |
SCNProgram (custom shaders) | CustomMaterial with Metal functions | Different API surface |
SCNGeometrySource | MeshResource.Contents | Low-level mesh data |
Transforms & Hierarchy
| SceneKit | RealityKit | Notes |
|---|
node.position | entity.position | Both SCNVector3 / SIMD3 |
node.eulerAngles | entity.orientation (quaternion) | RealityKit prefers quaternions |
node.scale | entity.scale | Both SIMD3 |
node.transform | entity.transform | 4×4 matrix |
node.worldTransform | entity.transform(relativeTo: nil) | World-space transform |
node.addChildNode(_:) | entity.addChild(_:) | Same hierarchy concept |
node.removeFromParentNode() | entity.removeFromParent() | Same concept |
node.childNodes | entity.children | Children collection |
node.parent | entity.parent | Parent reference |
node.childNode(withName:recursively:) | entity.findEntity(named:) | Named lookup |
Lighting
| SceneKit | RealityKit | Notes |
|---|
SCNLight (.omni) | PointLightComponent | Point light |
SCNLight (.directional) | DirectionalLightComponent | Sun/directional light |
SCNLight (.spot) | SpotLightComponent | Cone light |
SCNLight (.area) | No direct equivalent | Use multiple point lights |
SCNLight (.ambient) | EnvironmentResource (IBL) | Image-based lighting preferred |
SCNLight (.probe) | EnvironmentResource | Environment probes |
SCNLight (.IES) | No direct equivalent | Use light intensity profiles |
Camera
| SceneKit | RealityKit | Notes |
|---|
SCNCamera | PerspectiveCamera entity | Entity with camera component |
camera.fieldOfView | PerspectiveCameraComponent.fieldOfViewInDegrees | Same concept |
camera.zNear / camera.zFar | PerspectiveCameraComponent.near / .far | Clipping planes |
camera.wantsDepthOfField | Post-processing effects | Different mechanism |
camera.motionBlurIntensity | Post-processing effects | Different mechanism |
allowsCameraControl | Custom gesture handling | No built-in orbit camera |
Physics
| SceneKit | RealityKit | Notes |
|---|
SCNPhysicsBody | PhysicsBodyComponent | Component-based |
.dynamic | .dynamic | Same mode |
.static | .static | Same mode |
.kinematic | .kinematic | Same mode |
SCNPhysicsShape | CollisionComponent / ShapeResource | Separate from body in RealityKit |
categoryBitMask | CollisionGroup | Named groups vs raw bitmasks |
collisionBitMask | CollisionFilter | Filter-based |
contactTestBitMask | CollisionEvents.Began subscription | Event-based contacts |
SCNPhysicsContactDelegate | scene.subscribe(to: CollisionEvents.Began.self) | Combine-style events |
SCNPhysicsField | PhysicsBodyComponent forces | Apply forces directly |
SCNPhysicsJoint | PhysicsJoint | Similar joint types |
Animation
| SceneKit | RealityKit | Notes |
|---|
SCNAction | entity.move(to:relativeTo:duration:) | Transform animation |
SCNAction.sequence | Animation chaining | Less declarative in RealityKit |
SCNAction.group | Parallel animations | Apply to different entities |
SCNAction.repeatForever | AnimationPlaybackController repeat | Different API |
SCNTransaction (implicit) | No direct equivalent | Explicit animations only |
CAAnimation bridge | entity.playAnimation() | Load from USD |
SCNAnimationPlayer | AnimationPlaybackController | Playback control |
| Morph targets | Blend shapes in USD | Load via USD files |
Interaction
| SceneKit | RealityKit | Notes |
|---|
hitTest(_:options:) | RealityViewContent.entities(at:) | Different API |
| Gesture recognizers on SCNView | ManipulationComponent | Built-in drag/rotate/scale |
allowsCameraControl | Custom implementation | No built-in orbit |
AR Integration
| SceneKit | RealityKit | Notes |
|---|
ARSCNView | RealityView + AnchorEntity | Legacy → modern |
ARSCNViewDelegate | AnchorEntity auto-tracking | Event-driven |
renderer(_:didAdd:for:) | AnchorEntity(.plane) | Declarative anchoring |
ARWorldTrackingConfiguration | SpatialTrackingSession | iOS 18+ |
Part 2: Scene Graph API
SCNScene
// Loading
let scene = SCNScene(named: "scene.usdz")!
let scene = try SCNScene(url: url, options: [
.checkConsistency: true,
.convertToYUp: true
])
// Properties
scene.rootNode // Root of node hierarchy
scene.background.contents // Skybox (UIImage, UIColor, MDLSkyCubeTexture)
scene.lightingEnvironment.contents // IBL environment map
scene.fogStartDistance // Fog near
scene.fogEndDistance // Fog far
scene.fogColor // Fog color
scene.isPaused // Pause simulation
SCNNode
// Creation
let node = SCNNode()
let node = SCNNode(geometry: SCNBox(width: 1, height: 1, length: 1, chamferRadius: 0))
// Transform
node.position = SCNVector3(x, y, z)
node.eulerAngles = SCNVector3(pitch, yaw, roll)
node.scale = SCNVector3(1, 1, 1)
node.simdPosition = SIMD3<Float>(x, y, z) // SIMD variants available
node.pivot = SCNMatrix4MakeTranslation(0, -0.5, 0) // Offset pivot point
// Visibility
node.isHidden = false
node.opacity = 1.0
node.castsShadow = true
node.renderingOrder = 0 // Lower = rendered first
// Hierarchy
node.addChildNode(child)
node.removeFromParentNode()
node.childNodes
node.childNode(withName: "name", recursively: true)
node.enumerateChildNodes { child, stop in }
Part 3: Materials
Lighting Models
| Model | Description | Use Case |
|---|
.physicallyBased | PBR metallic-roughness | Realistic rendering (recommended) |
.blinn | Blinn-Phong specular | Simple shiny surfaces |
.phong | Phong specular | Classic specular highlight |
.lambert | Diffuse only, no specular | Matte surfaces |
.constant | Unlit, flat color | UI elements, debug visualization |
.shadowOnly | Invisible, receives shadows | AR ground plane |
Material Properties
let mat = SCNMaterial()
mat.lightingModel = .physicallyBased
// Textures or scalar values
mat.diffuse.contents = UIImage(named: "albedo") // Base color
mat.metalness.contents = 0.0 // 0 = dielectric, 1 = metal
mat.roughness.contents = 0.5 // 0 = mirror, 1 = rough
mat.normal.contents = UIImage(named: "normal") // Normal map
mat.ambientOcclusion.contents = UIImage(named: "ao") // AO map
mat.emission.contents = UIColor.blue // Glow
mat.displacement.contents = UIImage(named: "height") // Height map
// Options
mat.isDoubleSided = false // Render both sides
mat.writesToDepthBuffer = true
mat.readsFromDepthBuffer = true
mat.blendMode = .alpha // .add, .subtract, .multiply, .screen
mat.transparencyMode = .aOne // .rgbZero for pre-multiplied alpha
Part 4: Physics
Body Types and Properties
// Dynamic body with custom shape
let shape = SCNPhysicsShape(geometry: SCNSphere(radius: 0.5), options: nil)
let body = SCNPhysicsBody(type: .dynamic, shape: shape)
body.mass = 1.0
body.friction = 0.5
body.restitution = 0.3 // Bounciness
body.damping = 0.1 // Linear damping
body.angularDamping = 0.1 // Angular damping
body.isAffectedByGravity = true
body.allowsResting = true // Sleep optimization
node.physicsBody = body
// Compound shapes
let compound = SCNPhysicsShape(shapes: [shape1, shape2],
transforms: [transform1, transform2])
// Concave (static only)
let concave = SCNPhysicsShape(geometry: mesh, options: [
.type: SCNPhysicsShape.ShapeType.concavePolyhedron
])
Joint Types
| Joint | Description |
|---|
SCNPhysicsHingeJoint | Single-axis rotation (door) |
SCNPhysicsBallSocketJoint | Free rotation around point (pendulum) |
SCNPhysicsSliderJoint | Linear movement along axis (drawer) |
SCNPhysicsConeTwistJoint | Limited rotation (ragdoll limb) |
Part 5: Animation API
SCNAction Catalog
| Category | Actions |
|---|
| Movement | move(by:duration:), move(to:duration:) |
| Rotation | rotate(by:around:duration:), rotateTo(x:y:z:duration:) |
| Scale | scale(by:duration:), scale(to:duration:) |
| Fade | fadeIn(duration:), fadeOut(duration:), fadeOpacity(to:duration:) |
| Visibility | hide(), unhide() |
| Audio | playAudio(source:waitForCompletion:) |
| Custom | run { node in }, customAction(duration:action:) |
| Composition | sequence([]), group([]), repeat(_:count:), repeatForever(_:) |
| Control | wait(duration:), removeFromParentNode() |
Timing Functions
action.timingMode = .linear // Default
action.timingMode = .easeIn // Slow start
action.timingMode = .easeOut // Slow end
action.timingMode = .easeInEaseOut // Slow start and end
action.timingFunction = { t in // Custom curve
return t * t // Quadratic ease-in
}
Part 6: Constraints
| Constraint | Purpose |
|---|
SCNLookAtConstraint | Node always faces target |
SCNBillboardConstraint | Node always faces camera |
SCNDistanceConstraint | Maintains min/max distance |
SCNReplicatorConstraint | Copies transform of target |
SCNAccelerationConstraint | Smooths transform changes |
SCNSliderConstraint | Locks to axis |
SCNIKConstraint | Inverse kinematics chain |
let lookAt = SCNLookAtConstraint(target: targetNode)
lookAt.isGimbalLockEnabled = true // Prevent roll
lookAt.influenceFactor = 0.8 // Partial constraint
node.constraints = [lookAt]
In RealityKit: No direct constraint system. Implement with System update logic or entity.look(at:from:relativeTo:).
Part 7: Scene Configuration
SCNView Configuration
| Property | Default | Description |
|---|
antialiasingMode | .multisampling4X | MSAA level |
preferredFramesPerSecond | 60 | Target frame rate |
allowsCameraControl | false | Built-in orbit/pan/zoom |
autoenablesDefaultLighting | false | Add default light if none |
showsStatistics | false | FPS/node/draw count overlay |
isTemporalAntialiasingEnabled | false | TAA smoothing |
isJitteringEnabled | false | Temporal jitter for TAA |
debugOptions | [] | .showPhysicsShapes, .showBoundingBoxes, .renderAsWireframe |
Resources
WWDC: 2014-609, 2014-610, 2017-604, 2019-612
Docs: /scenekit, /scenekit/scnscene, /scenekit/scnnode, /scenekit/scnmaterial, /scenekit/scnphysicsbody, /scenekit/scnaction
Skills: axiom-scenekit, axiom-realitykit, axiom-realitykit-ref
