Reality Composer Pro自定义组件实时预览不生效问题求助

问题描述 #

我正在开发一款visionOS应用，为Reality Composer Pro创建自定义组件BinOpenerComponent，其中包含opacity字段。目前在Vision Pro设备上修改该字段值能正确应用实体透明度，但在Reality Composer Pro预览中无法实时看到更新效果。现有代码中已实现OpacitySystem，但未生效。

现有代码：

public struct BinOpenerComponent: Component, Codable {
    var dragAxis: DragAxis
    public var canDrag: Bool = true
    public var opacity: Float = 1.0
    public var objectReferenceName: String? = "Enter name"
    
    // Define min and max translation values per axis
    public var minTranslation: Float = 0
    public var maxTranslation: Float = 0

    public init(dragAxis: DragAxis = .x,
                minTranslation: Float = 0.0,
                maxTranslation: Float = 0.4,
                opacity: Float = 1.0,
                objectReferenceName: String = "Enter name") {
        self.dragAxis = dragAxis
        self.minTranslation = minTranslation
        self.maxTranslation = maxTranslation
        self.opacity = opacity
        self.objectReferenceName = objectReferenceName
    }
    
    // MARK: - Drag Logic
    
    /// Handle `.onChanged` actions for drag gestures.
    mutating func onChanged(value: EntityTargetValue<DragGesture.Value>) {
        guard canDrag else { return }
        
        let state = EntityGestureState.shared
        
        // Only allow a single Entity to be targeted at any given time.
        if state.targetedEntity == nil {
            state.targetedEntity = value.entity
            state.initialOrientation = value.entity.orientation(relativeTo: nil)
        }

        handleFixedDrag(value: value) { currentTranslation in
            DispatchQueue.main.async {
                state.currentTranslation = currentTranslation
            }
        }
    }
    
    mutating private func handleFixedDrag(value: EntityTargetValue<DragGesture.Value>, onChange: ((SIMD3<Float>) -> Void)? = nil) {
        let state = EntityGestureState.shared
        guard let entity = state.targetedEntity else { fatalError("Gesture contained no entity") }
        
        if !state.isDragging {
            state.isDragging = true
            state.dragStartPosition = entity.position(relativeTo: nil) // Use world position as reference
        }
        
        // Convert the gesture translation to the scene's coordinate space
        let translation3D = value.convert(value.gestureValue.translation3D, from: .local, to: .scene)
        
        // Determine which axis to apply the translation
        var desiredTranslation = state.dragStartPosition
        switch dragAxis {
        case .x:
            desiredTranslation.x += translation3D.x
            desiredTranslation.x = clamp(desiredTranslation.x, min: minTranslation, max: maxTranslation)
        case .y:
            desiredTranslation.y += translation3D.y
            desiredTranslation.y = clamp(desiredTranslation.y, min: minTranslation, max: maxTranslation)
        case .z:
            desiredTranslation.z += translation3D.z
            desiredTranslation.z = clamp(desiredTranslation.z, min: minTranslation, max: maxTranslation)
        }
        
        // Create the new position with clamped translation
        let offset = desiredTranslation
        
        // Apply the clamped position
        entity.setPosition(offset, relativeTo: nil)
        
        // Optionally, notify about the change
        onChange?(offset)
        
        // Restore the initial orientation if needed
        if let initialOrientation = state.initialOrientation {
            entity.setOrientation(initialOrientation, relativeTo: nil)
        }
        
        // Apply opacity whenever dragging occurs
        //applyOpacity(to: entity)
    }
    
    /// Handle `.onEnded` actions for drag gestures.
    mutating func onEnded(value: EntityTargetValue<DragGesture.Value>) {
        let state = EntityGestureState.shared
        state.isDragging = false
        
        state.pivotEntity = nil
        state.targetedEntity = nil
    }
    
    /// Helper function to clamp a value within a range
    private func clamp(_ value: Float, min: Float, max: Float) -> Float {
        return Swift.max(min, Swift.min(value, max))
    }
    
    // MARK: - Opacity Logic

    /// Apply the current opacity to the entity's materials.
    func applyOpacity(to entity: Entity) {
        guard let modelEntity = entity as? ModelEntity else { return }
        
        let opacityComponent = OpacityComponent(opacity: opacity)
        modelEntity.components.set(opacityComponent)
    }
}

extension Entity {
    var binOpenerComponent: BinOpenerComponent? {
        get { components[BinOpenerComponent.self] }
        set { components[BinOpenerComponent.self] = newValue }
    }
}

public class OpacitySystem: System {
    
    // Specify that this system processes entities with BinOpenerComponent
    static let query = EntityQuery(where: .has(RealityKitContent.BinOpenerComponent.self))

    required public init(scene: RealityKit.Scene) {}

    /// Called every frame to update entities.
    public func update(context: SceneUpdateContext) {
        let entities = context.scene.performQuery(Self.query).map({ $0 })
        
        for entity in entities {
            guard let binOpener = entity.binOpenerComponent else { continue }
            binOpener.applyOpacity(to: entity)
        }
    }
}

解决方案 #

1. 实现ComponentPropertyDisplay协议 #

Reality Composer Pro需要明确感知组件属性变更事件，通过实现该协议可以直接在属性修改时触发预览更新：

extension BinOpenerComponent: ComponentPropertyDisplay {
    public static func propertyDidChange(_ entity: Entity, property: String) {
        // 仅处理opacity字段变更
        guard property == "opacity", let component = entity.binOpenerComponent else { return }
        component.applyOpacity(to: entity)
    }
}

2. 修正系统查询的组件路径 #

原代码中查询使用了RealityKitContent.BinOpenerComponent，若组件不在该命名空间下会导致查询失败，修改为直接引用组件类型：

public class OpacitySystem: System {
    static let query = EntityQuery(where: .has(BinOpenerComponent.self))
    
    // ... 其余代码保持不变
}

3. 注册系统到Reality Composer Pro预览环境 #

添加系统注册逻辑，确保RCP预览场景能加载你的自定义系统：

@MainActor
public func registerRealityComposerProSystems() {
    RealityKit.Scene.systems.register(OpacitySystem.self)
}

同时在Package.swift的目标配置中添加RCP支持插件：

targets: [
    .target(
        name: "YourComponentTarget",
        plugins: [
            .plugin(name: "RealityComposerProSupport", package: "swift-packages")
        ]
    )
]

4. 优化applyOpacity方法的幂等性 #

避免重复设置相同的透明度值，提升预览更新效率：

func applyOpacity(to entity: Entity) {
    guard let modelEntity = entity as? ModelEntity else { return }
    
    // 仅当透明度值变化时才更新组件
    if let existingOpacity = modelEntity.components[OpacityComponent.self], 
       existingOpacity.opacity == opacity {
        return
    }
    let opacityComponent = OpacityComponent(opacity: opacity)
    modelEntity.components.set(opacityComponent)
}

原因说明 #

Reality Composer Pro的预览环境与设备运行环境存在差异：默认的System帧更新逻辑在RCP预览中不会自动响应组件属性的手动修改，必须通过ComponentPropertyDisplay协议明确绑定属性变更与预览更新的逻辑，同时确保系统注册路径正确，才能实现实时预览效果。

内容的提问来源于stack exchange，提问作者Silvering