usd-editor

USD 编辑器

快速入门

使用此技能进行最小限度的文本级 USD 或 USDA 编辑，以及通过命令行检查、转换、打包、渲染和验证 USD。尽量缩小改动，并保留现有组合关系，除非任务明确要求另作处理。

当场景、几何体、变换、动画或材质由已创作的 Reality Composer Pro 或 USD 内容负责时，应将这些已创作内容作为事实来源。使用 Swift 和 RealityKit 加载或调整运行时状态；除非请求明确要求以程序方式生成，否则不要在 Swift 中重新创建已创作的 USD 内容。

如果 Swift 代码需要在进程内使用 USDStage、USDPrim 或 USDLayer 打开、编辑、观察或导出场景阶段，请切换到 $usdkit-runtime-developer。

如果改动针对 RealityKit 的材质或着色器，请优先使用 shadergraph-editor。

需要时加载参考资料

参考资料	适用场景
usd-syntax	需要重温 .usda 语法、值和路径格式时。
prims-properties	添加或编辑 prim、属性或关系时。
composition-variants	涉及子层、引用、负载或变体集时。
transforms-units	编辑变换、xformOps、场景阶段单位或 up-axis 元数据时。
time-samples	修改动画属性或时间采样属性时。
command-line-tools	需要快速查阅常用 USD 命令行工具时。
usdcat	转换、扁平化或检查 USD 文件时。
usdchecker	验证 USD 或 USDZ 资源时，包括针对 RealityKit 的检查。
usdrecord	从 USD 文件渲染图像时。
usdtree	检查 USD 文件的 prim 层级结构时。
usdzip	创建或检查 USDZ 包时。
usdedit	需要使用官方文本编辑工作流编辑可读 USD 文件时。
visionos-runtime-loading.md	问题涉及已创作的 USD 或 USDZ 在 visionOS 应用中的实际加载方式和行为时。
apple-runtime-boundaries.md	决定应编辑已创作的 USD / Reality Composer Pro 内容、通过 RealityKit 加载，还是针对 Apple 平台进行验证时。

工作流

1. 确定内容归属：已创作的 USD / Reality Composer Pro 资源、包资源，还是仅限运行时的 Swift 生成内容。
2. 根据风险，在编辑前使用 usdtree、usdcat --loadOnly 或 usdcat --flatten 检查场景阶段。
3. 找出负责该意见的准确 prim 路径和图层。
4. 有意选择 over、def 或列表编辑。
5. 应用所需的最小改动。
6. 重新检查受影响的路径、变换或组合边。
7. 运行与改动相匹配的最精简验证工具；随后对要发布的 visionOS USDZ 资源运行 usdchecker --arkit。

注意事项

• 如果正确的编辑方式是 over，不要用 def 替换 prim。
• 除非明确要求，否则避免更改组合弧。
• 如果 RealityKit 应用使用 Entity(named:in:)、Entity(contentsOf:withName:) 或生成的 Reality Composer Pro 内容包加载资源，应优先修复已创作的资源并验证包，而不是构建并行的 Swift 场景图。
• 不要直接手动编辑 .usdz 包；应先检查或解包，再编辑源图层、重新构建包并验证结果。
• 使用 usdchecker --arkit --strict 验证最终的 Apple 平台 USDZ 输出，不要只做源图层解析检查。
• 尽可能保留现有格式和注释。

输出要求

请提供：

• 编辑的 prim 或路径
• 使用的参考文件
• 所做 USD 更改的具体类别
• 使用的验证步骤
• 如有需要，转交给 $usdkit-runtime-developer、shadergraph-editor 或运行时测试