Contents

ReferenceComponent

A component that can load another entity from a file.

Declaration

struct ReferenceComponent

Overview

You can use a ReferenceComponent to load other entities from files in your app’s main bundle. This allows you to load complex scenes incrementally, resulting in more responsive apps. It also enables collaborative workflows so you can split a complex scene into separate pieces that different teams own.

Use a ReferenceComponent by adding it to an entity when building up a scene programmatically. Then call write(to:) to save the scene to a .reality file.

// Create the root entity.
let root = Entity()

// Create an entity that references another entity file.
let earth = Entity()
earth.setParent(root)

// Add a reference to another entity that loads immediately
// when the root entity loads.
earth.components.set(ReferenceComponent(
    named: "Earth",
    loadingPolicy: .immediate))

// Add a reference to another entity that loads on demand.
let mars = Entity()
mars.name = "mars"
mars.components.set(ReferenceComponent(
    named: "Mars",
    loadingPolicy: .onDemand))

// Write the root entity to a `.reality` file.
try await root.write(to: fileURL)

When your app loads the .reality file, it can dynamically load referenced entities from files. For references that have a ReferenceComponent.LoadingPolicy of ReferenceComponent.LoadingPolicy.onDemand, you can use loadReference(at:) to load content on demand.

if let entity = root.findEntity(named: "mars") {
    try ReferenceComponent.loadReference(at: entity)
}

Conversely, use releaseReference(at:) to unload content and free up memory.

Topics

Initializers

Instance Properties

Type Methods

Enumerations

See Also

Loading an entity from a file