A collection of alternative representations of an entity you can choose from.
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"]
)
}
```
Creates a configuration catalog from in-memory entities and a dictionary of configuration sets.
- Parameters:
- configurationSets: The configuration choices that the configuration catalog presents.
Each key needs to match the ID of the configuration set value it maps to.
- combinations: The combinations of in-memory entities and configurations that can
address them. The keys you use in
``ConfigurationCombination/configurationSpecifications`` need to match
IDs of configuration sets from the `configurationSets` argument.
The values you use in
``ConfigurationCombination/configurationSpecifications`` need to match
IDs of configurations from the `configurationSets` argument.
There needs to be one ``ConfigurationCombination`` for each possible combination
of configurations.
- Returns: A configuration catalog that maintains the provided entities in memory.
Creates a configuration catalog from in-memory entities and an array of configuration sets.
- Parameters:
- configurationSets: The configuration choices that the configuration catalog presents.
Each configuration set needs to have a unique ID from all others.
The configuration catalog stores the array as the `configurationSets` dictionary
property and doesn't preserve its order.
- combinations: The combinations of in-memory entities and the configurations that can
address them.
The keys you use in
``ConfigurationCombination/configurationSpecifications`` need to match
IDs of configuration sets from the `configurationSets` argument.
The values you use in
``ConfigurationCombination/configurationSpecifications`` need to match
IDs of configurations from the `configurationSets` argument.
There needs to be one ``ConfigurationCombination`` for each possible combination
of configurations.
- Returns: A configuration catalog that maintains the provided entities in memory.
get · iOS 18.0+
configurationSets
TypeScript
get configurationSets(): Promise<Record<string, Entity_ConfigurationCatalog_ConfigurationSet>>
Swift declaration
var configurationSets: [String : Entity.ConfigurationCatalog.ConfigurationSet] { get }
The configuration sets that configure the default prim or entity.
The keys are configuration set IDs, and the values are the corresponding configuration sets.
Writes the configurations of the configuration catalog to a reality file.
Another configuration catalog instance can open the `.reality` file for reading.
- Parameters:
- url: The destination where the configuration catalog writes the `.reality` file.
- options: Options for writing the `.reality` file.
method · iOS 18.0+
write
TypeScript
writeTo(url: string): Promise<void>
Swift declaration
@MainActor func write(to url: URL) async throws
Writes the configurations of the configuration catalog to a reality file.
Another configuration catalog instance can open the `.reality` file for reading.
- Parameters:
- url: The destination where the configuration catalog writes the `.reality` file.
