axiom-scenekit-ref

name	axiom-scenekit-ref
description	SceneKit → RealityKit concept mapping, complete API cross-reference for migration, scene graph API, materials, lighting, camera, physics, animation, constraints
license	MIT
compatibility	["iOS 8+","macOS 10.8+","tvOS 9+"]
metadata	{"version":"1.0.0"}

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