axiom-scenekit_skill

Overview

This skill helps maintain and modernize SceneKit 3D scenes while planning and executing migration to RealityKit. It focuses on scene graph, geometry and materials, physics, animation, SwiftUI bridging, and a practical migration decision tree. Use it to diagnose legacy issues and make clear trade‑off decisions about when to migrate or maintain SceneKit code.

How this skill works

The skill inspects SceneKit concepts and provides mappings to RealityKit equivalents (nodes → entities, materials → PhysicallyBasedMaterial, physics components, and animation APIs). It outlines patterns for scene setup, hit testing, asset pipelines, shader strategies, and SwiftUI integration including UIViewRepresentable fallbacks. It also includes anti‑patterns and a stepwise migration decision tree to guide incremental or full migrations.

When to use it

• Maintaining or debugging an existing SceneKit codebase
• Prototyping quickly with SceneKit while aware of deprecation risks
• Planning or executing migration from SceneKit to RealityKit
• Integrating SceneKit content into SwiftUI via SCNViewRepresentable
• Loading or converting 3D assets (Model I/O, .scn → .usdz conversion)
• Diagnosing rendering, physics, or animation regressions in legacy apps

Best practices

• Prefer RealityKit for all new 3D or AR projects; reserve SceneKit for maintenance only
• Convert .scn assets to USDZ early to reduce migration friction
• Encapsulate SceneKit usage behind adapters or UIViewRepresentable to localize future rewrites
• Avoid heavy investments in SceneKit shader modifiers or custom SCNRenderer pipelines
• Use physics category masks and contact delegates conservatively; map to RealityKit collision and event subscriptions during migration
• Plan incremental migration: new features in RealityKit, stable legacy behavior kept in SceneKit

Example use cases

• Fixing a collision/contact bug in an older SceneKit game without rewriting the renderer
• Converting a library of .scn scene files to .usdz and validating materials before migrating
• Embedding a legacy SCNView into SwiftUI via UIViewRepresentable as an interim step
• Mapping SceneKit animation players and SCNActions to RealityKit animation APIs during phased migration
• Auditing a SceneKit codebase for anti‑patterns that will cause large migration costs