A wrapper around ShaderGraphMaterial(named:from:in:) with helpful comments about unrecognized shader graph properties for "Error 1"

ShaderGraphMaterial+LoadFileAsync.swift

//
//  ShaderGraphMaterial+LoadFileAsync.swift
//
//  Created by Drew Olbrich on 5/14/25.
//  Copyright © 2025 Lunar Skydiving LLC. All rights reserved.
//
//  MIT License
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in all
//  copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
//

import Foundation
import RealityKit

extension ShaderGraphMaterial {
    
    /// A wrapper around `ShaderGraphMaterial(named:from:in:)` that fails an assertion
    /// when the material doesn't exist in the file, or when RealityKit encounters a
    /// shader graph node property it does not recognize, with extensive comments that
    /// may help you through this trying experience.
    ///    
    /// Don't use `ShaderGraphMaterial(named:from:in:)`. To avoid hours of pain and
    /// frustration, use `ShaderGraphMaterial.loadFileAsync(named:from:in:)` instead.
    ///
    /// ## Usage
    /// ```
    /// let material = try await
    ///     ShaderGraphMaterial.loadFileAsync(
    ///     named: "/Root/MyMaterial", from: "MyFile")
    /// ```
    static func loadFileAsync(named name: String, from file: String, in bundle: Bundle? = nil) async throws -> ShaderGraphMaterial {
        do {
            return try await ShaderGraphMaterial(named: name, from: file, in: bundle)
        } catch {
            if case ShaderGraphMaterial.LoadError.materialNameNotFound = error {
                // If you see the error below in the console, it may mean that one of the USD
                // material's shader graph nodes has a property that RealityKit does not recognize.
                //
                //     The operation couldn’t be completed. (RealityFoundation.ShaderGraphMaterial.LoadError error 1.)
                //
                // This can happen if a newer version of Reality Composer Pro was used to edit a
                // shader graph which was later read by an older version of RealityKit that does
                // not recognize newer USD shader graph node properties that were introduced
                // by the new Reality Composer Pro in the future.
                //
                // In short, RealityKit is not forward-compatible with respect to reading shader
                // graph materials. RealityKit silently assumes that if your project uses shader
                // graph materials and builds against visionOS or iOS version N, you'll also drop
                // support for visionOS or iOS version N-1.
                // (FB14828873)
                //
                // Another reason this could happen is that you attempted to use an AI to generate
                // a USDA file containing a shader graph, and the AI hallucinated a shader graph
                // node property that doesn't exist.
                //
                // Or, perhaps your shader graph has simply become corrupt in some other way,
                // or there's a bug in Reality Composer Pro.
                //
                // Unfortunately, RealityKit does not appear to provide specific context describing
                // the specific source of the error. It says only "The operation couldn’t be
                // completed." It's up to you to track down the specific source of the error.
                //
                // One approach is to use Reality Composer Pro to systematically delete nodes from
                // the shader graph through a manual binary search. Once you've discovered the
                // offending node, you can remove its properties from the file by hand with a text
                // editor until you discover the one that RealityKit doesn't recognize.
                //
                // So far, it is known that this a problem with RealityKit in iOS 18, and
                // visionOS 1 and 2.
                assertionFailure("Cannot load shader graph material '\(name)' from USD file '\(file)', either because a shader graph material with that name was not found in the file, or possibly because a node property in the shader graph is not supported by this version of RealityKit: \(error.localizedDescription)")
            }
            throw error
        }
    }

}