📦 Shadergraph Editor — 着色器图编辑器

• 指导如何加载并在运行时控制 ShaderGraphMaterial
• 协助排查材质图、提升输入以及导出资源的问题
• 支持在高级场景下检视 USD 与 MaterialX，但不将其视为主要工作流
• 当仓库示例接近需求时，指引用户直接参考

本技能应做什么 使用 Shader Graph 材质时，本技能应： 1. 默认使用 Reality Composer Pro —— 将 Shader Graph 编辑器视为主要创作方式。

• 指导节点选择 —— 帮助挑选正确的 RealityKit surface、geometry、texture 与 math 节点以实现效果。
• 解释运行时集成 —— 展示被提升的输入如何映射到 ShaderGraphMaterial 参数。
• 排查导出文件 —— 仅在调试、互操作或资源审查需要时才检视导出的 USD 与 MaterialX。
• 合理跳转 —— 若任务本质是 prims、组合或文本级 USD 创作，则转交 usd-editor。
• 优先使用示例图 —— 若所需效果与 samples/ 中的示例匹配，则基于该文件开始并指引用户。

加载下方表格中的对应参考文件，可查看详细用法、代码示例与最佳实践。

快速开始工作流 从零搭建新效果前，先检查 samples/ 是否有近似示例并据此修改。 1. 在 Reality Composer Pro 的 Shader Graph 编辑器中创建或打开材质。

• 选择合适的 RealityKit surface 节点，并添加实现效果所需的图节点。
• 将需要在运行时修改的输入提升。
• 将材质保存在随 App 分发的 Reality Composer Pro 资源包内。
• 运行时用 ShaderGraphMaterial 加载该材质。
• 当体验需要动态控制时，通过运行时参数 API 更新被提升的输入。
• 仅在需要调试已创作的图或与其他资产工具互操作时，才检视导出的 USD 与 MaterialX。

技能信息 ### 核心概念 #### Material Prim

Reality Composer Pro 将 Shader Graph 材质导出为基于 USD 的资源，但默认应在 Shader Graph 编辑器中创作，而非手写文本。

Shader Graph 创作

Shader Graph 材质在 Reality Composer Pro 中以可视化方式组成。使用 Apple 文档中针对 Shader Graph 的 RealityKit 专用节点，如 surface 与 geometry modifier 节点。

提升输入与运行时控制

被提升的输入允许 App 在加载材质后修改参数，这是 Apple 官方支持的运行时自定义工作流。

导出的 USD 与 MaterialX

导出资产可能包含 USD 与 MaterialX 表示。将这些文件视为调试或互操作时的实现产物，而非主要创作界面。

示例与互操作边界

仓库中的示例是不错的起点，但属于仓库自有示例。除非 Apple 直接文档说明，否则不要将导出的 info:id 字符串或 USD 图结构视为稳定的 Apple API。

参考文件

| 参考文件 | 使用场景 | |-----------|-------------| | REFERENCE.MD | 查阅 ShaderGraph 节点与材质参考指南时。 |

示例（常见效果）

仓库在 samples/ 中包含常见 ShaderGraph 示例。当用户请求特定视觉效果时，先挑选最接近的示例，并告知用户打开以便对齐外观与参数。

• samples/ShaderSamplesScene.usda —— 单一场景，引用其他示例以便快速预览/检查。
• samples/OutlineShader.usda —— 通过复制网格 + 顶点扩张（geometry modifier）与 cullMode = "front" 实现描边。
• samples/FresnelShader.usda —— 带可调颜色与衰减的 Fresnel/边缘发光（emissive）。
• samples/GradientShader.usda —— 基于相机距离的近远颜色渐变。
• samples/LavaShader.usda —— 使用 3D 噪声 + 时间实现的熔岩发光动画。
• samples/DissolveShader.usda —— 带噪声阈值与发光边缘的溶解动画。
• samples/VertexDisplacementShader.usda —— 使用 outputs:realitykit:vertex（geometry modifier）的顶点位移动画。
• samples/NormalCorrectionShader.usda —— 带法线修正的顶点位移，使光照更干净。
• samples/ToonShader.usda —— 使用漫反射/镜面渐变纹理的卡通着色。
• samples/PBRToonShader.usda —— 在已有材质图上应用 PBR-to-toon 节点图（分阶/量化）。

部分示例引用外部资产（如渐变纹理或引用的 .usdz）。将示例复制到项目时，按需保留或更新这些资源路径。

实现模式

推荐创作流程

• 在 Reality Composer Pro 中从 Shader Graph 材质开始。
• 使用 Apple 文档中的 RealityKit Shader Graph 节点（如 surface 节点与 geometry modifier 节点）实现所需效果。
• 提升任何需要在运行时改变的输入。
• 在 App 代码中用 ShaderGraphMaterial 加载材质。
• 运行时通过参数 API 修改被提升的值，而非直接编辑导出的 USD。

何时适合查看原始 USD

• 材质加载或渲染不符合预期时，检查导出文件。
• 调试图转换问题时，将仓库示例与导出资产对比。
• 若任务本质是 USD 结构、路径或组合，则将 prim 级编辑转交 usd-editor。

常见陷阱与检查

• 不要将 UsdPreviewSurface 网络等同于 Reality Composer Pro Shader Graph 材质。
• 不要依赖未文档化的导出 info:id 字符串作为稳定的 Apple API。
• 当 App 需要动态控制时，优先使用提升输入与运行时参数更新，而非直接文本编辑。
• 涉及 prim 路径、组合弧线或其他文本级 USD 创作任务时，使用 usd-editor。
• 将示例视为仓库示例，而非详尽的 Apple 官方模式参考。