scenekit-product-stages
Build and debug SceneKit scenes where one 3D object (a product, badge, coin, wheel) performs on a transparent stage inside a SwiftUI app - studio lighting, real shadows, baked keyframe choreography, hand-rolled physics, gestures and haptics, multi-scene sequencing. Use when working with SCNView or SceneView in SwiftUI, UIViewRepresentable 3D scenes, product or hero-object animation, roll or spin entrances, a first-frame hitch when a scene appears, shadows missing or wrong, metal rendering black, choreographed 3D motion that must stay interruptible, a continuous vapor stream (vent air, steam, mist) drawn as a shader-driven sheet, a liquid-metal or jelly blob (noise-deformed surface with mirror reflections and tap ripples), chrome or gold that looks cartoon-flat instead of real, HDRI image-based lighting, free trackball rotation of an actor, deterministic screenshot testing of shader-driven scenes, cutting an actor in two with a finger swipe (runtime mesh slicing with sealed cross-sectio
dembsky · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add dembsky/PropMotion --skill scenekit-product-stagesAbout this skill
name: scenekit-product-stages description: Build and debug SceneKit scenes where one 3D object (a product, badge, coin, wheel) performs on a transparent stage inside a SwiftUI app - studio lighting, real shadows, baked keyframe choreography, hand-rolled physics, gestures and haptics, multi-scene sequencing. Use when working with SCNView or SceneView in SwiftUI, UIViewRepresentable 3D scenes, product or hero-object animation, roll or spin entrances, a first-frame hitch when a scene appears, shadows missing or wrong, metal rendering black, choreographed 3D motion that must stay interruptible, a continuous vapor stream (vent air, steam, mist) drawn as a shader-driven sheet, a liquid-metal or jelly blob (noise-deformed surface with mirror reflections and tap ripples), chrome or gold that looks cartoon-flat instead of real, HDRI image-based lighting, free trackball rotation of an actor, deterministic screenshot testing of shader-driven scenes, cutting an actor in two with a finger swipe (runtime mesh slicing with sealed cross-sections and a falling piece), a die-struck relief object (badge, coin, medallion) built from a heightfield with multiple finishes on one mesh, an actor crumbling into debris that falls and rests on the floor, reproducing a real object's motion from photos or video, or keyframed motion that stutters at its own keyframes. Not for RealityKit, ARKit, visionOS, or full game worlds. license: MIT metadata: author: Mateusz Dembek version: 1.9.0
PropMotion
Make one 3D object perform in your SwiftUI app. Production patterns for a specific, common job: a polished product actor on a transparent SceneKit stage - entrances, exits, throws, shadows, haptics, and the silent traps that cost days.
When to use SceneKit at all
Be honest about the framework's position:
- SceneKit is in maintenance mode. For new apps with heavy 3D needs (asset pipelines, USD/USDZ, AR, large worlds) prefer RealityKit.
- SceneKit is still the fastest path to a decorative 3D actor inside a SwiftUI
app: a transparent
SCNViewcomposites over any SwiftUI layout, geometry shader modifiers are a single MSL string, CoreAnimation interop is mature, and everything here runs on plain UIKit views with no session setup. - If the 3D element is one hero object with choreographed motion, this skill's recipes apply directly. If it is a full interactive world, stop and consider RealityKit first.
The core stage recipe
A stage is: transparent SCNView, a @MainActor coordinator that owns the
scene graph, a camera at standing eye height, a three-light rig plus a
dedicated shadow light, a contact blob, and a shadow catcher. The actor
performs via baked keyframe animations.
struct ProductStage: UIViewRepresentable {
let item: Item
// The key must change ONLY when the scene must visibly change.
private var stateKey: String { "\(item.id)" }
func makeCoordinator() -> Coordinator { Coordinator() }
func makeUIView(context: Context) -> SCNView {
let view = SCNView()
view.backgroundColor = .clear // the stage composites over SwiftUI
view.isOpaque = false
view.antialiasingMode = .multisampling4X
view.scene = context.coordinator.buildScene()
view.pointOfView = context.coordinator.cameraNode
context.coordinator.install(item)
context.coordinator.markState(stateKey)
// First-frame warm-up, two-key ignition: compile shaders off
// the critical path, park the actor offstage, and gate the first
// entrance on BOTH a minimum delay and prepare's completion.
context.coordinator.parkOffstage()
if let scene = view.scene {
view.prepare([scene]) { _ in
DispatchQueue.main.async { context.coordinator.markPipelinesWarm() }
}
}
context.coordinator.scheduleFirstEntrance()
return view
}
func updateUIView(_ view: SCNView, context: Context) {
// State-key diffing: SwiftUI re-renders must never replay entrances.
guard context.coordinator.stateKey != stateKey else { return }
context.coordinator.markState(stateKey)
context.coordinator.transition(to: item)
}
}
The pieces, in build order:
- Transparent view flags (
backgroundColor = .clear,isOpaque = false), MSAA 4x. The host screen provides the backdrop; the scene has no box. - Coordinator owns the node hierarchy, decomposed one node per motion concern (travel, lift, yaw, spin), so independent animations never fight over a single transform.
- Camera:
projectionDirection = .horizontalso the actor's size follows stage width; raised position with a slight downward pitch reads like a standing observer. Keep it static; a moving camera reads synthetic. - Lights: warm key, cool low fill, hard rim, ambient only as a floor value, plus a separate shadow-casting directional light aimed from behind-above the actor so it never disturbs the visible sculpt.
- Ground contact: a soft dark gradient plane (the contact blob) under the
actor plus an invisible
.shadowOnlycatcher plane for the real shadow. - Reflective materials sample a small programmatic environment map, not a photo. Keep the zone behind the camera dark.
- All choreography is baked
CAKeyframeAnimation, guarded by generation tokens so any new beat supersedes pending work.
Full detail with code: references/stage-recipe.md
The traps that cost the most time
| Trap | Fix |
|---|---|
| Deferred shadows never render when MSAA is on, with zero console errors | Use shadowMode = .forward plus a .shadowOnly catcher. Debug any missing shadow by first giving the scene a visible gray lambert floor. |
The first frame of a fresh SCNView compiles Metal pipelines in the middle of your entrance animation | prepare([scene]) in the background, park the actor offstage, delay the first entrance. Never st |