USD

53 tools. Back to the index.

add_usd_internal_reference

Additive.

Add an internal reference composition arc (references another prim inside the SAME stage; no asset_path needed).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
prim_path	string	yes	Prim that owns the reference (the consumer).
target_prim_path	string	yes	Prim inside the same stage to reference.
position	string	no	List position (same vocabulary as add_usd_reference). Default "BackOfPrependList".

Returns: { stage_name: string, prim_path: string, target_prim_path: string, added: bool, position: string, errors: [string]? }

add_usd_payload

Additive.

Add a payload composition arc to a prim (load-on-demand; payloads are NOT loaded by the stage unless an explicit Load rule says so).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
prim_path	string	yes	Prim that owns the payload.
asset_path	string	yes	Identifier of the layer containing the payload.
prim_path_for_target	string	no	Prim inside the referenced layer to import. Empty (default) means '/'.
position	string	no	List position (same vocabulary as add_usd_reference). Default "BackOfPrependList".

Returns: { stage_name: string, prim_path: string, asset_path: string, added: bool, position: string, errors: [string]? }

add_usd_reference

Additive.

Add an external reference composition arc to a prim (asset_path -> target prim, optionally re-targeted by prim_path_for_target).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
prim_path	string	yes	Prim that owns the reference (target of the composition op on the consumer side).
asset_path	string	yes	Identifier of the layer to reference (absolute file path or USD-style relative identifier).
prim_path_for_target	string	no	Prim inside the referenced layer to import. Empty (default) means the referenced layer's pseudo-root '/'. The default matches the common "import the whole layer" use case.
position	string	no	One of "FrontOfPrependList" / "BackOfPrependList" / "FrontOfAppendList" / "BackOfAppendList" (default BackOfPrependList — pxr::'s default for the strongest-anonymous opinion).

Returns: { stage_name: string, prim_path: string, asset_path: string, added: bool, position: string, errors: [string]? }

add_usd_variant

Additive, idempotent.

Add a new variant to an existing variant set at the requested list position; idempotent (returns already_existed:true when the variant is already present)

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim that authors the variant set
variant_set_name	string	yes	Variant set that will receive the new variant
variant_name	string	yes	Name of the variant to add
stage_name	string	no	Stage cache key
position	string	no	One of FrontOfPrependList / BackOfPrependList / FrontOfAppendList / BackOfAppendList (default BackOfPrependList)

Returns: { prim_path: string, variant_set_name: string, variant_name: string, added: bool, already_existed: bool, position: string }

add_usd_variant_set

Additive, idempotent.

Author a new (empty) variant set on a prim at the requested list position; idempotent (returns already_existed:true when the set is already present)

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim that will author the variant set
variant_set_name	string	yes	Name of the variant set to create
stage_name	string	no	Stage cache key
position	string	no	One of FrontOfPrependList / BackOfPrependList / FrontOfAppendList / BackOfAppendList (default BackOfPrependList, matching the USD wrapper default)

Returns: { prim_path: string, variant_set_name: string, created: bool, already_existed: bool, position: string }

apply_usd_prim_schema

Destructive.

Apply a USD API schema (e.g. "MaterialBindingAPI") to an existing prim of a registered USD stage, on the current edit target. Checks CanApplyAPI first: a schema that cannot apply returns applied=false with the USD reason in why_not instead of an error. Not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
schema_name	string	yes	Schema identifier (not the C++ class name), e.g. "MaterialBindingAPI", "GeomModelAPI"
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { applied: bool, schema_name: string, why_not?: string }

clear_usd_attribute

Destructive, idempotent.

Clear authored values of a USD attribute on a prim of an open stage: with time, only the sample at that time code; without it, the default value and every time sample. Edits the stage in memory; save_usd_stage writes it. Returns present and cleared, present false when the attribute is missing.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under by open_usd_stage (default the file basename) or create_usd_stage (default "Untitled").
prim_path	string	yes	Absolute SdfPath of an existing prim on that stage, e.g. "/World/Cube".
attr_name	string	yes	Name of the attribute to clear, e.g. "size".
time	number	no	Time code of the single sample to clear (ClearAtTime); omit it to clear the default value and all samples (Clear).

Returns: { prim_path: string, attr_name: string, cleared: bool, present: bool, time: number? }

clear_usd_references

Destructive, idempotent.

Remove every reference from a prim's reference list (irreversible — there is no "undo" in USD composition authoring).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
prim_path	string	yes	Prim whose references should be cleared.

Returns: { stage_name: string, prim_path: string, cleared: bool, errors: [string]? }

clear_usd_variant_selection

Destructive, idempotent.

Clear the active variant selection on a variant set (leaves the set and its variants intact — only the selection arc is removed); HasVariantSet guard

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim that authors the variant set
variant_set_name	string	yes	Variant set whose selection should be cleared
stage_name	string	no	Stage cache key

Returns: { prim_path: string, variant_set_name: string, cleared: bool }

close_usd_stage

Destructive, idempotent.

Close a USD stage by its LLM-facing stage_name. Removes the stage from the LLM-facing UEAgent::UsdRegistry::GStageNameCache AND calls UnrealUSDWrapper::EraseStageFromCache on it — this is the ONLY way to release a memory stage (memory stages are never closed automatically, even on editor shutdown). If stage_name is not in the cache the call returns success with a note rather than an error (idempotent — closing an already-closed stage is a no-op). The 'removed_from_cache' field reports whether the stage was actually present in the UnrealUSDWrapper stage cache at close time.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under via open_usd_stage or create_usd_stage.

Returns: { stage_name: string, closed: bool, was_in_cache: bool, removed_from_cache: bool, note: string? }

create_usd_attribute

Additive.

Create an attribute of a given USD type on a prim of an open stage, or return the existing one with created false. Edits the stage in memory; save_usd_stage writes it. Returns name, type_name, cpp_type and created; author its value with set_usd_attribute_value.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under by open_usd_stage (default the file basename) or create_usd_stage (default "Untitled").
prim_path	string	yes	Absolute SdfPath of an existing prim on that stage, e.g. "/World/Cube".
attr_name	string	yes	Attribute name (e.g. "size", "displayColor")
type_name	string	yes	USD type name (e.g. "float", "float3", "token", "asset")

Returns: { prim_path: string, name: string, type_name: string, cpp_type: string, created: bool }

create_usd_stage

Additive.

Create a new USD stage (either on-disk or in-memory). When file_path is provided, UnrealUSDWrapper::NewStage(FilePath) creates a root layer file at that path and opens it as a stage. When file_path is omitted or empty, NewStage() (no args) creates a memory-only stage — this is the only way to author a USD stage that is NOT persisted to disk; the only way to clean it up is close_usd_stage. The new stage is always added to the LLM-facing UEAgent::UsdRegistry::GStageNameCache under stage_name (default "Untitled"), so subsequent calls can refer to it by name. The returned identifier is the root layer's USD identifier (real path for on-disk; an anonymous "anon:0x..." handle for memory stages).

Parameter	Type	Required	Description
file_path	string	no	Absolute path for the new USD root layer file (.usd/.usda/.usdc/.usdz). Omit or empty for a memory-only stage (optional).
stage_name	string	no	LLM-facing name to register the new stage under (optional, default "Untitled").

Returns: { stage_name: string, file_path: string, memory: bool, identifier: string, real_path: string, dirty: bool, is_valid: bool, errors: [string]? }

create_usd_stage_actor

Additive.

Spawn an AUsdStageActor into the editor's current world (or return the existing one). Each editor world has at most one AUsdStageActor (USDStage is single-instance per world); when one already exists the tool returns already_existed:true with its current actor_path instead of failing. Spawn uses a uniquely-named FName based on the user-supplied name parameter so re-runs with the same name pick up the existing actor cleanly. Requires a live editor world — honest-gated.

Parameter	Type	Required	Description
name	string	no	Desired actor name (default "UsdStageActor"). Used only on first spawn; ignored on subsequent calls that pick up the existing actor.
location	array	no	World [x, y, z] location for the new actor (optional, default [0, 0, 0]).
rotation	array	no	World [pitch, yaw, roll] in degrees for the new actor (optional, default [0, 0, 0]).

Returns: { actor_path: string, already_existed: bool, name: string }

define_usd_prim

Destructive.

Define a prim (specifier def) of type_name at prim_path on a registered USD stage, at its current edit target, defining missing ancestors as typeless prims. On an existing prim of another type it replaces the type, so leaving type_name out retypes it to Xform. The requested specifier is then authored at the edit target (specifier_set_ok); specifier reports it only when that write succeeded, and a failed write fails the call. An unknown specifier is refused before anything is authored. In memory only: save_usd_stage writes it. override_usd_prim authors an over instead; set_usd_prim_type changes only the type.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath, e.g. /World/Cube
stage_name	string	no	Name the stage was registered under
type_name	string	no	USD type name (Xform, Mesh, Cube, Scope, Camera, DistantLight...). Default: Xform
specifier	string	no	"Def" | "Over" | "Class", case-insensitive; anything else is refused. Default: Def

Returns: { prim_path: string, type_name: string, specifier?: string, is_valid: bool, specifier_set_ok: bool, requested?: object }

flatten_usd_stage

Destructive.

Export a flattened copy of the stage to a .usd/.usda/.usdc/.usdz file (the file writer is chosen by the extension). Wraps UE::FUsdStage::Export(OutputPath, bAddSourceFileComment, FileFormatArguments) — does NOT alter the in-memory stage. When add_source_file_comment is true (default) the flattened file includes a comment header noting the source file (useful for provenance). The returned 'exported' field reports pxr::'s bool return — false means the file writer could not write the requested path (e.g. invalid extension, permission denied). Realistic gotcha: stage.Export() requires the stage NOT be in a restricted-edit state — under headless cov this is not an issue, but in-editor it can be during PIE.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under, OR an absolute file path to auto-open.
output_path	string	yes	Absolute path of the flattened file to write. The file extension picks the writer (.usda=text, .usdc=binary, .usdz=archive).
add_source_file_comment	boolean	no	Include the source-file comment header in the flattened file (default true).

Returns: { stage_name: string, resolution: string, output_path: string, exported: bool, add_source_file_comment: bool, errors: [string]? }

get_usd_attribute_time_samples

Read-only.

List the time codes at which a USD attribute on a prim of an open stage has authored time samples, without changing the stage. Returns time_samples, count and present; a missing attribute is not an error but present false with an empty list.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under by open_usd_stage (default the file basename) or create_usd_stage (default "Untitled").
prim_path	string	yes	Absolute SdfPath of an existing prim on that stage, e.g. "/World/Cube".
attr_name	string	yes	Name of the attribute to inspect, e.g. "xformOp:translate".

Returns: { prim_path: string, attr_name: string, time_samples: [number], count: int }

get_usd_attribute_value

Read-only.

Read a USD attribute's value at a time code

Parameter	Type	Required	Description
stage_name	string	yes	Stage cache key
prim_path	string	yes	Target prim path
attr_name	string	yes	Attribute name to read
time	number	no	Optional time code (default: unset = static default)

Returns: { present: bool, has_value: bool, has_authored_value: bool, type: string, type_name: string, value: object }

get_usd_generated_assets

Read-only.

Resolve the transient assets (UStaticMesh, USkeletalMesh, UMaterial, etc.) generated by the stage actor for a given prim path. Wraps AUsdStageActor::GetGeneratedAssets(prim_path). Returns an empty assets array (count:0) when the prim has no generated assets — NOT an error. A prim may produce multiple assets (e.g. a skinned mesh produces USkeletalMesh + USkeleton + UPhysicsAsset).

Parameter	Type	Required	Description
actor_path	string	yes	Full actor path (or short name) of the AUsdStageActor.
prim_path	string	yes	Full prim path, e.g. "/root_prim/my_mesh".

Returns: { actor_path: string, prim_path: string, assets: [string], count: int }

get_usd_generated_component

Read-only.

Resolve a transient USceneComponent generated by the stage actor for a given prim path. Wraps AUsdStageActor::GetGeneratedComponent(prim_path). Returns present:false (NOT an error) when the path is invalid or the prim has no generated component — the LLM can pivot on this cleanly. When present, also returns component_class (the runtime UClass name).

Parameter	Type	Required	Description
actor_path	string	yes	Full actor path (or short name) of the AUsdStageActor.
prim_path	string	yes	Full prim path, e.g. "/root_prim/my_prim".

Returns: { actor_path: string, prim_path: string, present: bool, component_path?: string, component_class?: string }

get_usd_layer_info

Read-only.

Read metadata for a single layer in the stage's stack (identifier, real path, dirty/muted flags, sublayer paths).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
layer_index	number	no	0-based index into the layer stack (root layer is 0; session layers follow). Defaults to 0. Out-of-range returns an error rather than a synthetic empty payload.

Returns: { stage_name: string, layer_index: int, identifier: string, real_path: string, dirty: bool, is_muted: bool, sub_layer_paths: [string], sub_layer_count: int, errors: [string]? }

get_usd_prim_info

Read-only.

Read one prim of a registered USD stage: name, type_name, active, parent_path, direct children_count, applied_schemas, variant_sets and an is_a map for nine common types (Xform, Mesh, Cube, Scope, Camera, four lights). A missing prim returns is_valid=false with a note, not an error. Read-only.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of the prim to read, e.g. "/World/Cube".
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { name: string, prim_path: string, type_name: string, active: bool, is_valid: bool, is_pseudo_root: bool, parent_path: string, children_count: number, applied_schemas: [string], variant_sets: [string], is_a: { Xform, Mesh, Cube, Scope, Camera, DistantLight, SphereLight, RectLight, MeshLight: bool } }, or { prim_path, is_valid: false, note } when the prim does not exist

get_usd_prim_metadata

Read-only.

Read the metadata of a prim on a registered USD stage: one key (present plus value as {type, value}) or, with no key, all entries (authored and fallback) plus count. Above 100 entries only count and a note return; unsupported value types become a placeholder string. Read-only.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.
key	string	no	Metadata field to read, e.g. "documentation"; empty or omitted (default) returns all entries.

Returns: { present: bool, key: string, value: object, metadata: object, count: number, note?: string }

get_usd_stage_actor_info

Read-only.

Read live metadata from an AUsdStageActor. Returns the root layer identifier + real path from the actor's currently-open UE::FUsdStage (via GetUsdStage()), the integer EUsdStageState (0=Closed, 1=Opened, 2=OpenedAndLoaded), the presence of a generated ULevelSequence (a non-null GetLevelSequence()), and the count of USceneComponents the actor has spawned (via GetComponents()). All read-only.

Parameter	Type	Required	Description
actor_path	string	yes	Full actor path (or short name) of the AUsdStageActor.

Returns: { actor_path: string, root_layer: string, real_path: string, stage_state: int, stage_state_name: string, has_level_sequence: bool, generated_component_count: int, has_isolated_stage: bool, errors: [string]? }

get_usd_stage_info

Read-only.

Read metadata about a USD stage: root layer identifier, real path, dirty flag, timecode range (start/end), frames-per-second, total prim count (recursive) and layer-stack depth (includes session layers when include_session_layers is true). Resolves stage_name via the LLM-facing UEAgent::UsdRegistry::GStageNameCache first, then falls back to treating stage_name as a file path and auto-opening it (LoadAll, use cache). Returns 'resolution' as one of "cache_hit" / "auto_opened" so the caller knows which path served the stage.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under, OR an absolute file path to auto-open.
include_session_layers	boolean	no	Include session layers when computing the layer-stack depth (default true).

Returns: { stage_name: string, resolution: string, identifier: string, real_path: string, dirty: bool, start_time: number, end_time: number, frames_per_second: number, prim_count: int, layer_stack_count: int, has_start_time: bool, has_end_time: bool, has_fps: bool, errors: [string]? }

get_usd_variant_set_info

Read-only.

Read the variant names and current selection for a single variant set on a prim

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim that authors the variant set
variant_set_name	string	yes	Name of the variant set to inspect
stage_name	string	no	Stage cache key

Returns: { prim_path: string, variant_set_name: string, variants: [string], current_selection: string, variant_count: int }

insert_usd_sublayer

Additive, idempotent.

Add a sublayer path to the stage's root layer's composition stack (idempotent — re-running with the same path returns already_present without erroring).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
sublayer_path	string	yes	Path or USD identifier of the layer to insert (e.g. an absolute .usd path or a "//sub.usd" relative identifier).
index	number	no	0-based insertion position; -1 (default) appends to the back of the prepend list.

Returns: { stage_name: string, sublayer_path: string, index: int, inserted: bool, already_present: bool, new_count: int, saved: bool, errors: [string]? }

isolate_usd_layer

Destructive.

Enter isolated mode by replacing the actor's displayed stage with a new stage rooted at one of the sublayers of the current layer stack. Wraps AUsdStageActor::IsolateLayer(Layer, b_load_usd_stage). The layer_index selects into Stage.GetLayerStack(true) — index 0 is the root layer, >0 are sublayers. When b_load_usd_stage is true (default) assets, actors and components are regenerated from the isolated stage; when false the isolation is structural only.

Parameter	Type	Required	Description
actor_path	string	yes	Full actor path (or short name) of the AUsdStageActor.
layer_index	number	no	Index into the actor's stage layer stack (default 0 = root layer).
b_load_usd_stage	boolean	no	Load assets/components from the isolated stage (default true).

Returns: { actor_path: string, layer_index: int, isolated_layer: string, b_load_usd_stage: bool }

list_usd_file_formats

Read-only.

List the USD file format extensions the engine supports, with optional human-readable descriptions. Always returns the native set ("usd"/"usda"/"usdc"/"usdz") and the full supported set (native + third-party USD plugin extensions like "abc" from usdAbc). When include_descriptions is true, also calls AddUsdImportFileFormatDescriptions to populate the human-readable per-extension description strings (e.g. "usdc; Universal Scene Description binary files").

Parameter	Type	Required	Description
include_descriptions	boolean	no	Also return the per-extension import description strings from UnrealUSDWrapper::AddUsdImportFileFormatDescriptions (optional, default false).

Returns: { native_formats: [string], supported_formats: [string], native_count: int, supported_count: int, descriptions: [{format: string, description: string}]? }

list_usd_prim_attributes

Read-only.

List every attribute of a prim on an open USD stage without changing it. Returns count and attributes [{name, type_name, cpp_type, has_value, has_authored_value, time_sample_count}]; has_value also counts fallback values, has_authored_value only authored opinions.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under by open_usd_stage (default the file basename) or create_usd_stage (default "Untitled").
prim_path	string	yes	Absolute SdfPath of an existing prim on that stage, e.g. "/World/Cube".

Returns: { prim_path: string, attributes: [{name, type_name, cpp_type, has_value, has_authored_value, time_sample_count}], count: int }

list_usd_prims

Read-only.

List the prims under one prim (default the pseudo root "/") on a registered USD stage, each with prim_path, type_name and active, plus count: its direct children, or with recursive=true its whole subtree in depth-first order. Only active, loaded, defined, non-abstract prims appear, and instance proxies are not traversed. Read-only.

Parameter	Type	Required	Description
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.
prim_path_prefix	string	no	SdfPath of the prim whose children are listed; it must exist. Default "/" (the pseudo root).
recursive	boolean	no	false (default) lists the direct children only; true lists every descendant, each parent before its children.

Returns: { prims: [{ prim_path, type_name, active }], count: number }

list_usd_stage_layers

Read-only.

List the layer stack of a USD stage opened with open_usd_stage or create_usd_stage, read-only: each layer identifier, real_path, is_muted and dirty, plus count and any captured USD errors. An unregistered stage_name is an error; get_usd_layer_info details one layer by index.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under via open_usd_stage or create_usd_stage.
include_session_layers	boolean	no	When true (default) the returned stack also includes the stage's session/auto-generated layers; pass false to get only the persistent root + sublayers.

Returns: { stage_name: string, include_session_layers: bool, count: int, layers: [{ identifier: string, real_path: string, is_muted: bool, dirty: bool }], errors: [string]? }

list_usd_stages

Read-only.

Enumerate every stage currently in the UnrealUSDWrapper stage cache (shared across C++ + Python). Returns one entry per cached stage with the root layer identifier, real path and dirty flag. It reads the engine's stage cache directly, so it also lists the stages opened outside these tools (Python USD scripts, the editor's USD importer). Each entry's 'stage_name' is the name the stage was opened under through these tools; it is empty for a stage they did not open.

No parameters.

Returns: { stages: [{stage_name: string, identifier: string, real_path: string, dirty: bool}], count: int }

list_usd_variant_sets

Read-only.

List every variant set authored on a prim, plus the current selection for each set (selections map may be empty when no selection is authored)

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim to inspect
stage_name	string	no	Stage cache key

Returns: { prim_path: string, names: [string], selections: object, count: int }

mute_usd_layer

Destructive.

Toggle mute state on a set of layers by their identifiers (mute + unmute are passed in the same call — pxr:: applies them atomically).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
mute_paths	array	no	Identifiers of layers to mute. Empty/missing is allowed (no-op on the mute side).
unmute_paths	array	no	Identifiers of layers to unmute. Empty/missing is allowed (no-op on the unmute side).

Returns: { stage_name: string, muted: [string], unmuted: [string], errors: [string]? }

open_usd_stage

Destructive.

Open an existing USD stage from a file path. Wraps UnrealUSDWrapper::OpenStage with caching and force-reload controls. When use_stage_cache is true (default) and the file is already open in the UnrealUSDWrapper stage cache, the existing stage is returned. When force_reload is true, all local layers are forced-reloaded from disk (useful when the file was modified by another tool since the last open). The opened stage is added to the LLM-facing UEAgent::UsdRegistry::GStageNameCache under either the explicit stage_name or a derived one (basename without extension). The stage_id returned is the root layer's USD identifier — a stable string handle useful as a unique reference across follow-up commands.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .usd/.usda/.usdc/.usdz file (or a USD layer identifier).
stage_name	string	no	LLM-facing name to register the opened stage under. Defaults to the file basename without extension (optional).
initial_load_set	string	no	"LoadAll" (default; loads payloads) or "LoadNone" (faster; inspect without loading payloads).
use_stage_cache	boolean	no	Use UnrealUSDWrapper's stage cache (default true). When false the stage is re-read and not added to the cache.
force_reload	boolean	no	Force-reload all local layers from disk, bypassing the layer registry (default false).

Returns: { stage_name: string, stage_id: string, identifier: string, real_path: string, from_cache: bool, file_path: string, errors: [string]? }

override_usd_prim

Additive, idempotent.

Author an over (specifier over, no type) at prim_path on a registered USD stage, at its current edit target, with overs for missing ancestors, to add opinions to a prim without defining it. A prim that already exists there is returned untouched (already_existed true, no specifier reported, since nothing was authored); specifier Over comes back only for an over this call authored. is_valid=false means USD refused; a missing stage or a bad path is an error. In memory only: save_usd_stage writes it. define_usd_prim creates a typed def; set_usd_prim_specifier changes the specifier of an existing prim.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath to author the over at, e.g. "/World/Cube"
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { prim_path: string, is_valid: bool, already_existed: bool, specifier?: string }

remove_usd_attribute

Destructive, idempotent.

Remove one attribute from a prim on a registered USD stage by deleting its scene description in the current edit target layer only, so opinions from other layers or references can keep it composed. Idempotent: an absent attribute gives present=false and removed=false, not an error, and a relationship of that name counts as absent. A stage not registered under stage_name or a missing prim is an error. In memory only: save_usd_stage writes it. To keep the attribute and drop its values use clear_usd_attribute.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under by open_usd_stage (default the file basename) or create_usd_stage (default "Untitled").
prim_path	string	yes	Absolute SdfPath of an existing prim on that stage, e.g. "/World/Cube".
attr_name	string	yes	Name of the attribute to remove, e.g. "size"

Returns: { prim_path: string, attr_name: string, removed: bool, present: bool }

remove_usd_prim

Destructive.

Remove a prim and its subtree from the current edit target layer of a registered USD stage, returning removed. Opinions in other layers or references can keep it composed; set_usd_prim_active with active=false is the reversible way to hide a prim. Not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of the prim to remove, e.g. "/World/Cube"; its descendants go with it.
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { removed: bool, prim_path: string }

remove_usd_prim_schema

Destructive.

Remove an applied API schema (e.g. "MaterialBindingAPI") from an existing prim of a registered USD stage, on the current edit target. A schema the prim does not have returns removed=false and was_applied=false instead of an error. Not saved to disk; inverse of apply_usd_prim_schema.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
schema_name	string	yes	Schema identifier as listed in applied_schemas by get_usd_prim_info, e.g. "MaterialBindingAPI".
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { removed: bool, schema_name: string }

remove_usd_sublayer

Destructive.

Remove a sublayer by index from the stage's root layer's composition stack.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
sublayer_index	number	yes	0-based index into GetSubLayerPaths() of the root layer.

Returns: { stage_name: string, sublayer_index: int, removed: bool, new_count: int, errors: [string]? }

save_usd_stage

Destructive.

Save a USD stage's root layer to disk. Wraps UE::FSdfLayer::Save(force) on the resolved stage's root layer. When force is false (default) and the root layer is clean, Save is a no-op and returns false — this is the USD-spec behavior and is reported honestly via 'saved:false' rather than as an error. Use force=true to re-write a clean layer (rare — typically only when a downstream tool requires a specific mtime).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under, OR an absolute file path to auto-open.
force	boolean	no	Force-re-save even when the layer is clean (default false).

Returns: { stage_name: string, resolution: string, saved: bool, dirty: bool, force: bool, real_path: string, errors: [string]? }

set_usd_attribute_value

Destructive, idempotent.

Author a value on a USD attribute (creating it if missing)

Parameter	Type	Required	Description
stage_name	string	yes	Stage cache key
prim_path	string	yes	Target prim path
attr_name	string	yes	Attribute name to set
type_name	string	no	USD type name; REQUIRED when the attribute does not exist yet (used to CreateAttribute). When the attribute already exists this is ignored.
value	any	no	{type: "float"|"int"|"string"|"token"|"asset"|..., value: <scalar>}; explicit type preferred; implicit by JSON runtime type otherwise.
time	number	no	Optional time code (default: unset = static default)

Returns: { prim_path: string, attr_name: string, set: bool, type_name: string, type: string, created: bool, time: number? }

set_usd_edit_target

Destructive, idempotent.

Point the stage's edit target at a specific layer in the stack (mutations after this call land on the chosen layer, not the root).

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under.
layer_index	number	no	0-based index into GetLayerStack(true) of the new edit target. Defaults to 0 (the root layer).

Returns: { stage_name: string, layer_index: int, edit_target: string, edit_target_real_path: string, errors: [string]? }

set_usd_prim_active

Destructive, idempotent.

Activate or deactivate an existing prim on a registered USD stage (active metadata on the current edit target). An inactive prim and its subtree leave composition but stay addressable, the reversible alternative to remove_usd_prim. Returns active and set; not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.
active	boolean	no	true to activate, false to deactivate; omitted means true.

Returns: { active: bool, prim_path: string }

set_usd_prim_display_name

Destructive, idempotent.

Author the displayName metadata (a UI label; the prim name does not change) on an existing prim of a registered USD stage, at the current edit target. An empty string is written as an empty displayName, not cleared. Returns display_name and set; not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
display_name	string	yes	Label that UIs show instead of the prim name, e.g. "Hero Cube"; may be empty.
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { set: bool, display_name: string }

set_usd_prim_instanceable

Destructive, idempotent.

Set or clear the instanceable metadata (USD native instancing) of an existing prim on a registered USD stage, at the current edit target. Returns instanceable (the requested value, or the current one when the write fails) and set. Not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.
instanceable	boolean	no	true to mark instanceable, false to clear; omitted means true.

Returns: { instanceable: bool, prim_path: string }

set_usd_prim_metadata

Destructive, idempotent.

Author one metadata field (e.g. "comment", "documentation", "kind") on an existing prim of a registered USD stage, at the current edit target. USD returns set=false when the value type does not match the field type; the reply echoes the converted value. Not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
key	string	yes	Registered USD prim metadata field, e.g. "comment", "documentation", "kind" or "hidden"; a key USD does not register as prim metadata fails with set=false.
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.
value	any	no	{type?: "bool|int|int64|float|double|string|token|asset", value: <scalar>} OR a bare scalar; without type the JSON type decides (bool, number stored as double, string). Token fields such as "kind" need type "token".

Returns: { set: bool, key: string, value: object }

set_usd_prim_specifier

Destructive, idempotent.

Change the specifier ("Def", "Over" or "Class") of an existing prim on a registered USD stage, at the current edit target. An unknown specifier is refused before anything is authored. specifier reports the one written, only when the write succeeded (set); a failed write fails the call. Not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of an existing prim, e.g. "/World/Cube".
specifier	string	yes	"Def", "Over" or "Class", case-insensitive; anything else is refused.
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { set: bool, specifier?: string, requested?: object }

set_usd_prim_type

Destructive, idempotent.

Change the typeName of an existing prim on a registered USD stage (define_usd_prim creates new ones), at the current edit target. The name is written as given, not checked against the schema registry. Returns type_name and set; not saved to disk.

Parameter	Type	Required	Description
prim_path	string	yes	Absolute SdfPath of the prim to retype, e.g. "/World/Cube"; it must exist.
type_name	string	yes	New USD schema type name, e.g. "Mesh", "Xform" or "Cube"; written as given.
stage_name	string	no	Name the stage was registered under by create_usd_stage or open_usd_stage; a stage already in the USD cache also matches by the end of its root layer identifier.

Returns: { set: bool, type_name: string }

set_usd_stage_actor_root_layer

Destructive, idempotent.

Assign a USD file as the actor's root layer and transition the stage state. Wraps AUsdStageActor::SetRootLayer(path) followed by AUsdStageActor::SetStageState(state). SetStageState(OpenedAndLoaded) triggers level-sequence regeneration — this can take a noticeable amount of time on large stages, so the cov harness may observe a transient 'rebuilding' state via follow-up get_usd_stage_actor_info calls. The tool does NOT verify the file exists on disk — SetRootLayer stores the path; the actual load happens during SetStageState(OpenedAndLoaded). When root_layer_path is empty, the existing root layer is preserved.

Parameter	Type	Required	Description
actor_path	string	yes	Full actor path (or short name) of the AUsdStageActor.
root_layer_path	string	yes	Absolute file path of the USD file (.usd/.usda/.usdc/.usdz).
stage_state	string	no	"OpenedAndLoaded" (default), "Opened", or "Closed".

Returns: { actor_path: string, root_layer_path: string, stage_state: string }

set_usd_stage_time_range

Destructive, idempotent.

Set a USD stage's start/end time codes and optionally its frames-per-second, then save the root layer (idempotent — no-op when !dirty). Both start_time and end_time are required and are written via UE::FUsdStage::SetStartTimeCode / SetEndTimeCode (which write to the stage's root layer metadata). When frames_per_second > 0, also calls SetFramesPerSecond. The Save() at the end is force=false so a layer that wasn't actually mutated by the Set* calls will not produce an unnecessary write.

Parameter	Type	Required	Description
stage_name	string	yes	Name the stage was registered under, OR an absolute file path to auto-open.
start_time	number	yes	New start time code (e.g. 0.0).
end_time	number	yes	New end time code (e.g. 24.0).
frames_per_second	number	no	Optional frames-per-second override; values <= 0 are ignored (use get_usd_stage_info / set_usd_stage_time_range to leave fps untouched).

Returns: { stage_name: string, resolution: string, start_time: number, end_time: number, frames_per_second: number, applied: bool, saved: bool, dirty: bool, errors: [string]? }

set_usd_variant_selection

Destructive, idempotent.

Set the active variant for a variant set; HasVariantSet guard prevents the FUsdVariantSet from going invalid when the set is missing

Parameter	Type	Required	Description
prim_path	string	yes	SdfPath of the prim that authors the variant set
variant_set_name	string	yes	Variant set to select a variant from
variant_name	string	yes	Variant to activate (must already be present — use add_usd_variant first)
stage_name	string	no	Stage cache key

Returns: { prim_path: string, variant_set_name: string, variant_name: string, set: bool }

usd_module_status

Read-only.

Probe whether the USDCore plugin is loaded and what file formats USD can read/write. Calls UnrealUSDWrapper::GetNativeFileFormats (expected to include "usd", "usda", "usdc", "usdz") and UnrealUSDWrapper::GetAllSupportedFileFormats (which also includes extensions from third-party USD plugins like Alembic "abc"). A zero count on either means USDCore did not load.

No parameters.

Returns: { native_formats: [string], supported_formats: [string], supported_count: int, native_count: int, native_present: bool, supported_present: bool }