<!--
{
  "availability" : [
    "iOS: 14.0.0 -",
    "iPadOS: 14.0.0 -",
    "macCatalyst: 14.0.0 -",
    "macOS: 11.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/ModelDebugOptionsComponent",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation26ModelDebugOptionsComponentV"
  },
  "title" : "ModelDebugOptionsComponent"
}
-->

# ModelDebugOptionsComponent

A component that changes how RealityKit renders its entity to help with
debugging.

```
struct ModelDebugOptionsComponent
```

## Overview

Attaching a `ModelDebugOptionsComponent` to a [`ModelEntity`](/documentation/RealityKit/ModelEntity) tells
RealityKit to change the way it renders that entity based on a specified
[`visualizationMode`](/documentation/RealityKit/ModelDebugOptionsComponent/visualizationMode-swift.property). This
component isolates individual parts of the rendering process, such as the
entity’s transparency or roughness, and displays surface color to help
identify visual anomalies.

To use this component, create a `ModelDebugOptionsComponent` and set its
[`visualizationMode`](/documentation/RealityKit/ModelDebugOptionsComponent/visualizationMode-swift.property) to the
desired value. Then, set the component as the entity’s
`ModelEntity/modelDebugOptions` property:

```swift
if let robot = anchor.findEntity(named: "Robot") as? ModelEntity {
    let component = ModelDebugOptionsComponent(visualizationMode: .normal)
    robot.modelDebugOptions = component
}
```

For more information on the visualization modes supported by
`ModelDebugOptionsComponent`, see
[`ModelDebugOptionsComponent.VisualizationMode`](/documentation/RealityKit/ModelDebugOptionsComponent/VisualizationMode-swift.enum).

### Attach a debug component to an entity

To attach a debug component to a particular entity, traverse the entity tree
while passing the component to each child:

```swift
// Traverse the entity tree to attach a certain debug mode through components.
func attachDebug(entity: Entity, debug: ModelDebugOptionsComponent) {
    entity.components.set(debug)
    for child in entity.children {
        attachDebug(entity: child, debug: debug)
    }
}
// Respond to a button or UI element.
func debugLightingDiffuseButtonCallback() {
    let debugComponent = ModelDebugOptionsComponent(
        visualizationMode: .lightingDiffuse
    )
    attachDebug(entity: model, debug: debugComponent)
}
```

### Attach a debug component to a trait

To attach a debug component based on a trait, traverse the entity tree while
checking for [`HasModel`](/documentation/RealityKit/HasModel) adoption:

```swift
func attachDebug(entity: Entity, debug: ModelDebugOptionsComponent) {
    if let model = entity as? ModelEntity {
        model.visualizationMode = debug
    }
    for child in entity.children {
        attachDebug(entity: child, debug: debug)
    }
}
// Respond to a button or UI element.
func debugLightingDiffuseButtonCallback() {
    let debugComponent = ModelDebugOptionsComponent(
        visualizationMode: .lightingDiffuse
    )
    attachDebug(entity: model, debug: debugComponent)
}
```

## Topics

### Creating model debug options components

[`init(visualizationMode:)`](/documentation/RealityKit/ModelDebugOptionsComponent/init(visualizationMode:))

Creates a component that isolates a portion of the rendering process and
displays it as the entity’s surface texture.

### Setting the visualization mode

[`visualizationMode`](/documentation/RealityKit/ModelDebugOptionsComponent/visualizationMode-swift.property)

The part of the rendering process to display as the entity’s surface
texture.

[`ModelDebugOptionsComponent.VisualizationMode`](/documentation/RealityKit/ModelDebugOptionsComponent/VisualizationMode-swift.enum)

A mode that specifies the portion of the rendering process to isolate
and display for debugging.


---

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)