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 SCNView composites 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:

1. Transparent view flags (backgroundColor = .clear, isOpaque = false), MSAA 4x. The host screen provides the backdrop; the scene has no box.
2. Coordinator owns the node hierarchy, decomposed one node per motion concern (travel, lift, yaw, spin), so independent animations never fight over a single transform.
3. Camera: projectionDirection = .horizontal so 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.
4. 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.
5. Ground contact: a soft dark gradient plane (the contact blob) under the actor plus an invisible .shadowOnly catcher plane for the real shadow.
6. Reflective materials sample a small programmatic environment map, not a photo. Keep the zone behind the camera dark.
7. 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 start an animation on frame one.
fillMode = .forwards + isRemovedOnCompletion = false pins the presentation, and removal is per object	One central clearAnimations that sweeps the node, every child geometry, the lights, and running actions, called from every entry point.
Face-on real metal renders as a gray or black hole	A mirror viewed head-on reflects the environment zone behind the camera. Keep the approved painted base and add a thin additive layer with its own reflection map.
Toggling castsShadow pops a blurred penumbra in one frame; shadowBias and the light's categoryBitMask are ignored for forward directional shadows	Keep castsShadow on permanently and animate shadowColor alpha, synchronized with the motion.
A fixed warm-up delay still hitches on cold devices and the Simulator; a particle effect's first frame compiles its own pipeline and drops exactly when it fires	Two-key ignition: gate the entrance on the minimum delay AND prepare's completion handler. Warm particle pipelines with a zero-opacity burst matching the real effect's flags.
The default UIGraphicsImageRenderer format inherits screen scale, inflating every generated texture 9x in pixels - deadly for textures re-rendered live (per-keystroke engraving)	Pin the renderer format's scale to 1 and size the canvas to the actor's on-screen projection; coalesce multi-input retargets to one render per update pass.
Reproducing a real object's motion from photos yields confident rigs that fail sideways - each fix reveals a new wrong	Stills carry poses, not paths or mechanisms; end-pose fits do not determine the trajectory. Model the path: a calibration rig with direct pose controls, the owner authoring keyframes against the physical object.
A keyframed motion stutters rhythmically at its keyframes and survives every rendering and timing fix	The jerks are baked into the curve: the uniform Catmull-Rom basis on unevenly spaced keyframes steps velocity at every knot. Interpolate with span-weighted Hermite tangents (or a natural cubic) over distance-based phases, and gate on a numeric continuity check.
A sub-mesh cut from a larger model measures as if it were the whole object, with no error anywhere	The cut trimmed only the index buffer; the vertex buffer still holds every vertex of the original. Measure only vertices referenced by the submesh indices.
A square image assigned to scene.lightingEnvironment is silently ignored - zero reflections, every mirror material renders black, no console output	Paint the environment map in a recognized cube-map layout, easiest a 2:1 spherical canvas (1024x512). Only material.reflective accepts a square sphere map.
A scene animated only by the shader clock draws one frame and freezes; two screenshots seconds apart are pixel-identical	The on-demand render loop cannot see shader time: set rendersContinuously = true, and verify motion with a pixel-diff, never by eye.
A speed dial on a shader-time pattern teleports the pattern when snapped - and tweening the dial makes the stream visibly race, or flow BACKWARD when slowing	Phase must be the integral of speed, never speed * absoluteTime: accumulate a clock in the renderer delegate, ease the speed toward its target, and let the clock only advance.
A translucent sheet waved by a geometry modifier prints a bright hairline along every fold silhouette; banded grazing fades either keep the razor or paint straight dark stripes	Modifiers move vertices, not normals: tilt the normal by the wave's analytic slope, then scale alpha by thickness compensation (1+k)*facing/(facing+k) - smooth, zero at tangency, face-on fog untouched.
Chrome lit by a hand-painted environment renders as cartoon metal: one flat paper-white highlight with a hard edge, reflections posterized into gray bands	The painted map's ceiling is 1.0 - there is no dynamic range to roll off. Use a photographic .hdr HDRI passed as a FILE URL (a UIImage re-encode silently clamps it back to LDR) plus wantsHDR on the camera.
lightingEnvironment has no orientation control, and the panorama's frontal lamp prints one big blob dead ahead in the reflection	Rotate the CAMERA RIG instead: with a symmetric actor and radial floor the framing is identical, only the reflection layout moves. Build screen-space gestures rig-aware (lift axes through pointOfView).
A full clearCoat on a white dielectric turns pearl into chrome with a white core; two finishes collapse into one look	clearCoat is a mirror layer. Pearl wants ~0.3-0.4 with roughness ~0.2 - gloss over cream, not silver.
A tap on a shader-deformed actor misses exactly on the bulges - hitTest sees only the undisplaced mesh	Give the actor an oversized invisible collider (colorBufferWriteMask = []), hit-test with .all, filter by node name.
Frozen-clock snapshots that should be identical diff nonzero with no visible difference	Adaptive exposure renders the same instant differently depending on scene history: wantsExposureAdaptation = false, fix exposure by hand.
Particle debris slides forever or never comes to rest, and every friction tweak makes it worse	particleFriction is INVERTED from physical intuition: 1.0 slides freely, 0.0 sticks. A low value (~0.25) is what parks a grain after its last hop.
A surface a mechanic creates at runtime (a cut face, a toppled underside) renders near-black while the rest of the actor looks fine	Faces standing nearly parallel to the view axis graze off the key and the shadow sun. Give the scene a real ambient floor and judge lighting in EVERY orientation the mechanic can produce, not just the authored pose.
A stage is silently empty - no errors, no scene, nothing to debug	A narrowing init (Int32(...)) after 64-bit hash arithmetic traps at runtime, and inside an async task the crash is invisible. Do hash math in the target width via truncatingIfNeeded, and check the system crash reports before debugging scene logic.

Reference map

• references/stage-recipe.md: the full stage, view setup, coordinator, node hierarchy, camera, lighting rig, contact blob and catcher, programmatic environment maps and textures, impact particles on a stage, shader modifiers on stage actors (the linear-space uniform trap), keeping the stage's SwiftUI identity (remount and update-storm traps).
• references/first-frame-and-warmup.md: the Metal pipeline-compile hitch at first draw and both cures, warm-up with a delayed entrance (upgraded to two-key ignition gated on prepare's completion), or keeping the scene mounted warm and retargeting it; particle pipeline warm-up; proving the cure with signposts and on-device hitch traces.
• references/shadows-and-lights.md: every silent shadow trap, the reliable forward + shadowOnly combo, animating shadow visibility, the neutral light budget, face-on metal.
• references/baked-animation.md: why baked keyframes beat timers, the cue sheet for designing multi-phase beats before baking them, seam classification (C1 vs contact impulses), designing weight, dense sampling, cleanup bookkeeping, generation tokens, stealing a node mid-animation, rolling without sliding, rolling along floor paths (steering, screen-space staging, debug trails), channels beyond transforms (morpher weights, lens values, shader uniforms), springs as authoring material, one property one owner.
• references/motion-from-reference.md: reproducing a real object's motion - what stills and video can and cannot tell you, modeling the path instead of the mechanism, the calibration rig (the owner poses the actor and saves keyframes), distance parametrization and span-weighted interpolation of hand-saved poses, the uniform Catmull-Rom trap, numeric continuity gates, seamless cosine state loops with exits from the current phase, measuring trimmed sub-meshes.
• references/physics-without-engine.md: the hand-rolled fixed-step integrator baked to keyframes, walls and floor as plain numbers, contact-driven haptics, a rim-pivot topple, and why this beats SCNPhysics for choreographed scenes.
• references/mesh-surgery.md: cutting an actor apart at runtime - the mesh as plain arrays, a swipe lifted into a cut plane through the camera, triangle clipping into two SEALED halves, the convexity argument that makes the cap trivial, planar cap UVs serving one radial artwork, closed-mesh volume and center-of-mass integrals deciding which piece falls, the support-point fall integrator for an arbitrary chunk, hold-to-aim commit-on-release, scripted cuts that survive re-slicing.
• references/relief-actors.md: die-struck relief objects from CPU heightfields - height and class map painted together (several finishes on one mesh), parabolic feature profiles, the silhouette's three simultaneous guarantees, normals from a blurrier copy of the field, judging flat mirrors front-on and frozen, the narrowing-init hash trap, naming the raster ceiling before polishing toward offline renders.
• references/gestures-and-haptics.md: pan-to-grab without hit testing, the trackball (screen axes lifted to world space through the camera, quaternion composed over authored motion, flick inertia on the stage clock, tap/pan coexistence), soft clamps while held, release velocity, impact haptics, scripted beats surviving live fingers (bounded retries, tokened polls, hidden-actor gesture guards, steal closes the hold contract), Reduce Motion as a taxonomy, VoiceOver access to an invisible stage, coexisting with SwiftUI gestures.
• references/sequencing-stages.md: directing several stages as one film - a master clock with beats as data, wall-time drift traps, cuts on motion after the exit clears, pre-mounting the next stage for warmup, a stage outliving its own cut (lingering smoke), re-basing the timeline on a user interaction, a recording lead, verifying cuts frame by frame.
• references/modeling-actors.md: building believable hero objects from primitives - real-world ratios before eyeballing, annuli for recessed faces, tube-plus-torus silhouettes, radial pattern legibility, per-instance tilt for concave faces, open gaps, relief features as geometry (never paint), satin metal albedo on dark stages, gating actors that arrive as files.
• references/camera-choreography.md: the camera as the performer - the orbit rig, baked reveal flights, focus riding the dolly, drag-orbit with inertia and fly-home, SCNFloor reflections as grounding, matte staging under downlights, constraints for tracking rigs (and why they never go on the actor).
• references/instancing-and-swarms.md: dozens of actors at once - one geometry for the swarm, slot-based piles instead of physics, parabolas solved backward from the landing spot, tumble blended to a rest pose, seeded randomness, stagger by scheduling, destruction bursts (the one place engine particles beat baking, and the determinism exemption that comes with them), budget notes.
• references/fog-and-mist-sheets.md: a continuous vapor stream (vent air, steam, mist) as ONE translucent sheet - geometry-modifier wave plus fragment-modifier fog, domain-warped noise vs stripes, quintic fades vs Mach bands, jittered envelopes, downstream brightness for direction, the integrated phase clock that survives a speed dial, wave-tilted normals and thickness compensation for fold silhouettes, camera-relative dial envelopes, measuring flow direction by profile correlation.
• references/multi-actor-physics.md: several actors in one baked simulation - N state vectors on one clock, pairwise collisions (separate, then exchange when approaching), the freeze-the-world grab, hit-testing which actor the finger picked, per-actor contact lists for squash and haptics.
• references/hdr-environments.md: believable metal - the LDR ceiling behind cartoon highlights, real .hdr HDRIs by file URL (the UIImage clamp trap), wantsHDR with bloom thresholds above 1.0, exposure adaptation vs snapshots, rotating the camera rig because the environment cannot rotate, clearcoat and dark-finish notes, light themes needing dark furniture, purpose-built environments for flat mirrors (finite gaussian cards, never full-sphere rings), classifying the three kinds of lines on chrome, CC0 sourcing and bundling.
• references/deformable-surfaces.md: a closed surface that breathes - fbm displacement on the unit direction, the octave budget separating liquid from rock, finite-difference normal reconstruction (mirror finishes die without it), tap ripples as float4 uniform slots with a travelling front, mesh density vs ring wavelength, the oversized invisible tap collider, amplitude as an animatable KVC dial.
• references/rendering-contract.md: the deterministic stage - one injectable dt-integrated clock owning shader uniforms, node poses, and gesture inertia; the freeze launch hook and back-dated events; the determinism checklist (exposure adaptation, wall clocks, Reduce Motion as pause); the proof kit (motion diff, bit-identical frozen pairs, frozen-clock interaction diff); synthetic CGEvent gestures and their traps (stale window frames, the human in the loop).

Review checklist

Before shipping a stage, verify: