spatial-swiftui-developer_skill

Overview

This skill helps you design and implement visionOS SwiftUI scenes that integrate RealityKit content. It focuses on choosing the right presentation surface, selecting Model3D vs RealityView, and building spatial interactions and lifecycle-safe loading patterns. Readers will get clear patterns for attachments, volumetric windows, and ImmersiveSpace workflows.

How this skill works

The skill inspects presentation needs (window group, volumetric window, or ImmersiveSpace) and recommends the appropriate SwiftUI surface. It guides API choice: use Model3D for simple async model display and RealityView for full RealityKit scenes with per-frame updates. It also describes how to add SwiftUI attachments, handle spatial gestures, and manage async loading and updates inside RealityView closures.

When to use it

• When you need to choose between WindowGroup volumetric windows and ImmersiveSpace for spatial presentation
• When deciding if a 3D asset is best shown with Model3D or requires RealityView/RealityKit systems
• When embedding SwiftUI UI into 3D scenes using RealityView attachments or ViewAttachmentEntity
• When implementing spatial interaction patterns like SpatialTapGesture or entity-targeted gestures
• When managing async model/entity loading and keeping RealityKit mutations off the SwiftUI body

Best practices

• Pick WindowGroup with windowStyle(.volumetric) and set defaultSize for consistent physical scale
• Use Model3D for layout-driven, async-loaded models; use RealityView for custom entity graphs and per-frame updates
• Perform RealityKit entity creation and mutation only inside RealityView make/update closures, not in SwiftUI body
• Use RealityView attachments or ViewAttachmentEntity to keep interactive UI driven by SwiftUI while positioned in 3D
• Avoid synchronous loading on the main actor; load assets asynchronously and surface state safely to SwiftUI
• Prefer .glassBackgroundEffect() for background treatments to match platform visuals

Example use cases

• A product viewer using Model3D for quick loading and SwiftUI controls anchored with attachments
• An interactive scene built with RealityView that updates physics-driven entities per frame
• A volumetric window UI for tools or dashboards opened from WindowGroup with defaultSize set
• An ImmersiveSpace experience that uses immersionStyle and openImmersiveSpace/dismissImmersiveSpace transitions
• Spatial gestures that target entities using SpatialTapGesture and entity hit testing patterns