使用 Xcode 扩展 Reality Composer Pro 3 的功能

探索 Reality Composer Pro 3 如何助你构建规模更大、更具雄心的空间项目。了解如何创建项目专属插件，以便编辑自定组件、运行自定系统，并构建自己的 ScriptGraph 节点，从而全面掌控你的空间创作工作流程。

章节

资源

- 高清视频
- 标清视频

相关视频

WWDC26

大家好我是Niklas 本次讲座将介绍如何使用插件扩展Reality Composer Pro 让美术师和内容创作者能够在编辑器中直接处理资源快速迭代并构建出色的3D App和游戏这项功能将在今年晚些时候推出

这就是Reality Composer Pro 3 这是Apple为RealityKit打造的游戏及3D内容编辑器最新版本此更新版本支持更大型的场景为美术师提供友好工作流以便快速迭代内容并支持在头显中预览场景

你可以在以下讲座中了解更多有关Reality Composer Pro 3的内容「Iterate your spatial scenes faster with Reality Composer Pro 3」另一个值得关注的讲座是「Design no-code games with Reality Composer Pro 3」该讲座介绍了如何不编写任何代码来构建一款游戏通过使用Reality Composer Pro的可视化脚本工具Script Graph 在本次演讲中我将展示如何通过代码实现更多功能我将介绍如何在Xcode中构建插件将你的项目专属内容公开给Reality Composer Pro 3 你的自定义组件将显示在编辑器中美术师和设计师可以在那里调整这些组件例如美术师可以调整水位高度或旋转速度并实时看到大锅做出相应反应无需构建和部署App

我将先介绍扩展编辑器的通用机制然后我将展示如何使用它在编辑器中运行自定义组件和自定义系统我还将展示如何添加你自己的自定义动画到序列器时间轴最后我将展示如何创建自定义节点用于Script Graph 我将从介绍通用机制开始关于扩展Reality Composer Pro 以及在团队协作时它是如何工作的我将在Chaparral Village游戏中工作这款游戏由开发者美术师和设计师团队共同制作该游戏同时包含 Reality Composer Pro项目和Xcode项目编辑器项目通常由美术师和设计师使用用于创建体验内容而Xcode项目由工程师使用以构建最终App 以及让美术师在编辑器中创建自定义数据的插件

Reality Composer Pro项目和Xcode项目相互关联这样你就可以直接从编辑器中启动App

你可以为自己的项目设置此关联使用窗口顶部的模拟工具栏编辑器项目和Xcode项目存放在同一个git仓库中美术师和工程师在本地进行修改然后提交并推送以与团队其他成员共享

当你将文件导入 Reality Composer Pro 3时它会被转换为内部数据格式并以JSON文件形式保存到磁盘你可以使用git的内置工具合并更改但编辑器也附带自定义合并工具该工具合并文件时冲突少于标准git合并要将数据从Reality Composer Pro 3 导入App 你需要将其导出为Reality File 这是RealityKit的序列化格式

这里有一张示意图展示了这一切如何配合运作 Xcode项目用于构建最终游戏App 以及Reality Composer Pro 3 的插件框架 Reality Composer Pro 3用于设置游戏中的各种3D场景和游戏对象 RCPCustomComponents.framework 使组件和开发者创建的系统在编辑器中可用

这样美术师和关卡设计师可以编辑它们查看其工作方式并交互式地改进内容

最后在Reality Composer Pro 3 中创建的场景将被导出为Reality File 该文件被链接进App 并由App加载

当代码更新时开发者将构建新的插件框架供团队所有成员使用以及新的App 当内容更改时将导出新的Reality File 在最终App中测试该Xcode项目已设置了两个不同的Schema ChaparralVillage用于构建实际App 和RCPCustomComponents 用于构建 Reality Composer Pro 3的插件项目中所有自定义组件和自定义系统在这两个Schema之间共享让我们看看它是如何工作的我将使用插件系统创建一个自定义组件并将其公开给Reality Composer Pro 我想与美术师合作为这口大锅创建一个效果在游戏中这口大锅将用于混合药水我希望能控制水位高度这样当添加原料时水位可以上升和下降我还想添加一个漩涡效果这样你就可以看到水在混合药水时旋转但让我们从设置水位开始

我可以用Script Graph来实现它看起来会是这样在更新事件上我获取水面实体并将其移动到特定位置但如果我想做更高级的操作使用自定义组件可能更合适而不是Script Graph Script Graph和自定义Swift代码可以完成类似的功能通常取决于个人偏好你想使用哪种方式但非常庞大的Script Graph 难以维护这可能是切换到代码的一个好理由代码还允许你与其他Apple API交互这些API在Script Graph中不可用例如SwiftUI 对于这口大锅我最终希望水位能与其他系统关联例如在水面上漂浮的原料所以编写代码是合理的为此我先创建一个简单的组件用于存储大锅的水位它有一个属性用于存储水位

除了Component协议之外 Cauldron还实现了Codable 这是在 Reality Composer Pro 3中表示此组件所必需的并将其序列化为Reality File 对于更高级的组件那些具有不应显示在编辑器中的运行时属性的组件实现CodingKeys 可能也很有意义但对于这个简单的组件我们只想序列化所有属性所以不需要这样做接下来我将创建一个自定义系统用于设置水位在系统更新中我找到具有Cauldron组件的实体然后我查找水网格子实体并调整水网格的位置基于Cauldron组件中设置的水位之后我需要确保 Reality Composer Pro 3 可以使用我的自定义组件和对应的系统为此我需要创建一个插件类实现RealityComposerProPlugin协议该协议来自 RealityComposerPro Swift Package 当你在编辑器中关联Xcode项目时此Package会自动添加到你的Xcode项目中当你在编辑器中关联它时使用模拟工具栏中的「与Xcode一起运行」选项在该类的setup方法中我使用从 Reality Composer Pro获取的context 来注册我的组件和系统这使这些组件和系统可供编辑器使用

我还需要确保 Reality Composer Pro 3 可以创建该插件我通过实现 createRealityComposerProPlugin()函数来完成该函数创建并返回我的插件你会注意到此函数以原始指针形式返回类这是因为我需要此函数在DLL接口中导出我还需要将其标记为C函数并为其指定导出名称这样插件加载器才能找到它让我们看看这一切在实践中如何运作首先我将创建包含 waterLevel属性的Cauldron组件

然后我将添加根据属性值定位水面的系统基于属性的值

最后让我们向 Reality Composer Pro注册组件和系统

现在我可以构建插件Schema 以创建动态库

现在我可以在编辑器中打开项目由于此项目有插件 Reality Composer Pro会询问我是否信任它我选择「信任」以加载插件

一旦我接受加载插件编辑器将向我展示已导入的组件

如果我转到项目的构建设置已导入的组件和系统也会显示在那里我还可以使用此设置面板指定自定义插件目录

已导入的组件位于项目中的自定义组件文件夹内现在我已导入组件且Reality Composer Pro 3已识别它我可以将其添加到 Cauldron实体

当我在编辑器中更改水位属性时你可以看到水面做出反应我的自定义系统正在编辑器内部运行通过插件机制并根据属性值更改水位美术师和设计师可以用这个在编辑器中微调属性无需重新构建和重新启动App

如果我想调试我的系统我可以在代码中设置断点并附加到编辑器应用程序

当它运行我的代码时它将在Xcode调试器中停止我可以检查我的逻辑

现在基本水面已经正常工作我想通过添加漩涡效果更上一层楼当玩家搅动大锅混合药水时我希望水面弯曲成漩涡形状要改变水面形状一位技术美术师构建了这个漩涡着色器使用Reality Composer Pro 3中的 Shader Graph系统 Shader Graph具有旋转速度等参数它将根据这些参数创建漩涡形状我希望能控制这些参数从我的自定义组件为此我先添加一些属性用于引导漩涡的形状然后我需要修改之前的大锅系统以便将这些参数传播到Shader Graph 首先我获取 Shader Graph材质然后我使用一个辅助函数计算水面的形状基于Cauldron属性我使用计算出的形状来设置Shader Graph参数最后我将此材质重新分配给模型让我们看看这在实践中如何工作首先我将向Cauldron 添加新属性

然后我将编写一个函数来计算水面

最后我将更新系统以设置着色器参数然后重新构建插件

每次重新构建插件时我需要重启Reality Composer Pro 以获取更改 Reality Composer Pro会再次询问我是否信任该项目如果你不想再看到这个对话框你可以勾选「不再询问」复选框

接下来会出现一个对话框显示我的自定义组件的更改这些更改对我来说都没问题所以我将接受它们

如果我返回到Cauldron组件我将看到那里有新属性

让我用水位的一些默认值来设置它和漩涡系数

现在让我尝试旋转速度的不同值你可以看到当我增加旋转速度时漩涡变得更深

接下来我想谈谈如何在动画系统中使用插件动画序列器支持自定义动画动作可以在插件中定义然后添加到序列器时间轴我想创建一个自定义动作用于设置大锅的水位为此我需要实现 EntityAction协议要保存到Reality File中它还需要实现Codable

我的动作接受两个参数水面的起始水位和终止水位这样它就可以在这两个值之间进行动画

对于EntityAction协议我还需要将动画值类型作为Transform返回这是在动画执行器中访问我的实体所必需的我还需要编写执行动作的代码并在动画运行时更新水位

为此我在实体动作中创建一个静态subscribe()函数我将从插件加载代码中调用它

在此函数中我使用EntityAction中的 subscribe方法订阅.updated事件该事件在RealityKit 运行动画时被调用我将用它来执行我的自定义动画动作我将获取已过去的动画时间作为0到1之间的归一化数

然后我计算当前水位通过使用归一化时间在起始和终止水位之间进行插值我从实体获取大锅组件并更新其水位最后我将修改后的大锅组件重新设置回实体最后一步是向 Reality Composer Pro 3 注册此自定义动画

与自定义组件和自定义系统一样我需要向context 注册动作以便编辑器能识别它

我还需要调用之前创建的subscribe函数以便动作在动画更新时执行让我们看看这在实践中如何工作首先我将定义我的自定义实体动作

然后我将添加实现此动作的代码

最后我将向编辑器注册此动作并重新构建插件

当我重启编辑器并打开项目时它会告诉我导入了一个新动作

让我们创建一个使用此动作的动画首先我将在编辑器中创建一个新序列

然后我将打开序列并设置动画的根实体为包含大锅的场景我准备了一个名为CauldronWorld的场景

接下来我将向序列添加一个动画轨道并选择大锅作为此轨道要使用的实体

现在我可以从左侧面板拖动SetWaterLevelAction 到轨道的时间轴中以创建在大锅上运行的动作我将在检查器中展开此动作以设置其参数大锅水位的起始值和终止值我将起始值设为0.3 终止值设为0.5 现在我可以播放动画并看到水位根据我的自定义动作发生变化

美术师和设计师可以使用Script Graph 来创建游戏玩法和交互性在Reality Composer Pro 3项目中而无需编写任何代码内置脚本节点已经很强大但如果你想更上一层楼你可以使用插件添加自定义节点设计师可以在 Script Graph中使用这些节点将自定义组件公开给 Script Graph的最快方式是使用@Scriptable宏为此我首先需要导入 RealityKitScripting 和RealityKitScriptingMacros模块此宏就是在这里定义的就像RealityComposerPro Swift Package一样当你从Reality Composer Pro内部创建Xcode项目时此Package会自动为你设置好然后我只需用@Scriptable宏标记我的组件结构体这将展开为一个schema变量描述该组件这样我就可以将其注册到脚本系统与所有其他注册一样这在插件的 setup函数中进行脚本模块需要在主线程上注册

我首先为我的项目创建一个脚本配置在配置的初始化器中我需要返回所有脚本模块的列表

我将创建一个单独的模块用于存储我的Cauldron Schema 此Schema由 @Scriptable宏生成然后我将我的配置添加到RealityKitScripting 让我们看看这在实践中如何工作首先我将导入脚本模块并将@Scriptable宏添加到Cauldron组件

然后我将添加向编辑器注册脚本模块的代码并重新构建插件

让我们创建一个Script Graph 使用Cauldron组件的新自定义节点我将首先向 Cauldron实体添加Scripting组件

我双击新组件以打开Script Graph编辑器让我们实现当用户按下键盘上的某个键时水位发生变化我将先添加一个更新节点此节点在每次场景更新时触发

接下来我将添加一个If节点并将其连接到按键事件这样每次按下该键时节点就会触发

我将连接If节点的true连接器以设置大锅的水位

现在当按下「a」键时大锅的水位将被设置为0.25 我将连接另一个键以设置不同的水位为此让我复制并粘贴整个图

然后在副本中我将把键改为「z」水位改为0.5

我可以通过打开模拟视图来测试当我按下「a」和「z」键时水位上升和下降

本次讲座涵盖了很多内容我向你展示了如何使用Xcode 创建一些简单的插件并扩展编辑器的功能以处理你的App数据甚至在编辑器中运行你的代码如需了解更多建议查看「Explore advances in RealityKit」讲座以了解RealityKit的最新功能我还建议观看「Supercharge your spatial workflows with Reality Composer Pro 3」讲座该讲座介绍了如何提升使用编辑器的效率期待看到你用全新Reality Composer Pro 3 创作出精彩的体验感谢观看！

6:08 - Cauldron component

// Add a component to represent the water level

import RealityKit

public struct Cauldron: Component, Codable {
    public var waterLevel: Float

    enum CodingKeys: CodingKey {
        case waterLevel
    }
}

6:42 - CauldronSystem

// Add a system to control the water level

import RealityKit

public struct CauldronSystem: System {
    let query = EntityComponentQuery(Cauldron.self)
    public init(scene: Scene) {}

    public func update(context: SceneUpdateContext) {
        for (entity, cauldron) in context.entities(matching: query) {
            guard let water = entity.findEntity(named: "Cauldron_Water_mesh")
                else { continue }
            water.setPosition(SIMD3<Float>(0, 1, 0) * cauldron.waterLevel, relativeTo: entity)
        }
    }
}

7:00 - RCPCustomComponentsPlugin

// Make sure that Reality Composer Pro 3 knows about the Cauldron and CauldronSystem

import RealityComposerPro

final class RCPCustomComponentsPlugin: RealityComposerProPlugin {
    public func setup(context: any RealityComposerProContext) {
        context.registerComponent(Cauldron.self)
        context.registerSystem(CauldronSystem.self)
    }
}

@_cdecl("createRealityComposerProPlugin")
public func createRealityComposerProPlugin() -> UnsafeMutableRawPointer {
    return RCPCustomComponentsPlugin().passRetained()
}

10:49 - Cauldron component with vortex properties

// Properties to control water surface

import RealityKit

public struct Cauldron: Component, Codable {
    public var waterLevel: Float
    public var rotationSpeed: Float
    public var minWaterLevel: Float
    public var maxWaterLevel: Float
    public var vortexCoeff: Float
}

11:05 - CauldronSystem update with ShaderGraph

public func update(context: SceneUpdateContext) {
    for (entity, cauldron) in context.entities(matching: query) {
        guard let water = entity.findEntity(named: "Cauldron_Water_mesh") else { continue }
        water.setPosition(SIMD3<Float>(0, 1, 0) * cauldron.waterLevel, relativeTo: entity)

        guard var model = water.components[ModelComponent.self] else { continue }
        guard var mat = model.materials.first as? ShaderGraphMaterial else { continue }
        let surface = computeSurface(cauldron: cauldron)
        try? mat.setParameter(name: "Level Radius", value: .float(surface.levelRadius))
        try? mat.setParameter(name: "Lowest Point",
            value: .float(cauldron.waterLevel - surface.lowestPoint))
        try? mat.setParameter(name: "Height Change", value: .float(surface.heightChange))
        try? mat.setParameter(name: "Level Coeff", value: .float(surface.levelCoeff))
        try? mat.setParameter(name: "Is Level", value: .bool(surface.isLevel))
        model.materials[0] = mat
        water.components.set(model)
    }
}

13:25 - SetWaterLevelAction

// Custom action for setting the water level of the Cauldron

import RealityKit

public struct SetWaterLevelAction: EntityAction, Codable {
    // Parameters for the action
    public let startWaterLevel: Float
    public let endWaterLevel: Float

    // Required by EntityAction protocol
    public var animatedValueType: (any AnimatableData.Type)? { Transform.self }
}

14:05 - SetWaterLevelAction subscribe

extension SetWaterLevelAction {
    static func subscribe() {
        Task { @MainActor in
            SetWaterLevelAction.subscribe(to: .updated) { event in
                let normalizedTime = (event.playbackController.time - event.startTime) /
                    event.duration
                let action = event.action
                let currentLevel = action.startWaterLevel +
                    Float(normalizedTime) * (action.endWaterLevel - action.startWaterLevel)
                guard let entity = event.targetEntity else { return }
                guard var cauldron = entity.components[Cauldron.self] else { return }
                cauldron.waterLevel = currentLevel
                entity.components.set(cauldron)
            }
        }
    }
}

14:56 - RCPCustomComponentsPlugin with action

// Make sure that Reality Composer Pro 3 knows about the SetWaterLevelAction

import RealityComposerPro

final class RCPCustomComponentsPlugin: RealityComposerProPlugin {
    public func setup(context: any RealityComposerProContext) {
        context.registerComponent(Cauldron.self)
        context.registerSystem(CauldronSystem.self)

        context.registerAction(SetWaterLevelAction.self)
        SetWaterLevelAction.subscribe()
    }
}

@_cdecl("createRealityComposerProPlugin")
public func createRealityComposerProPlugin() -> UnsafeMutableRawPointer {
    return RCPCustomComponentsPlugin().passRetained()
}

17:32 - Cauldron with @Scriptable macro

// Expose Cauldron to Script Graphs

import RealityKit
import RealityKitScripting
import RealityKitScriptingMacros

@Scriptable
public struct Cauldron: Component, Codable {
    public var waterLevel: Float
    public var rotationSpeed: Float
    public var minWaterLevel: Float
    public var maxWaterLevel: Float
    public var vortexCoeff: Float
}

18:08 - Register scripting module

// Register scripting module

public func setup(context: any RealityComposerProContext) {
    context.registerComponent(Cauldron.self)
    context.registerSystem(CauldronSystem.self)

    context.registerAction(SetWaterLevelAction.self)
    SetWaterLevelAction.subscribe()

    Task { @MainActor in
        let config = RKS.Configuration(id: "ChaparralVillage")
            .onInitialize { _ in
            [
                Module("ChaparralVillage") {
                    Cauldron.SchemaProvider.schema
                }
            ]
        }
        try! RKS.addConfiguration(config)
    }
}

0:00 - Introduction
An overview of the Reality Composer Pro 3 plugin system, showing how Xcode and the editor share a project to let engineers and artists collaborate — with custom components, systems, animation actions, and Script Graph nodes all running live inside the editor.
2:00 - Extending the editor
Learn how the Reality Composer Pro 3 plugin system works: how the editor and Xcode share a single git repository, how custom Swift code is compiled into a dynamic library, and how the editor loads and trusts plugins at runtime.
4:51 - Custom components and systems
Build a Cauldron component and CauldronSystem using RealityKit, expose them to the editor via a RealityComposerProPlugin, and see the water level property update in real time as artists adjust values in the inspector.
10:32 - Controlling the water surface
Extend the Cauldron component with vortex shader properties and update the system to drive a ShaderGraphMaterial at runtime, enabling artists to control vortex depth and rotation speed directly from the Reality Composer Pro 3 inspector.
13:19 - Custom animation actions
Implement the EntityAction protocol to create a SetWaterLevelAction that animates the cauldron water level on the sequencer timeline, subscribe to animation update events to interpolate the level, and register the action with the editor plugin.
17:12 - Custom Script Graph nodes
Use the @Scriptable macro to expose a custom component to Reality Composer Pro 3 Script Graphs, register a scripting module in the plugin setup, and see the generated nodes appear in the Script Graph editor for no-code artist workflows.
21:16 - Next steps
Recap of the plugin capabilities covered — custom components, systems, animation actions, and Script Graph nodes — with recommendations to explore the Explore Advances in RealityKit and Supercharge Your Spatial Workflows sessions.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

使用 Xcode 扩展 Reality Composer Pro 3 的功能

章节

资源

相关视频

WWDC26