RealityFoundation · IOS API REFERENCE

ReferenceComponent

struct · iOS 18.0+ · SDK 27.1

struct ReferenceComponent

A component that can load another entity from a file. 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 ``Entity/write(to:)`` to save the scene to a `.reality` file. ```swift // 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-swift.enum`` of ``ReferenceComponent/LoadingPolicy-swift.enum/onDemand``, you can use ``ReferenceComponent/loadReference(at:)-1en8b`` to load content on demand. ```swift if let entity = root.findEntity(named: "mars") { try ReferenceComponent.loadReference(at: entity) } ``` Conversely, use ``ReferenceComponent/releaseReference(at:)`` to unload content and free up memory.

Members (9)

static · iOS 18.0+

loadReference

TypeScript

static loadReferenceAt(entity: Entity): void

Swift declaration

static func loadReference(at entity: Entity) throws

Synchronously loads another entity file that an entity depends on. - Parameter entity: The entity that holds the ``ReferenceComponent`` to load.

static · iOS 18.0+

loadReference

TypeScript

static loadReferenceAt46131(entity: Entity): Promise<void>

Swift declaration

@MainActor static func loadReference(at entity: Entity) async throws

Asynchronously loads another entity file that an entity depends on. - Parameter entity: The entity that holds the ``ReferenceComponent`` to load.

static · iOS 18.0+

releaseReference

TypeScript

static releaseReference(entity: Entity): void

Swift declaration

static func releaseReference(at entity: Entity) throws

Releases the reference an entity holds. - Parameter entity: The entity that holds the ``ReferenceComponent`` to release.

get · iOS 18.0+

loadingPolicy

TypeScript

get loadingPolicy(): ReferenceComponent_LoadingPolicy

Swift declaration

var loadingPolicy: ReferenceComponent.LoadingPolicy { get }

A policy that defines when a referenced entity loads. The default loading policy is ``ReferenceComponent/LoadingPolicy-swift.enum/onDemand``.

init · iOS 18.0+

init

TypeScript

static initNamedLoadingPolicy(name: string, loadingPolicy?: ReferenceComponent_LoadingPolicy): ReferenceComponent

Swift declaration

init(named name: String, loadingPolicy: ReferenceComponent.LoadingPolicy = .onDemand)

Creates a reference component with a name and loading policy. Place references in the app's main bundle. - Parameters: - name: The name of the entity to load. - loadingPolicy: A loading policy indicating when the app loads the entity.

init · iOS 18.0+

init

TypeScript

static initNamedAtLoadingPolicy(name: string, bundlePath?: string, loadingPolicy?: ReferenceComponent_LoadingPolicy): ReferenceComponent

Swift declaration

init(named name: String, at bundlePath: String = "", loadingPolicy: ReferenceComponent.LoadingPolicy = .onDemand)

Creates a reference component with a name, loading policy, and bundle path. - Parameters: - name: The name of the entity to load. - bundlePath: The bundle path to search for the resource. Specify the path relative to the Resources directory. - loadingPolicy: A loading policy that indicates when the app loads the entity.

init · iOS 18.0+

init

TypeScript

static initNamedInLoadingPolicy(name: string, bundle: _Foundation_Bundle, loadingPolicy?: ReferenceComponent_LoadingPolicy): ReferenceComponent

Swift declaration

init(named name: String, in bundle: Bundle, loadingPolicy: ReferenceComponent.LoadingPolicy = .onDemand)

Creates a reference component with a name, loading policy, and bundle. - Parameters: - name: The name of the entity to load. - bundle: The bundle to search for the resource. - loadingPolicy: A loading policy indicating when the app loads the entity.

get · iOS 18.0+

state

TypeScript

get state(): ReferenceComponent_ReferenceState

Swift declaration

var state: ReferenceComponent.ReferenceState { get }

A variable that indicates the loading state of the referenced entity.

get · iOS 18.0+

reference

TypeScript

get reference(): (Entity) | null

Swift declaration

var reference: Entity? { get }

The root entity of the referenced entity file. This property returns `nil` when the referenced entity isn't loaded.

Skipped declarations

No declarations were skipped in this snapshot.

All RealityFoundation types →