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

# USDPrim

A single node in a stage’s scene hierarchy that holds attributes, relationships, metadata, and child prims.

```
struct USDPrim
```

## Topics

### Creating a prim

[`init()`](/documentation/USDKit/USDPrim/init())

An invalid prim handle.

[`init?(USDStage.Object)`](/documentation/USDKit/USDPrim/init(_:))

Casts an object handle to a prim handle.

### Identifying the prim

[`var path: USDLayer.Path`](/documentation/USDKit/USDPrim/path)

The complete scene path to this prim, relative to its stage.

[`var primPath: USDLayer.Path`](/documentation/USDKit/USDPrim/primPath)

The complete scene path to this prim, relative to its stage.

[`var isValid: Bool`](/documentation/USDKit/USDPrim/isValid)

A Boolean value indicating whether this prim is valid.

[`var specifier: USDPrim.Specifier`](/documentation/USDKit/USDPrim/specifier-swift.property)

The specifier that describes how this prim is defined, such as `def`, `over`, or `class`.

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

The stage that owns this prim.

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

The immediate parent prim of this prim.

[`var description: String`](/documentation/USDKit/USDPrim/description)

A summary description of this prim.

[`enum Specifier`](/documentation/USDKit/USDPrim/Specifier-swift.enum)

How a prim definition behaves in composition.

### Traversing the hierarchy

[`var children: [USDPrim]`](/documentation/USDKit/USDPrim/children)

The active, loaded, defined, non-abstract child prims of this prim.

[`var allChildren: [USDPrim]`](/documentation/USDKit/USDPrim/allChildren)

The child prims of this prim.

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

The active, loaded, defined, non-abstract descendant prims of this prim, in depth-first order.

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

The descendant prims of this prim.

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

The active, loaded, defined, non-abstract successor of this prim in its parent’s list of children.

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

Returns the child prims of this prim that satisfy the given predicate.

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

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

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

The successor of this prim in its parent’s list of children that satisfies the given predicate.

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

Returns the prim at a given path, relative to this prim.

[`struct Predicate`](/documentation/USDKit/USDPrim/Predicate)

A filter which returns true or false for prims based on their flags.

### Accessing properties

[`var properties: [USDPrim.Property]`](/documentation/USDKit/USDPrim/properties)

The properties of this prim, including those provided by its schemas.

[`var authoredProperties: [USDPrim.Property]`](/documentation/USDKit/USDPrim/authoredProperties)

The properties of this prim that have an authored opinion.

[`var propertyNames: [USDToken]`](/documentation/USDKit/USDPrim/propertyNames)

The names of this prim’s properties, including those provided by its schemas.

[`var authoredPropertyNames: [USDToken]`](/documentation/USDKit/USDPrim/authoredPropertyNames)

The names of this prim’s properties that have an authored opinion.

[`func property(named: USDToken) -> USDPrim.Property`](/documentation/USDKit/USDPrim/property(named:))

Returns the property with a given name on this prim.

[`func hasProperty(named: USDToken) -> Bool`](/documentation/USDKit/USDPrim/hasProperty(named:))

Returns true if an attribute or relationship with a given name exists.

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

Returns the object at a given path, relative to this prim.

[`struct Property`](/documentation/USDKit/USDPrim/Property)

A named property on a prim, which is either an attribute or a relationship.

### Accessing attributes

[`var attributes: [USDPrim.Attribute]`](/documentation/USDKit/USDPrim/attributes)

The attributes of this prim, including those provided by its schemas.

[`var authoredAttributes: [USDPrim.Attribute]`](/documentation/USDKit/USDPrim/authoredAttributes)

The attributes of this prim that have an authored opinion.

[`func attribute(named: USDToken) -> USDPrim.Attribute`](/documentation/USDKit/USDPrim/attribute(named:))

Returns the attribute with a given name on this prim.

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

Returns the attribute at a given path, relative to this prim.

[`func hasAttribute(named: USDToken) -> Bool`](/documentation/USDKit/USDPrim/hasAttribute(named:))

Returns true if an attribute with a given name exists on this prim.

[`func makeAttribute(named: USDToken, as: USDPrim.Attribute.ValueType, custom: Bool, variability: USDPrim.Property.Variability) -> USDPrim.Attribute`](/documentation/USDKit/USDPrim/makeAttribute(named:as:custom:variability:))

Creates an attribute with the given name on this prim, or returns the
existing attribute if one already exists.

[`struct Attribute`](/documentation/USDKit/USDPrim/Attribute)

### Accessing relationships

[`func relationship(named: USDToken) -> USDPrim.Relationship`](/documentation/USDKit/USDPrim/relationship(named:))

Returns the relationship with a given name on this prim.

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

Returns the relationship at a given path, relative to this prim.

[`func hasRelationship(named: USDToken) -> Bool`](/documentation/USDKit/USDPrim/hasRelationship(named:))

Returns true if a relationship with a given name exists on this prim.

[`struct Relationship`](/documentation/USDKit/USDPrim/Relationship)

A property that connects a prim to one or more other objects in the stage by their paths.

### Composing references and payloads

[`var references: USDPrim.ReferenceCollection`](/documentation/USDKit/USDPrim/references)

The reference composition arcs on this prim.

[`struct Reference`](/documentation/USDKit/USDPrim/Reference)

A reference to an external layer or asset.

[`struct ReferenceCollection`](/documentation/USDKit/USDPrim/ReferenceCollection)

Manages reference composition arcs on a prim.

[`struct Payload`](/documentation/USDKit/USDPrim/Payload)

A payload to an external asset.

[`enum ListPosition`](/documentation/USDKit/USDPrim/ListPosition)

Where a new composition arc should be inserted relative to existing arcs.

### Authoring variants

[`struct VariantSpec`](/documentation/USDKit/USDPrim/VariantSpec)

A handle to a single variant option within a variant set.

[`struct VariantSetSpec`](/documentation/USDKit/USDPrim/VariantSetSpec)

A handle to a variant set — a named group of variant options.

[`typealias VariantsMap`](/documentation/USDKit/USDPrim/VariantsMap)

Maps variant set names to lists of available variant names.

[`typealias VariantSelectionMap`](/documentation/USDKit/USDPrim/VariantSelectionMap)

Maps variant set names to selected variant names.

### Applying schemas and transforms

[`func applyAPISchema(USDToken) throws`](/documentation/USDKit/USDPrim/applyAPISchema(_:))

Applies a single-apply API schema to this prim.

[`func applyAPISchema(USDToken, instanceName: USDToken) throws`](/documentation/USDKit/USDPrim/applyAPISchema(_:instanceName:))

Applies a multi-apply API schema to this prim with the given instance name.

[`func addTransformOperation(type: USDTransformOperation.Kind)`](/documentation/USDKit/USDPrim/addTransformOperation(type:))

Adds a transform operation of the given kind to this prim’s transform stack.

### Working with scene-description specs

[`struct Spec`](/documentation/USDKit/USDPrim/Spec)

A handle to a prim definition stored in a layer.

[`struct PseudoRootSpec`](/documentation/USDKit/USDPrim/PseudoRootSpec)

A handle to a layer’s pseudo-root — the implicit parent of all top-level
prims in a layer.

### Structures

[`struct InheritCollection`](/documentation/USDKit/USDPrim/InheritCollection)

Manages inherit composition arcs on a prim.

[`struct PayloadCollection`](/documentation/USDKit/USDPrim/PayloadCollection)

Manages payload composition arcs on a prim.

[`struct SpecializeCollection`](/documentation/USDKit/USDPrim/SpecializeCollection)

Manages specializes composition arcs on a prim.

[`struct VariantSet`](/documentation/USDKit/USDPrim/VariantSet)

Represents a single variant set on a prim.

[`struct VariantSetCollection`](/documentation/USDKit/USDPrim/VariantSetCollection)

Manages variant sets on a prim.

### Instance Properties

[`var hasAuthoredInherits: Bool`](/documentation/USDKit/USDPrim/hasAuthoredInherits)

A Boolean value indicating whether the prim has authored inherit arcs.

[`var hasAuthoredPayloads: Bool`](/documentation/USDKit/USDPrim/hasAuthoredPayloads)

A Boolean value indicating whether the prim has authored payload arcs.

[`var hasAuthoredReferences: Bool`](/documentation/USDKit/USDPrim/hasAuthoredReferences)

A Boolean value indicating whether the prim has authored reference arcs.

[`var hasAuthoredSpecializes: Bool`](/documentation/USDKit/USDPrim/hasAuthoredSpecializes)

A Boolean value indicating whether the prim has authored specializes arcs.

[`var inherits: USDPrim.InheritCollection`](/documentation/USDKit/USDPrim/inherits)

The inherit composition arcs on this prim.

[`var isPrototype: Bool`](/documentation/USDKit/USDPrim/isPrototype)

A Boolean value indicating whether this prim is a prototype that instances share.

[`var payloads: USDPrim.PayloadCollection`](/documentation/USDKit/USDPrim/payloads)

The payload composition arcs on this prim.

[`var prototype: USDPrim`](/documentation/USDKit/USDPrim/prototype)

The prototype that this instance shares, or an invalid prim if this prim
is not an instance.

[`var specializes: USDPrim.SpecializeCollection`](/documentation/USDKit/USDPrim/specializes)

The specializes composition arcs on this prim.

[`var transformOperations: [USDTransformOperation]`](/documentation/USDKit/USDPrim/transformOperations)

The transform operations on this prim, in evaluation order.

[`var variantSets: USDPrim.VariantSetCollection`](/documentation/USDKit/USDPrim/variantSets)

The variant sets on this prim.

### Instance Methods

[`func clearTransformOperations()`](/documentation/USDKit/USDPrim/clearTransformOperations())

Removes all transform operations from the prim’s transform stack.

[`func hasAPISchema(USDToken) -> Bool`](/documentation/USDKit/USDPrim/hasAPISchema(_:))

Returns `true` if this prim has a particular API schema applied.

[`func isSchema(USDToken) -> Bool`](/documentation/USDKit/USDPrim/isSchema(_:))

Returns `true` if this prim has the given type or a more derived type.

[`func makeRelationship(named: USDToken, custom: Bool) -> USDPrim.Relationship`](/documentation/USDKit/USDPrim/makeRelationship(named:custom:))

Creates a relationship with the given name on this prim, or returns the
existing relationship if one already exists.

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

Returns the property at a given path, relative to this prim.

[`func removeAPISchema(USDToken) throws`](/documentation/USDKit/USDPrim/removeAPISchema(_:))

Removes a single-apply API schema from this prim.

[`func removeAPISchema(USDToken, instanceName: USDToken) throws`](/documentation/USDKit/USDPrim/removeAPISchema(_:instanceName:))

Removes a multi-apply API schema from this prim with the given instance name.

[`func transform(at: USDStage.TimeCode) -> USDValue.Matrix4d?`](/documentation/USDKit/USDPrim/transform(at:))

Computes the prim’s composed local transform at the specified time.

### Subscripts

[`subscript(USDToken, as _: Int.Type) -> Int?`](/documentation/USDKit/USDPrim/subscript(_:as:)-127jz)

[`subscript<T>(USDToken, as _: T.Type) -> T?`](/documentation/USDKit/USDPrim/subscript(_:as:)-1frls)

Access or modify the value of a named attribute on this prim.

[`subscript(USDToken, as _: USDArray<UInt>.Type) -> USDArray<UInt>?`](/documentation/USDKit/USDPrim/subscript(_:as:)-2pr71)

[`subscript(USDToken, as _: USDArray<Int>.Type) -> USDArray<Int>?`](/documentation/USDKit/USDPrim/subscript(_:as:)-7uc7b)

[`subscript(USDToken, as _: UInt.Type) -> UInt?`](/documentation/USDKit/USDPrim/subscript(_:as:)-okns)

### Default Implementations

[CustomStringConvertible Implementations](/documentation/USDKit/USDPrim/CustomStringConvertible-Implementations)

## Relationships

### Conforms To

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

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

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

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

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

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

---

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)