<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "USDKit",
  "identifier" : "/documentation/USDKit/USDStageComponent",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "USDKit",
      "RealityKit"
    ],
    "preciseIdentifier" : "s:18_USDKit_RealityKit17USDStageComponentV"
  },
  "title" : "USDStageComponent"
}
-->

# USDStageComponent

A component that renders a USD stage as RealityKit entities.

```
struct USDStageComponent
```

## Overview

Attach a `USDStageComponent` to an entity to render USD content as child
entities. The component supports two modes of operation:

- **Manual mode**: Created with [`init(allowsHitTesting:)`](/documentation/USDKit/USDStageComponent/init(allowsHitTesting:)). You control
  when rendering occurs by calling [`render(_:to:at:)`](/documentation/USDKit/USDStageComponent/render(_:to:at:)).
- **Automatic mode**: Created with [`init(_:timeCode:allowsHitTesting:)`](/documentation/USDKit/USDStageComponent/init(_:timeCode:allowsHitTesting:)).
  The component manages rendering internally and updates when the
  stage or time code changes.

## Topics

### Creating a stage component

[`init(USDStage, timeCode: USDStage.TimeCode, allowsHitTesting: Bool) async`](/documentation/USDKit/USDStageComponent/init(_:timeCode:allowsHitTesting:))

Creates a USDStageComponent in automatic mode and waits for the
first render to complete.

[`init(allowsHitTesting: Bool)`](/documentation/USDKit/USDStageComponent/init(allowsHitTesting:))

Creates a USDStageComponent in manual mode.

### Configuring the component

[`var stage: USDStage?`](/documentation/USDKit/USDStageComponent/stage)

The stage currently being rendered by this component, or `nil` if
the component is in manual mode and no render has been performed yet.

[`var timeCode: USDStage.TimeCode`](/documentation/USDKit/USDStageComponent/timeCode)

The time code to render at.

[`let allowsHitTesting: Bool`](/documentation/USDKit/USDStageComponent/allowsHitTesting)

Whether the rendered entities support hit testing.
Set at initialization and cannot be changed afterwards.

[`let rendersAutomatically: Bool`](/documentation/USDKit/USDStageComponent/rendersAutomatically)

Whether the component renders automatically in response to stage
or time code changes. `false` indicates manual mode, in which
rendering must be triggered explicitly via [`render(_:to:at:)`](/documentation/USDKit/USDStageComponent/render(_:to:at:)).

### Rendering the stage

[`static func render(USDStage, to: Entity, at: USDStage.TimeCode) async -> USDStageComponent.RenderResult`](/documentation/USDKit/USDStageComponent/render(_:to:at:))

Renders a USD stage to an entity in manual mode.

[`struct RenderResult`](/documentation/USDKit/USDStageComponent/RenderResult)

The result of a render operation.

### Type Methods

[`static func coordinateSpace(on: Entity, at: USDLayer.Path, timeCode: USDStage.TimeCode?) -> some CoordinateSpace3DFloat`](/documentation/USDKit/USDStageComponent/coordinateSpace(on:at:timeCode:))

Returns a coordinate space anchored to the closest rendered ancestor of `path`.

[`static func waitForRenderCompletion(on: Entity) async -> USDStageComponent.RenderResult`](/documentation/USDKit/USDStageComponent/waitForRenderCompletion(on:))

Waits for automatic rendering to complete.

## Relationships

### Conforms To

[`Decodable`](/documentation/Swift/Decodable)

[`Component`](/documentation/RealityKit/Component)

[`Equatable`](/documentation/Swift/Equatable)

[`Copyable`](/documentation/Swift/Copyable)

[`Encodable`](/documentation/Swift/Encodable)

[`Escapable`](/documentation/Swift/Escapable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)