Generating interactive geometry with RealityKit

At a glance

Project structure

Source bundle/
└── GeneratingInteractiveGeometry/
    └── GeneratingInteractiveGeometry/
        ├── Compute/
        │   └── ComputeSystem.swift  # ComputeUpdateContext, ComputeSystem, ComputeSystemComponent
        ├── HeightMapMeshView.swift  # HeightMapMeshView, Generator
        ├── GeneratingInteractiveGeometrySampleApp.swift  # GeneratingInteractiveGeometrySampleApp
        ├── HeightMapMesh/
        │   ├── HeightMapGenerator.swift  # HeightMapGenerator
        │   └── HeightMapMesh.swift  # HeightMapComputeParams, HeightMapMesh
        ├── Sine Wave/
        │   └── SineWaveHeightMapGenerator.swift  # SineWaveHeightMapGenerator
        └── Terrain/
            └── TerrainHeightMapGenerator.swift  # TerrainHeightMapGenerator

Structure observations

• The runtime boundary is WindowGroup + volumetric window; the tree is pruned to lifecycle, state, framework, rendering, and ECS files.
• The source is C/Objective-C header, Metal, Swift; role-named types and feature folders separate the major responsibilities.

Overall architecture

flowchart LR
    GeneratingInteractiveGeometrySampleApp_1["GeneratingInteractiveGeometrySampleApp"]
    WindowGroup___volumetric_window_2["WindowGroup + volumetric window"]
    HeightMapMeshView_3["HeightMapMeshView"]
    ComputeSystem_4["ComputeSystem"]
    RealityKit_entity_graph_5["RealityKit entity graph"]
    Metal_compute___RealityKit_geometry_6["Metal compute + RealityKit geometry"]
    GeneratingInteractiveGeometrySampleApp_1 --> WindowGroup___volumetric_window_2
    WindowGroup___volumetric_window_2 --> HeightMapMeshView_3
    HeightMapMeshView_3 --> ComputeSystem_4
    ComputeSystem_4 --> RealityKit_entity_graph_5
    RealityKit_entity_graph_5 --> Metal_compute___RealityKit_geometry_6

Reference code

GeneratingInteractiveGeometry/GeneratingInteractiveGeometry/GeneratingInteractiveGeometrySampleApp.swift:11 — executable or app-lifecycle anchor.

struct GeneratingInteractiveGeometrySampleApp: App {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It separates lifecycle, presentation, stable state, framework/session work, and the RealityKit entity graph.

Ownership and state

classDiagram
    HeightMapMeshView *-- Entity : sceneContainer
    HeightMapMeshView --> HeightMapMeshEntity : heightMapMeshEntity
    HeightMapMeshView *-- Entity : defaultPlaneContainer
    HeightMapMeshView *-- SimpleMaterial : sineWaveMaterial

Ownership evidence

GeneratingInteractiveGeometry/GeneratingInteractiveGeometry/HeightMapMeshView.swift:18 — representative stored state or nearest verified lifecycle anchor.

    private var sceneContainer: Entity = Entity()
    /// The entity that contains the default plane mesh.
    private let defaultPlaneContainer: Entity = Entity()
    /// The height map mesh entity.
    private let heightMapMeshEntity: HeightMapMeshEntity
    
    private let sineWaveMaterial: SimpleMaterial = SimpleMaterial(color: #colorLiteral(red: 0.4666666687, green: 0.7647058964, blue: 0.2666666806, alpha: 1), roughness: 0.85, isMetallic: false)
    private let terrainMaterial: SimpleMaterial = SimpleMaterial(color: #colorLiteral(red: 0.5058823824, green: 0.3372549117, blue: 0.06666667014, alpha: 1), roughness: 0.25, isMetallic: false)

Ownership is intentionally narrow: environment, bindings, observed objects, weak links, and delegate callbacks do not prove lifetime ownership. Initialized stored services and wrapper-managed state do; entities added inside a RealityKit content closure belong to that entity graph.

Class and protocol design

Verified protocol-oriented seams: HeightMapMesh → ComputeSystem, SineWaveHeightMapGenerator → HeightMapGenerator, TerrainHeightMapGenerator → HeightMapGenerator, WaterSurfaceHeightMapGenerator → HeightMapGenerator. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

No reviewed Swift access example uses fileprivate, private(set), public, open; declarations without a modifier are internal.

Objective-C/C header and implementation visibility is documented separately from Swift lexical access control.

Reference code

GeneratingInteractiveGeometry/GeneratingInteractiveGeometry/HeightMapMesh/HeightMap.swift:16 — representative visibility boundary.

@MainActor
struct HeightMap {
    // ...
    private let deriveNormalsPipeline: MTLComputePipelineState = makeComputePipeline(named: "deriveNormalsFromHeightMap")!
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: GeneratingInteractiveGeometrySampleApp; System: ComputeDispatchSystem, ComputeSystem; Component: ComputeSystemComponent; View: HeightMapMeshView.
• ECS names pair data and behavior: components ComputeSystemComponent; systems ComputeDispatchSystem, HeightMapMesh.
• Protocols: ComputeSystem, HeightMapGenerator.
• Commands use verb-led methods: update, setHeightMapGenerator, createScene, reset, generateHeightMap, updateVertices.
• Files and folders use primary-type or responsibility names such as Views, Models, Rendering, Components, Systems, Packages, or feature names where those boundaries exist.

Architecture takeaways

• Treat GeneratingInteractiveGeometrySampleApp as the owner of executable or scene lifecycle, not automatically as the owner of every entity created later.
• Keep view/controller input near presentation, but move sessions, reconstruction, capture, rendering, shared game state, or documents into stable owners when their lifetime exceeds one callback or render pass.
• Use components for per-entity data and systems for repeated simulation instead of centralizing every update in a view model or controller.

Source map

• Official Apple documentation