Scenekit Product Stages Agent Skill

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:

• 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 = .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.

• 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 .shadowOnly catcher 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 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. |

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/gestures-and-haptics.md:

pan-to-grab without hit testing, 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, 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.

Review checklist

Before shipping a stage, verify:

• [ ] backgroundColor = .clear and isOpaque = false on the SCNView; the

stage composites with no visible box or seam.

• [ ] No animation starts on the view's first frame; prepare runs and the

first entrance is delayed or the scene is kept mounted warm.

• [ ] Shadows use forward mode with a .shadowOnly catcher; nothing relies on

deferred shadows, shadowBias, or light categoryBitMask gating.

• [ ] Alpha-textured planes (labels, decals) have castsShadow = false, or

they will cast square shadows.

• [ ] Shadow visibility changes ramp shadowColor alpha; castsShadow is

never toggled at runtime.

• [ ] If the scene must render a texture color-faithfully, ambient plus

directional times cos(incidence) sums to neutral (1000) for a flat

surface; no clipped light grays.

• [ ] Any image on lightingEnvironment (or background) uses a

recognized cube-map layout - 2:1 spherical, 6:1 or 1:6 strip, or six

images; a square image there is silently ignored and reflective

materials render black.

• [ ] Every async continuation (delayed entrances, scheduled haptics, chained

transitions) captures a generation token and re-checks it before acting.

• [ ] Any code that steals an animating node snapshots .presentation values

into the model before calling removeAllAnimations.

• [ ] Baked animations set the model to the final pose before addAnimation;

nothing depends on fillMode = .forwards without a cleanup sweep.

• [ ] Multi-phase beats have a cue sheet comment above the pose function

that matches the phase-boundary struct; phase and cue times live in

that one struct, never as literals in the sample loop or in scheduled

haptics. Every seam is classified: design seams are C1, impulse seams

occur only at contact events and each lands a cue.

• [ ] Rolling objects slave spin to distance divided by radius; nothing slides.
• [ ] Motion copied from a real object is authored as keyframes through a

calibration rig (direct pose controls, saved poses, the owner's eye),

never as a mechanism inferred from photographs.

• [ ] Hand-authored keyframes are parametrized by pose-space distance and

interpolated with span-weighted tangents (or a natural cubic); a dense

sampling passes a numeric max-acceleration-step check before the bake.

• [ ] Looping states drive their phase with a cosine over the state's actual

sweep range (start equals end, zero-velocity reversals) and repeat via

the engine; exits read the current phase from the animation clock and

leave along the same path with duration scaled by remaining travel.

• [ ] Eases on paths that enter or leave the frame keep a nonzero arc-rate

at both edges of the VISIBLE window; a path appended to a resting

actor starts with its tangent dead on the actor's roll axis (actor

length amplifies any first-frame heading snap).

• [ ] Any scripted beat that can meet a live finger uses a bounded,

token-guarded retry, never a single shot behind a silent guard; every

gesture entry point refuses a hidden or unmounted actor before

bumping tokens.

• [ ] When a motion bug is reported, the path is drawn as a ~4pt flat

ribbon (the bake's own points, unlit, depth-test off) BEFORE tuning

anything - and the ribbon is removed once the shape is approved.

• [ ] In a multi-scene sequence: the script clock advances by wall-time

deltas from a static publisher, every cut lands after the outgoing

exit clears the frame, and the next stage pre-mounts parked offstage.

• [ ] Haptics respect the app's haptics preference; motion-driven extras

(gyro parallax, shake) respect Reduce Motion.

• [ ] 60 Hz work (motion callbacks, per-frame updates) stops when the view

leaves the window and restarts on reattach.

• [ ] updateUIView diffs a state key; a pure SwiftUI re-render replays

nothing.

• [ ] The stage's SwiftUI identity is stable: never conditionally present

(hide with opacity), no closure parameters on the representable, and

.id used only as a deliberate remount lever.

• [ ] The stage exists for VoiceOver: one accessibility element with a label

and value, gestures mirrored as adjustable or named actions, and

looping ambient motion removed (not slowed) under Reduce Motion.

• [ ] Textures are capped well under the GPU's texture size limit (16384 px

on modern iPhones, 8192 px on older GPUs) and any texture cache is

released when the stage leaves for good.

• [ ] Generated textures render at format scale 1, sized to the actor's

on-screen projection; live-retargeted textures coalesce to one render

per update pass.

• [ ] The first entrance is gated on prepare's completion handler, not a

fixed delay alone; particle pipelines are warmed (zero-opacity burst,

flags matching the real effect) before their first real frame.

• [ ] Impact particles are alpha-blended, distance-sorted, unlit with a

per-rig flat color, and their emitter shapes never intersect the actor.

• [ ] Haptic generators are prepared and reused per style, never built

inline inside scheduled closures.

• [ ] Any stage animated only by the shader clock sets

rendersContinuously; motion is verified by pixel-diffing two

captures, direction/pace claims by frame-to-frame profile

correlation, not by eye.

• [ ] Every speed-driven shader pattern advances by an accumulated clock

(integral of speed), never by speed * absoluteTime; the speed

eases toward its target and the clock only moves forward.

• [ ] View-angle fades on deformed sheets read wave-tilted normals (the

modifier updates _geometry.normal, not just position), and fold

silhouettes are handled by thickness compensation, not a banded

softstep with a floor.

• [ ] Each motion channel owns its envelope: a calm or taper on one

channel (the wave) never rides a ramp another channel (a swing

bend) depends on.

• [ ] A ported effect's dials are re-blocked for the new camera in screen

space first; every envelope-coupled constant is re-derived from the

new visible run before detail tuning.