Scenekit

作者 dpearson26998d90fd121a26無授權條款1.1K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫2 個月前更新

Maintain and extend existing SceneKit 3D scenes and visualizations. Use when working with SCNView, SCNScene, SCNNode scene graphs, SceneKit geometry/materials/lights/cameras, SCNAction animation, SCNPhysicsBody physics, SCNParticleSystem effects, .scn/.dae/.abc SceneKit assets, shader modifiers, or SwiftUI SceneView. SceneKit is soft-deprecated and in maintenance mode; route new apps, significant updates, USD/USDZ pipelines, and migration planning toward RealityKit.

僅含說明Software Development
AI 產生的概覽

指導維護與擴充現有 SceneKit 3D 場景，並建議將新專案轉向 RealityKit。

功能
此技能為現有 SceneKit 3D 場景提供參考指引，涵蓋 SCNView 與 SCNScene 設定、節點圖、幾何、材質、燈光、相機、動畫、物理、粒子系統、資源載入以及 SwiftUI SceneView 整合。內容包含程式碼範例、常見錯誤與審查清單，並建議將新專案、重大更新與 USD/USDZ 流程轉向 RealityKit。產出為指引說明與程式碼範例，而非檔案或指令碼。
適用情境
適用於維護或擴充現有 SceneKit 場景時，例如調整節點、材質、燈光、相機、動畫、物理或粒子。也適合在審查 SceneKit 程式碼，或判斷相關工作是否應改用 RealityKit 時使用。
執行需求
沒有指令碼，僅為說明性指引。鎖定 Apple 平台，假定使用 Swift、SceneKit，可能還涉及 SwiftUI 或 UIKit，並需要 .scn、.dae 或 .abc 等 SceneKit 資源檔案。

SceneKit

Maintain existing SceneKit scenes only. Apple deprecated SceneKit at WWDC 2025 and limits it to maintenance; route new projects, major modernization, and USD/USDZ pipelines to RealityKit. Existing apps continue to work.

Contents

Scene Setup

SCNView in UIKit

swift
import SceneKit
let sceneView = SCNView(frame: view.bounds)sceneView.scene = SCNScene()sceneView.allowsCameraControl = truesceneView.autoenablesDefaultLighting = truesceneView.backgroundColor = .blackview.addSubview(sceneView)

allowsCameraControl adds built-in orbit, pan, and zoom gestures. Typically disabled in production where custom camera control is needed.

Creating an SCNScene

swift
let scene = SCNScene()                                          // Emptyguard let scene = SCNScene(named: "art.scnassets/ship.scn")     // .scn in .scnassets    else { fatalError("Missing scene asset") }let url = Bundle.main.url(forResource: "ship", withExtension: "dae")!let scene = try SCNScene(url: url, options: [.checkConsistency: true])

Nodes and Geometry

Every scene has a rootNode. All content exists as descendant nodes. Nodes define position, orientation, and scale in their parent's coordinate system. SceneKit uses a right-handed coordinate system: +X right, +Y up, +Z toward the camera.

swift
let parentNode = SCNNode()scene.rootNode.addChildNode(parentNode)
let childNode = SCNNode()childNode.position = SCNVector3(0, 1, 0)  // 1 unit above parentparentNode.addChildNode(childNode)

Transforms

swift
node.position = SCNVector3(x: 0, y: 2, z: -5)node.eulerAngles = SCNVector3(x: 0, y: .pi / 4, z: 0)  // 45-degree Y rotationnode.scale = SCNVector3(2, 2, 2)node.simdPosition = SIMD3<Float>(0, 2, -5)  // Prefer simd for performance

Built-in Primitives

SCNBox, SCNSphere, SCNCylinder, SCNCone, SCNTorus, SCNCapsule, SCNTube, SCNPlane, SCNFloor, SCNText, SCNShape (extruded Bezier path).

swift
let node = SCNNode(geometry: SCNSphere(radius: 0.5))

Finding Nodes

swift
let maxNode = scene.rootNode.childNode(withName: "Max", recursively: true)let enemies = scene.rootNode.childNodes { node, _ in    node.name?.hasPrefix("enemy") == true}

Materials

SCNMaterial defines surface appearance. Use firstMaterial for single-material geometries or the materials array for multi-material.

Color and Texture

swift
let material = SCNMaterial()material.diffuse.contents = UIColor.systemBlue     // Solid colormaterial.diffuse.contents = UIImage(named: "brick") // Texturematerial.normal.contents = UIImage(named: "brick_normal")sphere.firstMaterial = material

Physically Based Rendering (PBR)

swift
let pbr = SCNMaterial()pbr.lightingModel = .physicallyBasedpbr.diffuse.contents = UIImage(named: "albedo")pbr.metalness.contents = 0.8       // Scalar or texturepbr.roughness.contents = 0.2       // Scalar or texturepbr.normal.contents = UIImage(named: "normal")pbr.ambientOcclusion.contents = UIImage(named: "ao")

Lighting Models

.physicallyBased (metalness/roughness), .blinn (default), .phong, .lambert (diffuse-only), .constant (unlit), .shadowOnly.

Each material property is an SCNMaterialProperty accepting UIColor, UIImage, CGFloat scalar, SKTexture, CALayer, or AVPlayer.

Transparency

swift
material.transparency = 0.5material.transparencyMode = .dualLayermaterial.isDoubleSided = true

Lighting

Attach an SCNLight to a node. The light's direction follows the node's negative Z-axis.

Light Types

swift
// Ambient: uniform, no directionlet ambient = SCNLight()ambient.type = .ambientambient.color = UIColor(white: 0.3, alpha: 1)
// Directional: parallel rays (sunlight)let directional = SCNLight()directional.type = .directionaldirectional.castsShadow = true
// Omni: point light, all directionslet omni = SCNLight()omni.type = .omniomni.attenuationEndDistance = 20
// Spot: cone-shapedlet spot = SCNLight()spot.type = .spotspot.spotInnerAngle = 20spot.spotOuterAngle = 60

Attach to a node:

swift
let lightNode = SCNNode()lightNode.light = directionallightNode.eulerAngles = SCNVector3(-Float.pi / 3, 0, 0)lightNode.position = SCNVector3(0, 10, 10)scene.rootNode.addChildNode(lightNode)

Shadows

swift
light.castsShadow = truelight.shadowMapSize = CGSize(width: 2048, height: 2048)light.shadowSampleCount = 8light.shadowRadius = 3.0light.shadowColor = UIColor(white: 0, alpha: 0.5)

Category Bit Masks

swift
light.categoryBitMask = 1 << 1     // Category 2node.categoryBitMask = 1 << 1      // Only lit by category-2 lights

SceneKit renders a maximum of 8 lights per node. Use attenuationEndDistance on point/spot lights so SceneKit skips them for distant nodes.

Cameras

Attach an SCNCamera to a node to define a viewpoint.

swift
let cameraNode = SCNNode()cameraNode.camera = SCNCamera()cameraNode.position = SCNVector3(0, 5, 15)cameraNode.look(at: SCNVector3Zero)scene.rootNode.addChildNode(cameraNode)sceneView.pointOfView = cameraNode

Configuration

swift
camera.fieldOfView = 60                        // Degreescamera.zNear = 0.1camera.zFar = 500camera.automaticallyAdjustsZRange = true
// Orthographiccamera.usesOrthographicProjection = truecamera.orthographicScale = 10

Depth-of-field (wantsDepthOfField, focusDistance, fStop) and HDR effects (wantsHDR, bloomIntensity, bloomThreshold, screenSpaceAmbientOcclusionIntensity) are configured directly on SCNCamera.

Animation

SceneKit provides three animation approaches.

SCNAction (Declarative, Game-Oriented)

Reusable, composable animation objects attached to nodes.

swift
let move = SCNAction.move(by: SCNVector3(0, 2, 0), duration: 1)let rotate = SCNAction.rotateBy(x: 0, y: .pi, z: 0, duration: 1)node.runAction(.group([move, rotate]))
// Sequentialnode.runAction(.sequence([.fadeOut(duration: 0.3), .removeFromParentNode()]))
// Infinite looplet pulse = SCNAction.sequence([    .scale(to: 1.2, duration: 0.5),    .scale(to: 1.0, duration: 0.5)])node.runAction(.repeatForever(pulse))

SCNTransaction (Implicit Animation)

swift
SCNTransaction.begin()SCNTransaction.animationDuration = 1.0node.position = SCNVector3(5, 0, 0)node.opacity = 0.5SCNTransaction.completionBlock = { print("Done") }SCNTransaction.commit()

Explicit Animations (Core Animation)

swift
let animation = CABasicAnimation(keyPath: "rotation")animation.toValue = NSValue(scnVector4: SCNVector4(0, 1, 0, Float.pi * 2))animation.duration = 2animation.repeatCount = .infinitynode.addAnimation(animation, forKey: "spin")

Physics

Physics Bodies

swift
node.physicsBody = SCNPhysicsBody(type: .dynamic, shape: nil)   // Forces + collisionsfloor.physicsBody = SCNPhysicsBody(type: .static, shape: nil)    // Immovableplatform.physicsBody = SCNPhysicsBody(type: .kinematic, shape: nil) // Code-driven

When shape is nil, SceneKit derives it from geometry. For performance, use simplified shapes:

swift
let shape = SCNPhysicsShape(    geometry: SCNBox(width: 1, height: 2, length: 1, chamferRadius: 0),    options: nil)node.physicsBody = SCNPhysicsBody(type: .dynamic, shape: shape)node.physicsBody?.mass = 2.0node.physicsBody?.restitution = 0.3

Applying Forces

swift
node.physicsBody?.applyForce(SCNVector3(0, 10, 0), asImpulse: false) // Continuousnode.physicsBody?.applyForce(SCNVector3(0, 5, 0), asImpulse: true)   // Instantnode.physicsBody?.applyTorque(SCNVector4(0, 1, 0, 2), asImpulse: true)

Collision Detection

swift
struct PhysicsCategory {    static let player:     Int = 1 << 0    static let enemy:      Int = 1 << 1    static let ground:     Int = 1 << 2}
playerNode.physicsBody?.categoryBitMask = PhysicsCategory.playerplayerNode.physicsBody?.collisionBitMask = PhysicsCategory.ground | PhysicsCategory.enemyplayerNode.physicsBody?.contactTestBitMask = PhysicsCategory.enemy
scene.physicsWorld.contactDelegate = self
func physicsWorld(_ world: SCNPhysicsWorld, didBegin contact: SCNPhysicsContact) {    handleCollision(between: contact.nodeA, and: contact.nodeB)}

Gravity

swift
scene.physicsWorld.gravity = SCNVector3(0, -9.8, 0)node.physicsBody?.isAffectedByGravity = false

Particle Systems

SCNParticleSystem creates effects like fire, smoke, rain, and sparks.

swift
let particles = SCNParticleSystem()particles.birthRate = 100particles.particleLifeSpan = 2particles.particleSize = 0.1particles.particleColor = .orangeparticles.emitterShape = SCNSphere(radius: 0.5)particles.particleVelocity = 2particles.isAffectedByGravity = trueparticles.blendMode = .additive
let emitterNode = SCNNode()emitterNode.addParticleSystem(particles)scene.rootNode.addChildNode(emitterNode)

Load from Xcode particle editor with SCNParticleSystem(named: "fire.scnp", inDirectory: nil). Particles can collide with geometry via colliderNodes.

Loading Models

SceneKit's documented scene-source formats are .scn, .dae, and .abc. For bundled assets, place scene files in a .scnassets folder and texture images in asset catalogs so Xcode can optimize them for target devices.

USD/USDZ is the RealityKit migration path, not the default SceneKit loading path. For new projects, significant updates, or SCN-to-USD asset conversion, handoff to the RealityKit skill.

swift
enum SceneAssetError: Error { case missingResource, missingNode(String) }
func loadCheckedScene() throws -> SCNScene {    guard let url = Bundle.main.url(forResource: "model", withExtension: "dae")    else { throw SceneAssetError.missingResource }
    let scene = try SCNScene(url: url, options: [.checkConsistency: true])    guard scene.rootNode.childNode(withName: "mesh", recursively: true) != nil    else { throw SceneAssetError.missingNode("mesh") }    return scene}

Use this as an authoring/import gate: stop on a consistency or required-node failure, fix the source asset or import options, then repeat the same check. For generated .scn files, load Scene Serialization [blocked] and require both export success and a checked reload before commit.

Use SCNReferenceNode with .onDemand loading policy for large models. For import-time unit conversion, use SCNSceneSource.LoadingOption:

swift
let source = SCNSceneSource(url: url, options: nil)!let scene = try source.scene(options: [.convertUnitsToMeters: 1.0])

Do not use SCNScene.Attribute.unit or UnitMetersPerUnit. SCNScene.Attribute is metadata only: .startTime, .endTime, .frameRate, and .upAxis.

SwiftUI Integration

SceneView embeds SceneKit in SwiftUI:

swift
import SwiftUIimport SceneKit
struct SceneKitView: View {    let scene: SCNScene = {        let scene = SCNScene()        let sphere = SCNNode(geometry: SCNSphere(radius: 1))        sphere.geometry?.firstMaterial?.lightingModel = .physicallyBased        sphere.geometry?.firstMaterial?.diffuse.contents = UIColor.systemBlue        sphere.geometry?.firstMaterial?.metalness.contents = 0.8        scene.rootNode.addChildNode(sphere)        return scene    }()
    var body: some View {        SceneView(scene: scene,                  options: [.allowsCameraControl, .autoenablesDefaultLighting])    }}

Options: .allowsCameraControl, .autoenablesDefaultLighting, .jitteringEnabled, .temporalAntialiasingEnabled.

For render loop control, wrap SCNView in UIViewRepresentable with an SCNSceneRendererDelegate coordinator. See references/scenekit-patterns.md [blocked].

Common Mistakes

Not adding a camera or lights

swift
// DON'T: Scene renders blank or black -- no camera, no lightssceneView.scene = scene
// DO: Add camera + lights, or use convenience flagslet cameraNode = SCNNode()cameraNode.camera = SCNCamera()cameraNode.position = SCNVector3(0, 5, 15)scene.rootNode.addChildNode(cameraNode)sceneView.pointOfView = cameraNodesceneView.autoenablesDefaultLighting = true

Using exact geometry for physics shapes

swift
// DON'Tnode.physicsBody = SCNPhysicsBody(type: .dynamic,    shape: SCNPhysicsShape(geometry: complexMesh, options: nil))
// DO: Simplified primitivenode.physicsBody = SCNPhysicsBody(type: .dynamic,    shape: SCNPhysicsShape(        geometry: SCNBox(width: 1, height: 2, length: 1, chamferRadius: 0),        options: nil))

Modifying transforms on dynamic bodies

swift
// DON'T: Resets physics simulationdynamicNode.position = SCNVector3(5, 0, 0)
// DO: Use forces/impulsesdynamicNode.physicsBody?.applyForce(SCNVector3(10, 0, 0), asImpulse: true)

Review Checklist

  • Scene has at least one camera node set as pointOfView
  • Scene has appropriate lighting (or autoenablesDefaultLighting for prototyping)
  • Physics shapes use simplified geometry, not full mesh detail
  • contactTestBitMask set for bodies that need collision callbacks
  • SCNPhysicsContactDelegate assigned to scene.physicsWorld.contactDelegate
  • Dynamic body transforms changed via forces/impulses, not direct position
  • Lights limited to 8 per node; attenuationEndDistance set on point/spot lights
  • Materials use .physicallyBased lighting model for realistic rendering
  • SceneKit assets use documented .scn, .dae, or .abc scene-source formats
  • Imported and exported assets pass consistency and required-node checks before commit
  • Bundled SceneKit textures/images use asset catalogs or Xcode-optimized resources
  • Scene metadata/import options use documented API; no invented SCNScene.Attribute.unit
  • New USD/USDZ pipelines or significant updates are routed to RealityKit
  • Game Center authentication, leaderboards, achievements, or multiplayer are handed off to GameKit
  • SCNReferenceNode used for large models to enable lazy loading
  • Particle birthRate and particleLifeSpan balanced to control particle count
  • categoryBitMask used to scope lights and cameras to relevant nodes
  • SwiftUI scenes use SceneView or UIViewRepresentable-wrapped SCNView
  • Deprecation acknowledged; RealityKit evaluated for new projects

References

來源與署名

來源：dpearson2699/swift-ios-skills位於skills/scenekit提交8d90fd1

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 dpearson2699/swift-ios-skills 的技能

Widgetkit

dpearson2699

指導實作、審查與改進 iOS、iPadOS、watchOS 與 CarPlay 上的 WidgetKit 小工具與控制項。

Software Development1.1K2 個月前更新

Weatherkit

dpearson2699

指導 iOS 開發者使用 WeatherService 取得 WeatherKit 預報、警報與署名資訊。

Software Development1.1K2 個月前更新

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

待分類1.1K2 個月前更新

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

待分類1.1K2 個月前更新

Tabletopkit

dpearson2699

指導使用 TabletopKit 在 visionOS 上打造多人空間桌遊，涵蓋棋具、座位、動作與 RealityKit 算繪。

Software Development1.1K2 個月前更新

Swiftui Webkit

dpearson2699

指導在 iOS 26 及更新版本的 SwiftUI App 中使用 WebKit for SwiftUI 嵌入與控制網頁內容。

Software Development1.1K2 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新