跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add dembsky/PropMotion --skill scenekit-product-stages

技能说明


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 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

TrapFix
Deferred shadows never render when MSAA is on, with zero console errorsUse 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 animationprepare([scene]) in the background, park the actor offstage, delay the first entrance. Never st
阅读完整来源 ↗