usd-editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

USD Editor

Description and Goals

说明与目标

This skill guides safe, minimal edits to USD ASCII (.usda) files and the proper use of USD command-line tools. It focuses on preserving stage structure, using correct specifiers and property types, and avoiding composition mistakes while making targeted changes.

本skill指导用户对USD ASCII（.usda）文件进行安全、最小化的编辑，并正确使用USD命令行工具。重点在于保留场景（stage）结构，使用正确的说明符（specifier）和属性类型，在进行针对性修改时避免合成错误。

Goals

目标

Make precise edits without disrupting existing USD composition
Preserve file formatting and authoring style
Use correct prim specifiers, property types, and relationships
Avoid common USD pitfalls (wrong paths, missing xformOpOrder, broken connections)
Guide safe manipulation and inspection of USD assets using the command-line tools

在不破坏现有USD合成逻辑的前提下进行精准编辑
保留文件格式和编写风格
使用正确的Prim说明符、属性类型和关系
避免常见的USD陷阱（错误路径、缺失xformOpOrder、连接断裂）
指导用户安全地使用命令行工具操作和检查USD资产

What This Skill Should Do

本Skill的适用场景

When asked to modify a .usda file, this skill should:

Inspect the stage structure - Identify root prims, scopes, and relevant paths.
Choose the correct specifier - Use
```
over
```
for edits to existing prims,
```
def
```
for new prims.
Edit only what is necessary - Preserve unrelated content and formatting.
Respect composition - Avoid changing subLayers, references, or variants unless asked.
Validate connections and paths - Ensure
```
SdfPath
```
targets are valid and type-compatible.

If the change is material- or shader-related for RealityKit, prefer the

shadergraph-editor

skill for node-specific guidance.

当需要修改.usda文件时，本Skill应：

检查场景结构 - 识别根Prim、作用域（scope）和相关路径。
选择正确的说明符 - 对现有Prim进行编辑时使用
```
over
```
，创建新Prim时使用
```
def
```
。
仅编辑必要内容 - 保留无关内容和格式。
遵循合成规则 - 除非明确要求，否则不要修改子层（subLayers）、引用（references）或变体。
验证连接和路径 - 确保
```
SdfPath
```
目标有效且类型兼容。

如果是针对RealityKit的材质或着色器相关修改，建议使用

shadergraph-editor

skill获取节点相关的指导。

Quick Start Workflow

快速开始流程

Locate the prim path you need to edit (search by prim name or
```
SdfPath
```
).
Determine whether you should
```
over
```
an existing prim or
```
def
```
a new one.
Apply the smallest possible change (attribute value, relationship target, or child prim).
If adding transforms, update
```
xformOpOrder
```
to match your new ops.
Re-check any paths or connections you touched.

定位需要编辑的Prim路径（通过Prim名称或
```
SdfPath
```
搜索）。
确定是对现有Prim使用
```
over
```
还是创建新Prim使用
```
def
```
。
应用最小化的修改（属性值、关系目标或子Prim）。
如果添加变换操作，更新
```
xformOpOrder
```
以匹配新增的操作。
重新检查所有涉及的路径或连接。

Information About the Skill

Skill相关信息

Core Concepts

核心概念

Stage and Layer

场景（Stage）与层（Layer）

A USD stage is composed of one or more layers. A .usda file is a single ASCII layer that can sublayer or reference others.

USD场景由一个或多个层组成。.usda文件是单个ASCII层，可以包含子层或引用其他层。

Prim and Specifier

Prim与说明符（Specifier）

A prim is a scene graph node. Specifiers control behavior:

def

creates,

over

modifies,

class

defines a reusable template.

Prim是场景图节点。说明符控制其行为：

def

用于创建新Prim，

over

用于修改现有Prim，

class

用于定义可复用的模板。

Properties

属性（Properties）

Attributes store typed data; relationships (

rel

) point to other prims.

属性（Attributes）存储类型化数据；关系（relationships，缩写为

rel

）指向其他Prim。

Composition Arc

合成弧（Composition Arc）

Mechanisms like sublayers, references, and payloads that bring other USD data into the stage.

诸如子层、引用和负载（payloads）之类的机制，用于将其他USD数据引入场景。

SdfPath

A path to a prim or property, written like

</Root/Child>

</Root/Mat.outputs:surface>

指向Prim或属性的路径，格式如

</Root/Child>

或

</Root/Mat.outputs:surface>

。

List Editing

列表编辑（List Editing）

USD list ops (

prepend

append

delete

add

) modify lists without replacing them.

USD列表操作（

prepend

、

append

、

delete

、

add

）用于修改列表而非替换整个列表。

Variants

变体（Variants）

Variant sets provide alternative content branches for a prim.

变体集为Prim提供可选的内容分支。

Time Samples

时间采样（Time Samples）

Animated or time-varying data stored in

timeSamples

dictionaries.

存储在

timeSamples

字典中的动画或时变数据。

Reference Tables

参考表格

Reference	When to Use
`usd-syntax`	When you need a refresher on .usda syntax, values, and path formats.
`prims-properties`	When adding or editing prims, attributes, or relationships.
`composition-variants`	When touching sublayers, references, payloads, or variant sets.
`transforms-units`	When editing transforms, xformOps, or stage units/up axis metadata.
`time-samples`	When modifying animated/time-sampled properties.
`command-line-tools`	When you need a quick reference for common USD command-line tools.
`usdcat`	When converting, flattening, or inspecting USD files.
`usdchecker`	When validating USD or USDZ assets, including RealityKit-focused checks.
`usdrecord`	When rendering images from USD files.
`usdtree`	When inspecting the prim hierarchy of a USD file.
`usdzip`	When creating or inspecting USDZ packages.
`usdcrush`	When compressing USD or USDZ assets for size.
`usdextract`	When extracting files from USD-compatible packages.

参考文档	使用场景
`usd-syntax`	当你需要回顾.usda语法、值和路径格式时。
`prims-properties`	当添加或编辑Prim、属性或关系时。
`composition-variants`	当涉及子层、引用、负载或变体集时。
`transforms-units`	当编辑变换、xformOp或场景单位/上轴元数据时。
`time-samples`	当修改动画/时间采样属性时。
`command-line-tools`	当你需要USD常用命令行工具的快速参考时。
`usdcat`	当转换、展平或检查USD文件时。
`usdchecker`	当验证USD或USDZ资产（包括针对RealityKit的检查）时。
`usdrecord`	当从USD文件渲染图像时。
`usdtree`	当检查USD文件的Prim层次结构时。
`usdzip`	当创建或检查USDZ包时。
`usdcrush`	当压缩USD或USDZ资产以减小体积时。
`usdextract`	当从USD兼容包中提取文件时。

Implementation Patterns

实现模式

Override an Existing Prim

覆盖现有Prim

usda

over "Mesh"
{
    token visibility = "invisible"
}

usda

over "Mesh"
{
    token visibility = "invisible"
}

Add a Simple Xform with Translate

添加带平移的简单变换节点

usda

def Xform "Pivot"
{
    double3 xformOp:translate = (0.0, 0.1, 0.0)
    uniform token[] xformOpOrder = ["xformOp:translate"]
}

usda

def Xform "Pivot"
{
    double3 xformOp:translate = (0.0, 0.1, 0.0)
    uniform token[] xformOpOrder = ["xformOp:translate"]
}

Bind a Material Relationship

绑定材质关系

usda

rel material:binding = </Materials/Mat>

usda

rel material:binding = </Materials/Mat>

Pitfalls and Checks

常见陷阱与检查项

Don't replace a prim with
```
def
```
when you only need an
```
over
```
.
Keep
```
xformOpOrder
```
consistent with the ops you add or remove.
Verify
```
SdfPath
```
targets exist and match the expected property type.
Avoid editing composition arcs unless explicitly requested.
Preserve existing formatting and comments to minimize diff noise.

当只需要
```
over
```
时，不要用
```
def
```
替换现有Prim。
确保
```
xformOpOrder
```
与你添加或移除的操作保持一致。
验证
```
SdfPath
```
目标是否存在，并与预期的属性类型匹配。
除非明确要求，否则避免编辑合成弧。
保留现有格式和注释，以减少差异对比的干扰。