shadergraph-editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ShaderGraph Editor

ShaderGraph编辑器

Description and Goals

说明与目标

This skill provides guidance for manually editing USD ASCII (.usda) files to create and modify RealityKit materials and ShaderGraph networks. It covers material prims, shader nodes, connections, and material binding patterns.

本技能为手动编辑USD ASCII（.usda）文件以创建和修改RealityKit材质及ShaderGraph网络提供指导。内容涵盖材质prim、着色器节点、连接以及材质绑定模式。

Goals

目标

Enable developers to create custom materials in USD format
Guide manual editing of .usda files for ShaderGraph networks
Help troubleshoot material and shader node issues
Support creation of complex material networks
Ensure proper material binding to geometry

帮助开发者创建USD格式的自定义材质
指导手动编辑.usda文件以构建ShaderGraph网络
协助排查材质与着色器节点相关问题
支持创建复杂的材质网络
确保材质与几何体正确绑定

What This Skill Should Do

本技能的功能

When editing ShaderGraph materials in .usda files, this skill should:

Guide material creation - Show how to define material prims and surface shaders
Explain shader nodes - Demonstrate how to add and configure shader node prims
Show connections - Explain how to connect node outputs to shader inputs
Handle material binding - Show how to bind materials to geometry
Troubleshoot issues - Help identify and fix common material problems
Prefer sample graphs when available - If the requested effect matches an example in
```
samples/
```
, start from that file and point the user to it.

Load the appropriate reference file from the tables below for detailed usage, code examples, and best practices.

在.usda文件中编辑ShaderGraph材质时，本技能可：

指导材质创建 - 展示如何定义材质prim和表面着色器
解释着色器节点 - 演示如何添加和配置着色器节点prim
展示连接方式 - 说明如何将节点输出连接到着色器输入
处理材质绑定 - 展示如何将材质绑定到几何体
排查问题 - 帮助识别并修复常见的材质问题
优先使用示例图 - 如果所需效果与
```
samples/
```
中的示例匹配，请以该文件为基础，并指引用户查看。

请从下方表格中加载对应的参考文件，以获取详细用法、代码示例及最佳实践。

Quick Start Workflow

快速开始流程

Before building a new effect from scratch, check

samples/

for a close match and adapt it.

Open the
```
.usda
```
file in a text editor.
Find or create a
```
def Material "MaterialName"
```
block in the correct scope.
Define a
```
def Shader "Surface"
```
prim and connect
```
outputs:surface
```
to the material output.
Add shader node prims (
```
def Shader
```
) for textures and math operations.
Connect node outputs to shader inputs with the
```
.connect
```
syntax.
Set constant values on inputs that are not connected.
Bind the material to geometry with
```
rel material:binding
```
.

在从头构建新效果之前，请先检查

samples/

目录中是否有相近的示例并进行适配。

在文本编辑器中打开.usda文件。
在正确的作用域中找到或创建
```
def Material "MaterialName"
```
块。
定义
```
def Shader "Surface"
```
prim，并将
```
outputs:surface
```
连接到材质输出。
添加用于纹理和数学运算的着色器节点prim（
```
def Shader
```
）。
使用
```
.connect
```
语法将节点输出连接到着色器输入。
为未连接的输入设置常量值。
使用
```
rel material:binding
```
将材质绑定到几何体。

Information About the Skill

技能相关信息

Core Concepts

核心概念

Material Prim

材质Prim

The root of a material definition in USD. Contains the material structure and connects to a surface shader.

USD中材质定义的根节点，包含材质结构并连接到表面着色器。

Surface Shader

表面着色器

Shader

prim that drives

outputs:surface

. Typically uses

UsdPreviewSurface

or RealityKit-specific shader identifiers.

驱动

outputs:surface

的

Shader

prim。通常使用

UsdPreviewSurface

或RealityKit专用的着色器标识符。

Shader Nodes

着色器节点

Additional

Shader

prims for textures, transforms, and math operations. Each node has an

info:id

that identifies its type.

用于纹理、变换和数学运算的额外

Shader

prim。每个节点都有一个

info:id

用于标识其类型。

Connections

连接

.connect

syntax links between node outputs and shader inputs. Creates the material network graph.

使用

.connect

语法链接节点输出与着色器输入，构建材质网络图形。

Material Binding

材质绑定

rel material:binding

on a mesh prim associates the material with geometry.

网格prim上的

rel material:binding

用于将材质与几何体关联。

info:id

The shader node identifier used by USD and RealityKit to determine the node's behavior.

USD和RealityKit用于确定节点行为的着色器节点标识符。

Reference Files

参考文件

Reference	When to Use
`REFERENCE.MD`	When looking for ShaderGraph node and material reference guide.

参考文件	使用场景
`REFERENCE.MD`	查找ShaderGraph节点和材质参考指南时使用。

Samples (Common Effects)

示例（常见效果）

This repo includes common ShaderGraph examples in

samples/

. When a user asks for a specific visual effect, start by selecting the closest sample and tell them to open it so you can align on the exact look and parameters.

```
samples/ShaderSamplesScene.usda
```
— A single scene that references the other samples for quick preview/inspection.
```
samples/OutlineShader.usda
```
— Mesh outline via duplicated mesh + vertex expansion (geometry modifier) and
```
cullMode = "front"
```
.
```
samples/FresnelShader.usda
```
— Fresnel/rim glow (emissive) with tunable color and falloff.
```
samples/GradientShader.usda
```
— Near/far color gradient driven by camera distance.
```
samples/LavaShader.usda
```
— Animated lava emissive using 3D noise + time.
```
samples/DissolveShader.usda
```
— Animated dissolve with noise threshold and emissive edge.

samples/VertexDisplacementShader.usda

— Animated vertex displacement using

outputs:realitykit:vertex

(geometry modifier).

```
samples/NormalCorrectionShader.usda
```
— Vertex displacement with corrected normals for cleaner lighting.
```
samples/ToonShader.usda
```
— Toon shading using diffuse/specular ramp textures.
```
samples/PBRToonShader.usda
```
— PBR-to-toon node graph (banding/quantization) applied to an existing material graph.

Some samples reference external assets (for example ramp textures or a referenced

.usdz

). When copying a sample into your project, keep or update those asset paths as needed.

本仓库在

samples/

目录中包含常见的ShaderGraph示例。当用户询问特定视觉效果时，请优先选择最接近的示例，并告知用户打开该文件，以便确认具体的外观和参数。

```
samples/ShaderSamplesScene.usda
```
— 一个包含其他所有示例引用的场景文件，用于快速预览/检查。
```
samples/OutlineShader.usda
```
— 通过复制网格+顶点扩展（几何体修改器）和
```
cullMode = "front"
```
实现的网格轮廓效果。
```
samples/FresnelShader.usda
```
— 具有可调颜色和衰减效果的菲涅尔/边缘发光（自发光）。
```
samples/GradientShader.usda
```
— 由相机距离驱动的近/远颜色渐变。
```
samples/LavaShader.usda
```
— 使用3D噪声+时间实现的动画熔岩自发光效果。
```
samples/DissolveShader.usda
```
— 带有噪声阈值和自发光边缘的动画溶解效果。
```
samples/VertexDisplacementShader.usda
```
— 使用
```
outputs:realitykit:vertex
```
（几何体修改器）实现的动画顶点位移。
```
samples/NormalCorrectionShader.usda
```
— 带有法线校正的顶点位移，以获得更清晰的光照效果。
```
samples/ToonShader.usda
```
— 使用漫反射/高光渐变纹理实现的卡通着色效果。
```
samples/PBRToonShader.usda
```
— 应用于现有材质图的PBR转卡通节点图（带色阶/量化效果）。

部分示例引用了外部资源（例如渐变纹理或引用的.usdz文件）。将示例复制到项目中时，请根据需要保留或更新这些资源路径。

Implementation Patterns

实现模式

Basic Red PBR Material (UsdPreviewSurface)

基础红色PBR材质（UsdPreviewSurface）

usda

def Material "RedMaterial"
{
    token outputs:surface.connect = <./Surface.outputs:surface>

    def Shader "Surface"
    {
        uniform token info:id = "UsdPreviewSurface"
        color3f inputs:diffuseColor = (1, 0, 0) # Red
        float inputs:roughness = 0.2
        float inputs:metallic = 0.0
        token outputs:surface
    }
}

usda

def Material "RedMaterial"
{
    token outputs:surface.connect = <./Surface.outputs:surface>

    def Shader "Surface"
    {
        uniform token info:id = "UsdPreviewSurface"
        color3f inputs:diffuseColor = (1, 0, 0) # Red
        float inputs:roughness = 0.2
        float inputs:metallic = 0.0
        token outputs:surface
    }
}

Texture-Mapped Material

纹理映射材质

usda

def Material "TexturedMaterial"
{
    token outputs:surface.connect = <./Surface.outputs:surface>

    def Shader "Surface"
    {
        uniform token info:id = "UsdPreviewSurface"
        color3f inputs:diffuseColor.connect = <../DiffuseTexture.outputs:rgb>
        token outputs:surface
    }

    def Shader "DiffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @textures/wood_albedo.png@
        float2 inputs:st.connect = <../PrimvarReader.outputs:result>
        float3 outputs:rgb
    }

    def Shader "PrimvarReader"
    {
        uniform token info:id = "UsdPrimvarReader_float2"
        string inputs:varname = "st" # Name of UV set on mesh
        float2 outputs:result
    }
}

usda

def Material "TexturedMaterial"
{
    token outputs:surface.connect = <./Surface.outputs:surface>

    def Shader "Surface"
    {
        uniform token info:id = "UsdPreviewSurface"
        color3f inputs:diffuseColor.connect = <../DiffuseTexture.outputs:rgb>
        token outputs:surface
    }

    def Shader "DiffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @textures/wood_albedo.png@
        float2 inputs:st.connect = <../PrimvarReader.outputs:result>
        float3 outputs:rgb
    }

    def Shader "PrimvarReader"
    {
        uniform token info:id = "UsdPrimvarReader_float2"
        string inputs:varname = "st" # Name of UV set on mesh
        float2 outputs:result
    }
}

RealityKit-Specific Nodes

RealityKit专用节点

usda

def Material "UnlitMaterial"
{
    token outputs:surface.connect = <./UnlitSurface.outputs:surface>

    def Shader "UnlitSurface"
    {
        # Identifier may vary based on RealityKit version/export
        uniform token info:id = "ND_realitykit_unlit_surfaceshader"
        color3f inputs:color = (0, 1, 0)
        token outputs:surface
    }
}

usda

def Material "UnlitMaterial"
{
    token outputs:surface.connect = <./UnlitSurface.outputs:surface>

    def Shader "UnlitSurface"
    {
        # Identifier may vary based on RealityKit version/export
        uniform token info:id = "ND_realitykit_unlit_surfaceshader"
        color3f inputs:color = (0, 1, 0)
        token outputs:surface
    }
}

Pitfalls and Checks

注意事项与检查项

Ensure
```
outputs:surface.connect
```
is present on the material.
Verify
```
info:id
```
values match the expected node identifiers.
Confirm all
```
.connect
```
paths point to valid outputs.
Provide a
```
PrimvarReader
```
when using UV textures.
Bind materials to geometry with
```
rel material:binding
```
.

确保材质上存在
```
outputs:surface.connect
```
。
验证
```
info:id
```
值与预期的节点标识符匹配。
确认所有
```
.connect
```
路径指向有效的输出。
使用UV纹理时需提供
```
PrimvarReader
```
。
使用
```
rel material:binding
```
将材质绑定到几何体。