# reality-usda-shader-graph

> Use this skill when the user asks to read, understand, or modify USD shader graph structure in .usda/.usdz files, analyze material networks, modify shader parameters, or validate file integrity for RealityKit.

- Author: xander
- Repository: XanderXu/RealitySkills
- Version: 20260123110406
- Stars: 4
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/XanderXu/RealitySkills
- Web: https://mule.run/skillshub/@@XanderXu/RealitySkills~reality-usda-shader-graph:20260123110406

---

---
name: reality-usda-shader-graph
description: Use this skill when the user asks to read, understand, or modify USD shader graph structure in .usda/.usdz files, analyze material networks, modify shader parameters, or validate file integrity for RealityKit.
---

# Reality USDA Shader Graph

## Overview

Read, understand, and modify USD shader graph structure in .usda/.usdz files. Analyze material networks, modify shader parameters, and validate file integrity for RealityKit.

## Quick Start

**Read shader graph:**

```python
stage = Usd.Stage.Open("model.usda")
material = UsdShade.Material(stage.GetPrimAtPath("/Root/Lambert1"))
surface, _ = material.GetSurfaceOutput().GetConnectedSource()
```

**Modify parameter:**

```python
shader = UsdShadeShader(stage.GetPrimAtPath("/Root/Lambert1/PreviewSurface"))
roughness = shader.GetInput("roughness")
if roughness and not roughness.HasConnectedSource():
    roughness.Set(0.8)
stage.GetRootLayer().Save()
```

See `scripts/USD_SCRIPT.md` for complete implementations.

## Core Concepts

### USD Shader Graph Structure (DAG)

```
UsdShade.Material → UsdPreviewSurface → UsdUVTexture → UsdTransform2d → UsdPrimvarReader_float2
```

**Connection Types:**
- **Value**: `float inputs:roughness = 0.5`
- **Shader**: `inputs:diffuseColor.connect = </Texture.outputs:rgb>`
- **Terminal**: `outputs:surface.connect = </Shader.outputs:surface>`

**Data Flow:** Mesh (UVs) → PrimvarReader → Transform2d → UVTexture → PreviewSurface → Material

## Workflow Decision Tree

### 1) Read shader graph
Open stage → Find Material nodes → Get surface output → Traverse graph recursively

### 2) Modify parameters
Open edit mode → Find material → Get shader inputs → Set values → Save stage

### 3) Create connections
Define shader nodes → Set shader ID → Connect outputs to inputs → Link to material surface

### 4) Validate integrity
Check surface output → Verify connections → Validate type compatibility → Check texture paths

## Common Shader Nodes

- **UsdPreviewSurface**: PBR shader (`diffuseColor`, `roughness`, `metallic`, `normal`, `emissiveColor`, `opacity`, `ior`, `clearcoat`, `occlusion`) → `surface`, `displacement`
- **UsdUVTexture**: Texture sampling (`file`, `st`, `wrapS`, `wrapT`, `scale`, `bias`) → `rgb`, `r`, `g`, `b`, `a`
- **UsdPrimvarReader_float2**: Read vertex data (`varname`) → `result`
- **UsdTransform2d**: UV transform (`in`, `rotation`, `scale`, `translation`) → `result`

## Best Practices & Common Issues

**Best Practices:**
- Check connections before modifying: use `GetInput()` not `CreateInput()`
- Validate material structure before saving
- Use relative paths for USDZ textures

**Common Issues:**
- **Normal maps fail** → Set `scale = (1, 1, 1, 1)`
- **Connections break** → Use `GetInput()` for existing parameters
- **Textures not loading** → Verify files in USDZ archive

## Requirements

- **visionOS**: 1.0+ (UsdPreviewSurface), 2.0+ (MaterialX)
- **Python**: 3.8+ with `usd-core` or `pxr`
- **USD**: 20.08+ (recommended 23.05+)

## Technical Reference

See `references/TECHNICAL_GUIDE.md` for architecture, concepts, and troubleshooting.