.USD File Format – USDA text

Header line and encoding

The first line is #usda, a space and the version as MAJOR.MINOR with an optional .PATCH, normally #usda 1.0. A reader must accept earlier versions with the same major number. Spline tangent algorithm tokens need version 1.1 or later.

The text is UTF-8; the “a” of the name is historical. Lines may end with CR, LF or CR LF. Spaces and tabs separate tokens, and statements are separated by a line break or a semicolon.

Comments, names and literals

The grammar does not tell integers from real numbers; a value takes its type from the attribute or field it is assigned to.

Layer metadata

After the header, an optional parenthesised block holds the layer’s metadata: a documentation string on its own, doc = "…", subLayers = [@a.usda@, @b.usda@ (offset = 10; scale = 2)], relocates, and any other field as name = value, such as defaultPrim, upAxis, metersPerUnit, timeCodesPerSecond, startTimeCode and endTimeCode. Then come the root prims.

Prims

def Mesh "Floor" (
    kind = "component"
    references = @floor.usda@</Floor>
)
{
    point3f[] points = [(0, 0, 0), (1, 0, 0), (1, 0, 1), (0, 0, 1)]
}

A prim begins with its specifier: def defines it, over only overrides what another layer defines, and class makes a class for other prims to inherit. An optional type name such as Xform or Mesh follows, then the name in quotes, optional metadata in parentheses and the body in braces, which holds properties, child prims, variant sets and reorder statements.

Prim metadata includes doc, kind, references, payload, inherits, specializes, variants (the selected variant of each set), variantSets, and any other field as name = value. A reference or payload item is an asset path, a prim path, or both (@car.usdz@</models/window>), optionally followed by parameters in parentheses: a layer offset (offset and scale) for both, and customData for references.

Attributes

An attribute is declared as an optional custom, an optional uniform (the value does not change over time; the default is varying), a type name with [] for an array, and a name, then optionally = and a default value or None, and optional metadata in parentheses. Other forms add to it:

Value types come from the specification’s foundational data types, such as bool, int, float, double, half, string, token, asset, timecode, double3, matrix4d, quatf, and role names such as point3f, normal3f, vector3f, color3f and texCoord2f.

Relationships

rel or custom rel and a name declares a relationship, optionally assigned None, one path or a list of paths: rel material:binding = </Looks/Wood>.

List operations

Fields that hold lists, such as references, inherits, apiSchemas and relationship targets, can be set outright or edited. The prefixes prepend, append and delete add to the front, add to the back or remove from what weaker layers say; add and reorder are legacy forms. Without a prefix the list replaces the weaker ones.

Variant sets and reordering

variantSet "colour" = {
    "red" {
        color3f[] primvars:displayColor = [(1, 0, 0)]
    }
    "blue" {
        color3f[] primvars:displayColor = [(0, 0, 1)]
    }
}
reorder nameChildren = ["Wheels", "Body"]
reorder properties = ["size", "colour"]

Each variant’s body can hold anything a prim body can, including nested variant sets.

Keywords