<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/Entity/ConfigurationCatalog",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation6EntityC20ConfigurationCatalogV"
  },
  "title" : "Entity.ConfigurationCatalog"
}
-->

# Entity.ConfigurationCatalog

A collection of alternative representations of an entity you can choose from.

```
struct ConfigurationCatalog
```

## Overview

A configuration catalog allows you to create an entity from alternative configurations, such as
different mesh geometries, levels of detail, or material properties.
From these options, you can select the configurations according to how you want that entity to appear.

You can load a configuration catalog from a USD file with variant sets or a `.reality` file with a
configuration catalog.

### Create a configuration catalog

To create a configuration catalog with RealityKit, first set up a configuration set for each category you
want to represent.
A configuration set consists of a name and an array of alternative representations for that category.
For example, a configuration set can include different levels of detail or different material representations
of an entity.

The following example creates a configuration set for the categories `size` and `color`:

```swift
let configurationSets: [Entity.ConfigurationCatalog.ConfigurationSet] = [
    try Entity.ConfigurationCatalog.ConfigurationSet(
        id: "size",
        configurations: [
            Entity.ConfigurationCatalog.Configuration(id: "small"),
            Entity.ConfigurationCatalog.Configuration(id: "big")
        ],
        defaultConfigurationId: "small"
    ),
    try Entity.ConfigurationCatalog.ConfigurationSet(
        id: "color",
        configurations: [
            Entity.ConfigurationCatalog.Configuration(id: "red"),
            Entity.ConfigurationCatalog.Configuration(id: "green"),
        defaultConfigurationId: "green"
    ),
]
```

Use a configuration combination to associate entities that represent specific configuration choices
with a dictionary that describes those selections, as the following example shows:

```swift
let combinations: [Entity.ConfigurationCatalog.ConfigurationCombination] = [
    Entity.ConfigurationCatalog.ConfigurationCombination(
        entity: smallRedEntity,
        configurationSpecifications: ["size" : "small", "color" : "red"]
    ),
    Entity.ConfigurationCatalog.ConfigurationCombination(
        entity: smallGreenEntity,
        configurationSpecifications: ["size" : "small", "color" : "green"]
    ),
    Entity.ConfigurationCatalog.ConfigurationCombination(
        entity: bigRedEntity,
        configurationSpecifications: ["size" : "big", "color" : "red"]
    ),
    Entity.ConfigurationCatalog.ConfigurationCombination(
        entity: bigGreenEntity,
        configurationSpecifications: ["size" : "big", "color" : "green"]
    ),
]
```

Create a catalog from the configuration sets and combinations.

```swift
let configurableEntity = try Entity.ConfigurationCatalog(
   configurationSets: configurationSets,
   combinations: combinations
)
```

Save the catalog to a `.reality` file that your RealityKit app can load.

```swift
try await configurableEntity.write(to: url)
```

### Load an entity with a configuration

The following code example loads a small, red entity from the configuration catalog in the preceding
example.
The entity initializer looks for the catalog to have configuration sets named `size` and `color`,
and the sets to contain configurations named `small` and `red`, respectively.

```swift
func loadSmallRedEntity(from url: URL) async throws -> Entity {
    let catalog = try await Entity.ConfigurationCatalog(from: url)
    return try await Entity(
        from: catalog,
        configurations: ["size": "small", "color": "red"]
    )
}
```

## Topics

### Opening a catalog from a file

[`init(from:)`](/documentation/RealityKit/Entity/ConfigurationCatalog/init(from:))

Loads a configuration catalog from a USD or reality file.

### Defining configuration choices

[`Entity.ConfigurationCatalog.Configuration`](/documentation/RealityKit/Entity/ConfigurationCatalog/Configuration)

A type that represents an alternative that you can choose.

[`Entity.ConfigurationCatalog.ConfigurationSet`](/documentation/RealityKit/Entity/ConfigurationCatalog/ConfigurationSet)

A collection of alternatives to choose from.

[`Entity.ConfigurationCatalog.ConfigurationCombination`](/documentation/RealityKit/Entity/ConfigurationCatalog/ConfigurationCombination)

A type that associates an entity with a combination of configurations.

### Querying available configuration choices

[`configurationSets`](/documentation/RealityKit/Entity/ConfigurationCatalog/configurationSets)

The configuration sets that configure the default prim or entity.

### Creating a configuration catalog from entities

[`init(configurationSets:combinations:)`](/documentation/RealityKit/Entity/ConfigurationCatalog/init(configurationSets:combinations:)-1difa)

Creates a configuration catalog from in-memory entities and an array of configuration sets.

[`init(configurationSets:combinations:)`](/documentation/RealityKit/Entity/ConfigurationCatalog/init(configurationSets:combinations:)-1difa)

Creates a configuration catalog from in-memory entities and an array of configuration sets.

### Saving a configuration catalog to a file

[`write(to:)`](/documentation/RealityKit/Entity/ConfigurationCatalog/write(to:))

Writes the configurations of the configuration catalog to a reality file.

### Writing to a file

[`write(to:options:)`](/documentation/RealityKit/Entity/ConfigurationCatalog/write(to:options:))

Writes the configurations of the configuration catalog to a reality file.


---

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)