/scenekit-game-workflow

name: scenekit-game-workflow
description: Guide SceneKit game implementation, repair, and maintenance. Use when Codex works on SCNScene, SCNView, SCNNode, cameras, lights, materials, geometry, animation, 3D physics, .scn files, .scnassets, model assets, SceneKit and SwiftUI/AppKit/UIKit integration, or RealityKit migration handoffs.

SceneKit Game Workflow

SwiftData And SwiftUI Rule

When a task combines SwiftData with SwiftUI, keep SwiftData directly coupled to SwiftUI through Apple's data-driven path: `modelContainer`, environment `modelContext`, `@Query`, SwiftData model objects, and bindings. Do not add repositories, stores, service layers, DTO mirrors, view-model caches, wrapper objects, or other abstraction layers between SwiftData and SwiftUI. If this skill is not the right owner for SwiftData-backed SwiftUI work, hand off to `apple-dev-skills:swiftui-app-architecture-workflow` instead of inventing an intermediate data layer.

Overview

Use this skill for game-specific SceneKit work after SceneKit has been chosen or when maintaining an existing SceneKit project. Keep generic Apple app lifecycle, project-integrity mechanics, and Swift source cleanup with their owner skills.

Source Check

Use Xcode MCP `DocumentationSearch`, Xcode-local documentation, Dash Apple API Reference docsets, or readable official Apple documentation before making SceneKit-specific claims. Generic no-JS web search/open results, snippets, metadata shells, or bare Apple Developer URLs are not enough evidence that Apple docs were read:

• [SceneKit](https://developer.apple.com/documentation/scenekit)
• [SCNScene](https://developer.apple.com/documentation/scenekit/scnscene)
• [SCNNode](https://developer.apple.com/documentation/scenekit/scnnode)
• [Bringing your SceneKit projects to RealityKit](https://developer.apple.com/documentation/realitykit/bringing-your-scenekit-projects-to-realitykit)

When new work is really modern 3D, spatial, or visionOS game work, consider RealityKit before deepening SceneKit-specific architecture. When maintaining an existing SceneKit project, preserve SceneKit unless the user asks for a migration.

Workflow

1. Inspect the SceneKit surface:

• `import SceneKit`
• `SCNScene`, `SCNView`, `SCNNode`, `SCNCamera`, `SCNLight`, `SCNMaterial`, `SCNGeometry`, `SCNPhysicsWorld`, `SCNPhysicsBody`, animation players, and delegates
• `.scn`, `.scnassets`, `.dae`, `.obj`, `.usdz`, textures, normal maps, environment maps, and animation assets
• host SwiftUI/AppKit/UIKit views and project-resource membership

2. Keep the scene graph readable:

• Name node ownership explicitly.
• Keep camera, lighting, physics, material, and asset-loading changes close to the scene or game subsystem that owns them.
• Avoid opaque node-name lookups for core gameplay unless the existing project already uses them deliberately.

3. Choose migration posture:

• Maintain SceneKit for existing projects when the request is repair, content, performance, or incremental gameplay work.
• Consider RealityKit when the request is new spatial or visionOS-first work, entity-component design, or an explicit SceneKit-to-RealityKit migration.
• Consider Metal only when the work needs custom rendering or shader-level ownership beyond SceneKit's model.

4. Validate honestly:

• Build and run through the repo's Xcode workflow.
• Inspect visual behavior in a running app, simulator, device, screenshot, or recording when possible.
• Use Instruments or `xctrace` handoffs for frame pacing, CPU/GPU timing, memory, or asset-loading performance.

Handoffs

• `choose-apple-game-stack` when SceneKit versus RealityKit versus Metal is still unclear.
• `gameplaykit-simulation-workflow` when entity-component modeling, state machines, pathfinding, agents, randomization, or simulation update order owns the work.
• `xcode-game-profiling-workflow` when SceneKit frame pacing, CPU/GPU overlap, material/asset cost, memory pressure, or trace evidence owns the work.
• `game-controller-input-workflow` for controller, keyboard, mouse, and virtual-controller input.
• `core-haptics-game-feedback-workflow` for haptic feedback.
• `apple-dev-skills:xcode-build-run-workflow` for project membership, schemes, build, run, resources, and simulator mechanics.
• `apple-dev-skills:xcode-testing-workflow` for XCTest, UI tests, Instruments, `xctrace`, and trace interpretation.

Output Shape

Return the SceneKit owner, changed or planned scene/assets, migration posture, validation path, and any manual visual, hardware, or profiling checks still required.