<!--
{
  "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/USDStage",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "USDKit"
    ],
    "preciseIdentifier" : "s:6USDKit8USDStageV"
  },
  "title" : "USDStage"
}
-->

# USDStage

A 3D scene composed from one or more Universal Scene Description (USD) documents.

```
struct USDStage
```

## Overview

Stages support authoring, animating, and composing 3D data from various
3D file formats. A stage can contain meshes, materials, cameras, lights, or
arbitrary custom data, as well as references to textures or additional scene
data stored in separate files.

A stage is a scene graph formed by opening a single document (the “root
layer”) and then recursively following the composition rules described by
that document in order to assemble a scene graph. Because of this
composition process, a `USDStage` object presents a unified view that may
incorporate data from more than one source file.

A `USDStage` object is a mutable view onto the composed scene graph. It
consists of a tree-structured hierarchy of [`USDPrim`](/documentation/USDKit/USDPrim) objects representing
nodes in the scene graph. Each prim has schemas that give it a kind (is-a)
and capabilities (has-a), attributes that contain possibly-animated values,
and relationships that connect the prim to other objects in the stage.

The [`USDPrim`](/documentation/USDKit/USDPrim), `USDPrim.Attribute`, and `USDPrim.Relationship` objects in a
stage are owned by the `USDStage` object. Values of these types act as views
or handles into the composed content of the stage. Modifying any value in a
stage authors a modification to an [`USDLayer`](/documentation/USDKit/USDLayer) that represents a file or
file-like storage. Values of these types refer to and act on the current
state of a particular stage, and become invalid if the stage is closed.

> Note: A stage may also possess a “session layer” that may contain
> temporary modifications that will not be written to any file.

A composed, runtime view of a USD scene assembled from one or more layers.

## Topics

### Creating a stage

[`init(displayName: String?, loadingPayloads: USDStage.InitialLoadRule)`](/documentation/USDKit/USDStage/init(displayName:loadingPayloads:))

Creates a new memory-backed stage.

[`init(string: String, loadingPayloads: USDStage.InitialLoadRule) throws`](/documentation/USDKit/USDStage/init(string:loadingPayloads:))

Creates a stage from a string containing a `.usda` document.

[`init(Data, type: UTType, loadingPayloads: USDStage.InitialLoadRule) throws`](/documentation/USDKit/USDStage/init(_:type:loadingPayloads:))

Creates a stage from in-memory data in a given format.

### Opening a stage

[`static func open(rootLayer: USDLayer, sessionLayer: USDLayer?, options: USDStage.OpenOptions) throws -> USDStage`](/documentation/USDKit/USDStage/open(rootLayer:sessionLayer:options:))

Opens a stage rooted at a given layer.

[`static func open(FilePath, sessionLayer: USDLayer?, options: USDStage.OpenOptions) throws -> USDStage`](/documentation/USDKit/USDStage/open(_:sessionLayer:options:))

Opens a stage using a file as the root layer.

[`static func open(URL, loadingPayloads: USDStage.InitialLoadRule) throws -> USDStage`](/documentation/USDKit/USDStage/open(_:loadingPayloads:))

Opens a stage using the file at a URL as its root layer.

[`struct OpenOptions`](/documentation/USDKit/USDStage/OpenOptions)

Options that specify behavior related to opening a stage.

[`enum InitialLoadRule`](/documentation/USDKit/USDStage/InitialLoadRule)

Specifies the rule used when opening a stage to determine if referenced payloads are loaded.

### Saving and reloading

[`func save() throws`](/documentation/USDKit/USDStage/save())

Saves the stage’s changed layers to their sources.

[`func saveSessionLayers() throws`](/documentation/USDKit/USDStage/saveSessionLayers())

Saves the stage’s changed session layers to their sources.

[`func reload() throws`](/documentation/USDKit/USDStage/reload())

Reloads the stage’s layers from their sources, discarding any unsaved changes.

### Accessing prims and properties

[`func prim(at: USDLayer.Path) -> USDPrim`](/documentation/USDKit/USDStage/prim(at:))

Returns the prim at a given path, if it exists.

[`func object(at: USDLayer.Path) -> USDStage.Object`](/documentation/USDKit/USDStage/object(at:))

Returns the object at a given path, if it exists.

[`func property(at: USDLayer.Path) -> USDPrim.Property`](/documentation/USDKit/USDStage/property(at:))

Returns the property at a given path, if it exists.

[`func attribute(at: USDLayer.Path) -> USDPrim.Attribute`](/documentation/USDKit/USDStage/attribute(at:))

Returns the attribute at a given path, if it exists.

[`func relationship(at: USDLayer.Path) -> USDPrim.Relationship`](/documentation/USDKit/USDStage/relationship(at:))

Returns the relationship at a given path, if it exists.

[`var pseudoRoot: USDPrim`](/documentation/USDKit/USDStage/pseudoRoot)

The prim at the top of the stage’s namespace, whose path is `/`.

[`var defaultPrim: USDPrim?`](/documentation/USDKit/USDStage/defaultPrim)

The prim designated as this stage’s default entry point when the stage is referenced.

[`var hasDefaultPrim: Bool`](/documentation/USDKit/USDStage/hasDefaultPrim)

Return true if this stage’s root layer has an authored opinion for the
default prim layer metadata.

[`struct Object`](/documentation/USDKit/USDStage/Object)

### Authoring prims

[`func definePrim(at: USDLayer.Path, type: USDToken) -> USDPrim`](/documentation/USDKit/USDStage/definePrim(at:type:))

Defines a prim at a given path, if none already exists.

[`func overridePrim(at: USDLayer.Path) -> USDPrim`](/documentation/USDKit/USDStage/overridePrim(at:))

Authors an override prim at a given path, if no prim exists at that path.

[`func removePrim(at: USDLayer.Path) -> Bool`](/documentation/USDKit/USDStage/removePrim(at:))

Removes all authored data at the given path in the current edit target.

### Traversing the scene

[`var descendants: [USDPrim]`](/documentation/USDKit/USDStage/descendants)

The active, loaded, defined, non-abstract descendant prims of this stage’s pseudo-root.

[`func descendants(where: USDPrim.Predicate) -> [USDPrim]`](/documentation/USDKit/USDStage/descendants(where:))

Returns the descendant prims of this stage that satisfy the given predicate.

[`var allDescendants: [USDPrim]`](/documentation/USDKit/USDStage/allDescendants)

All descendant prims of this stage’s pseudo-root.

### Managing layers

[`var rootLayer: USDLayer`](/documentation/USDKit/USDStage/rootLayer)

The root layer of this stage.

[`func muteLayer(String)`](/documentation/USDKit/USDStage/muteLayer(_:))

Mutes the layer with the given identifier, excluding its opinions from composition.

[`func unmuteLayer(String)`](/documentation/USDKit/USDStage/unmuteLayer(_:))

Unmutes the layer with the given identifier, restoring its opinions to composition.

[`func isLayerMuted(String) -> Bool`](/documentation/USDKit/USDStage/isLayerMuted(_:))

Returns a Boolean value that indicates whether the layer with the given identifier is muted.

### Setting the edit target

[`var editTarget: USDStage.EditTarget`](/documentation/USDKit/USDStage/editTarget-swift.property)

The destination for authoring operations on this stage.

[`struct EditTarget`](/documentation/USDKit/USDStage/EditTarget-swift.struct)

A destination for authoring operations on a stage.

### Working with time codes

[`var timeCodeRange: ClosedRange<USDStage.TimeCode>`](/documentation/USDKit/USDStage/timeCodeRange)

The range of time codes over which this stage has authored animation.

[`var timeCodesPerSecond: Double`](/documentation/USDKit/USDStage/timeCodesPerSecond)

The number of time codes per second of playback for this stage.

[`struct TimeCode`](/documentation/USDKit/USDStage/TimeCode)

A unitless point in time, used with time-varying values authored in 3D scenes.

### Reading stage metrics

[`var metersPerUnit: Double`](/documentation/USDKit/USDStage/metersPerUnit)

The number of meters represented by one unit in this stage’s
coordinate system.

[`var hasAuthoredMetersPerUnit: Bool`](/documentation/USDKit/USDStage/hasAuthoredMetersPerUnit)

A Boolean value that indicates whether this stage has an authored
[`metersPerUnit`](/documentation/USDKit/USDStage/metersPerUnit) opinion.

[`var upAxis: USDToken`](/documentation/USDKit/USDStage/upAxis)

The axis that points upward in this stage’s coordinate system.

[`static var fallbackUpAxis: USDToken`](/documentation/USDKit/USDStage/fallbackUpAxis)

The up axis used when a stage has no authored opinion.

### Observing changes

[`func addObserver<Notice>(for: Notice.Type, using: (Notice) -> Void) -> USDStage.ObservationToken`](/documentation/USDKit/USDStage/addObserver(for:using:))

Registers an observer that runs when a notice of the given type is sent
for this stage.

[`protocol Notice`](/documentation/USDKit/USDStage/Notice)

A change notification that can be observed on a stage.

[`struct ObjectsDidChange`](/documentation/USDKit/USDStage/ObjectsDidChange)

A notice sent when the objects on a stage change.

[`struct ObservationToken`](/documentation/USDKit/USDStage/ObservationToken)

A token that keeps an observer registered for as long as it is retained.

### Exporting the stage

[`func exportPackage(to: URL, options: USDStage.ExportOptions) throws`](/documentation/USDKit/USDStage/exportPackage(to:options:)-6s2wk)

Packages the stage into a USDZ archive.

[`func exportPackage(to: FilePath, options: USDStage.ExportOptions) throws`](/documentation/USDKit/USDStage/exportPackage(to:options:)-2x7yr)

Packages the stage into a USDZ archive.

[`func exportFlattened(to: URL) throws`](/documentation/USDKit/USDStage/exportFlattened(to:)-98kpc)

Exports the stage as a flattened USD file.

[`func exportFlattened(to: FilePath) throws`](/documentation/USDKit/USDStage/exportFlattened(to:)-6717d)

Exports the stage as a flattened USD file.

[`struct ExportOptions`](/documentation/USDKit/USDStage/ExportOptions)

Options for packaging a stage into a USDZ file.

### Instance Methods

[`func exportPackage(options: USDStage.ExportOptions) throws -> Data`](/documentation/USDKit/USDStage/exportPackage(options:))

Packages the stage into a USDZ archive and returns it as in-memory data.

## Relationships

### Conforms To

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

---

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)