Author Usd Component

Author a USD component

USD is the source of truth, projected to Bevy ECS. For a live Editor task, you build a thing through a Rhai typed-operation plan and the document command owner; the engine then projects the authored stage. Do not hand-edit USDA text, patch a file behind the open document, or mutate ECS state to force a result. The resulting component is still a normal .usda asset, but its persistent file is written by the Editor's save operation. Nothing here is a Rust change unless the typed owner is missing a generic USD capability.

Frame is fixed: Y-up, right-handed, −Z-forward, SI metres (docs/architecture/41-axes-and-units.md). Author in that frame. upAxis = "Z" / metersPerUnit != 1 are converted once at the shared USD boundary (crates/lunco-usd-document/src/units.rs; the runtime reader adapter is in lunco-usd-bevy) — never branch on them.

Background: 21-domain-usd.md, 50-usd-driven-visuals.md. Before adding a schema or property, read clean-architecture-and-usd-standards.md and run its standard-schema gate. Use UsdGeom, UsdPhysics, UsdShade, and UsdLux where they own the concept; add a LunCo field only for semantics USD does not define, then delete any overlapping superseded field and reader in the same cutover. Related skills: use-asset-library (where the file goes, how it is discovered, the lunco:// scheme), build-usd-scene (assemble), edit-usd-assembly (interactive headful assembly authoring with screenshot/user-feedback checkpoints), validate-assets (pre-flight it), test-via-api (verify), compose-multidomain-twin. For creating or hot-registering reusable Rhai builders, lints, and component tests, read author-rhai-tool. For the agreed live feedback loop and the Blender/FreeCAD/Fusion/SOLIDWORKS/ COMSOL/OpenUSD practice mapping, read interactive-component-authoring.

Component contract before geometry

Treat a component as a lightweight CAD deliverable rather than an isolated mesh. Before authoring, state its local frame, mount datum, required topology/types, dimensional envelope, mass/inertia owner, collision policy, parameters/units, public provenance, and any deployment or operating limits. Keep public/reference-backed facts separate from Twin study assumptions. For material-dependent parts, record a typed SysML material reference and the condition-specific properties required by the analysis; the USD material assignment/runtime facts remain standard authored USD and must be an explicit projection of that same selection, not a second manual source. Keep this distinct from UsdShade appearance and UsdPhysicsMaterialAPI contact coefficients. Use the SysML material-property gate for the single-source catalogue rule. Do not author physics:density expecting it to affect runtime mass: this component path consumes explicit physics:mass.

Before authoring any component, use the repository-wide five-phase workflow in interactive-component-authoring: analyse the USD/Rhai/Modelica/Rust seam, split by ownership, record sources and rationale in SysML, build with typed Editor tools, and run component → assembly → whole-system gates. This applies to every mission and model. A missing datum or unsupported generic operation is an explicit failing report; this skill does not permit invented dimensions, duplicated requirement literals, or a direct USDA workaround.

One independently reusable or articulated part gets one explicit component root and its own USD file under the Twin's components/ tree. The component's Rhai tool creates typed USD operations and its requirement/test Rhai reads the composed stage and checks both normal and boundary cases. The parent assembly must separately test reference identity, placement, symmetry/clearance, joint endpoints, variant selection, and cross-component wiring. Do not rely on the assembly test to prove the component's internal contract, or on a component test to prove it is correctly mounted.

For live Editor work, create/open the component document, apply the typed Rhai plan, wait for projection, inspect the exact prims, capture a screenshot, and only then save. Do not hand-edit or flatten USDA text to accelerate a component change. Use standard USD variants for genuine configurations; if the typed editor cannot create the needed variant set/blocks or reference-list opinion, report the Rust capability gap instead of using hidden duplicate geometry as a substitute.

Keep the component's Rhai source reviewable: pure plan functions, read-only requirement reports, and runtime test observers are separate responsibilities. Register Twin-scoped libraries through RegisterToolLibrary and verify a real namespaced call in the same process; ListToolLibraries alone is not invocation proof. See author-rhai-tool.

For recurring parametric parts, use the generic assembly_builder::component_bundle_facts and assembly_builder::component_bundle_plan contract instead of adding a vehicle-specific schema or Rust type. Supply SI-metre dimensions, standard Cube/Cylinder/Cone geometry, explicit visual/collision roles, existing material targets, mass/inertia, named attachment or actuator frames, and any limits. The facts call is the validation boundary; the plan returns typed USD operations for the normal proposal/review/commit flow. It does not invent a body, joint, socket occupancy, or material asset. Add those contracts through their existing explicit builders and test the component's normalized facts and composed result in Rhai.

When editing an existing component rather than creating it, use the generic component_editor::update_context or component_editor::selected_update_context facade. It combines the exact document/edit-target/generation checkpoint with the standard property catalog; component_editor::update_plan delegates to the same bundle planner and returns dry typed ops. Keep the bundle recipe in the owning Twin/model package, preserve existing topology and material ownership, and commit one reviewed proposal. Do not infer the recipe from child names or add a Rust registry.

When the component is ready to become a reusable asset, call model_authoring::publish_component(doc, root, edit_target, output, provenance). It checks the top-level component root, standard kind and defaultPrim, applied schemas, reference identities, and caller-supplied provenance, then returns ordinary metadata ops and an explicit save_as command. Review and apply the ops through assembly_edit; call assembly_edit::save_as_document explicitly after projection/lint. The helper does not invent a provenance schema, write USDA directly, or autosave. See scripting-guide.md for the complete facade sequence.

Skeleton

One file = one spawnable thing. The catalog keys off the file, and lunco:spawnable must sit on the stage's defaultPrim.

For live authoring, the skeleton below describes the authored result; it is not permission to paste or rewrite USDA source. Use assembly_edit::new_document or open the exact component document, call the component's Rhai builder, apply its reviewed typed ops, inspect the projected result, and save through the document lifecycle.

#usda 1.0
(
    defaultPrim = "Widget"
    upAxis = "Y"
    metersPerUnit = 1.0
    doc = """What this is, and where its numbers came from."""
)

def Xform "Widget" (
    kind = "component"
    prepend apiSchemas = ["LunCoCatalogAPI"]
)
{
    uniform bool lunco:spawnable = true

    def Scope "Looks" { def Material "Shell" { ... } }

    def Mesh "Body" (prepend apiSchemas = ["MaterialBindingAPI"]) { ... }
}

kind is authored but read by nothing — standard-USD hygiene for DCC interop, not an engine signal. Use doc = "..." prim metadata for descriptions; doc is the standard USD description metadata; do not add a lunco:description attribute (crates/lunco-scene-catalog/src/spawn_meta.rs).

Transforms — the mandatory bit

double3 xformOp:translate = (0, 1.5, 0)
double3 xformOp:scale = (1, 0.5, 1)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]

Without xformOpOrder the prim is at identity and every xformOp:* is ignored, silently. Treat a missing or incomplete transform order as an authoring error. This is the single most common way to author a correct-looking file that does nothing.

Supported: translate, scale, orient (quat, USD (w,x,y,z)), transform (matrix4d), rotateX/Y/Z (degrees), all six Euler orders, and the !invert! prefix. Ops compose in listed order, so the last listed applies first to the geometry. An op that is listed but unreadable is skipped as identity — silently.

Also: a translation of (0,0,0), an identity rotation, or an all-zero scale will not overwrite an existing spawned transform (crates/lunco-usd-bevy/src/lib.rs). Authoring zero is a no-op, not a reset.

Geometry

axis defaults to "Z", not Y — a Cylinder with no axis lies along Z (crates/lunco-usd-bevy/src/lib.rs). Cube.width/height/depth do not exist. extent is never read.

Procedural camera backgrounds

Use the reusable environment/starfield_sky.usda pattern for a procedural camera background: author an Xform with MaterialBindingAPI, bind its UsdShade material, and apply LunCoProceduralSkyAPI. This registered API intent is needed because USD has no standard field for a renderer-specific procedural camera background. The projection stamps the existing render-free ProceduralSkybox intent and creates no mesh. Use UsdLuxDomeLight when the scene needs a textured environment light; it is a different USD concept and must not be represented by a skybox marker.

If a referenced component supplies a generic visual proxy but the enclosing vehicle needs a different authored shape, keep the reference for its ports and domain facets, set the referencing visual prim's standard visibility to "invisible", and add the replacement as a visual-only child of the same rigid body. Do not duplicate the electrical/environment component or give the replacement its own body. This keeps USD topology and runtime ownership intact.

UsdGeomPointInstancer is supported for static direct renderable Gprim prototypes: author the standard prototypes, protoIndices, positions, and optional orientations/orientationsf, scales, ids, and invisibleIds properties. The visual projection shares the prototype mesh/material handles so Bevy can automatically batch equal instances. Time-sampled instance arrays and animated prototypes are rejected visibly until runtime sampling is implemented. Arbitrary prototype subtrees are rejected visibly until the multi-mesh render batch is implemented. Native instanceable = true scenegraph instancing, Points, GeomSubset, and subdivisionScheme remain unsupported (catmullClark renders as its raw control cage).

Mesh rules

For Rhai-authored mesh updates, keep points, faceVertexCounts, and faceVertexIndices as numeric arrays and pass them to assembly_builder::mesh_points_update_plan (points only) or assembly_builder::mesh_geometry_update_plan (points plus topology). Review and apply the returned operations through assembly_edit; do not hand-build USD array literals in model-specific scripts. These helpers serialize only at the standard USD attribute boundary and leave material, purpose, and physics metadata untouched.

• Output is unindexed triangles; n-gons are fan-triangulated, so author convex faces or triangulate yourself.
• orientation = "leftHanded" flips winding; default is right-handed/CCW.
• Any malformed topology → no mesh at all, no fallback primitive.
• Interpolation is inferred from array length only — interpolation metadata is never read. An array matching points.len() is per-vertex; one matching faceVertexIndices.len() is faceVarying; any other length is silently ignored. So uniform/constant normals or UVs vanish.
• UVs: primvars:st only, UV_0 only. Bare st and primvars:st0 are not read.
• Normals: authored normals used, else flat-computed. No smoothing.

NurbsPatch

def NurbsPatch "Wall" {
    int uVertexCount = 9
    int vVertexCount = 2
    int uOrder = 3                      # default is 4 if unauthored
    int vOrder = 2
    double[] uKnots = [0,0,0,1,1,2,2,3,3,4,4,4]
    double[] vKnots = [0,0,1,1]
    point3f[] points = [ ... ]          # v-major: v rows of u points
    double[] pointWeights = [ ... ]     # omit ⇒ all 1 ⇒ POLYNOMIAL, not rational
}

• Point order is index = iv * uVertexCount + iu — v-major rows of u-points. pointWeights uses the same index.
• uRange / vRange are NEVER READ. The parametric span comes from the knots: [uKnots[uOrder-1], uKnots[uVertexCount]]. Authoring a range that disagrees with the knots does nothing at all.
• Omitting pointWeights silently gives you the wrong shape. A circle needs rational weights 1, cos45, 1, cos45, …; without them the "circle" is a quadratic B-spline through a square control polygon and bulges ~6% at the diagonals. Pinned by nurbs::tests::dropping_weights_visibly_breaks_the_circle.
• Tessellation is fixed, not adaptive: clamp(count * 6, 8, 128) per direction.
• Normals are analytic; a degenerate row (a dome apex) yields +Y rather than NaN.

Every rejection path warns with a reason (crates/lunco-usd-geometry/src/nurbs.rs). If a patch is missing from the render, read the log first — it will say which guard fired, and untrimmed patches log their vert count.

Curves

widths is required — no widths, no mesh. That gate is what stops a camera rail becoming a pipe. Note basis = "bspline" is approximated as CatmullRom (interpolating, not hull-approximating).

Real holes — trim curves

trimCurve:* is the standard USD way to put a genuine hole in a surface, and it is implemented by the importer.

int[] trimCurve:counts = [1]           # curves per loop
int[] trimCurve:orders = [2]           # 2 = linear = a polyline
int[] trimCurve:vertexCounts = [16]
double[] trimCurve:knots = [0,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,15]
point3f[] trimCurve:points = [ (u, v, w), ... ]   # HOMOGENEOUS 2D

• Points are homogeneous: the position is (x/w, y/w). Skipping the divide gives a subtly wrong, plausible-looking loop.
• Coordinates are in the patch's raw parameter space (from the knots), not normalised, and are deliberately not unit/axis converted.
• Winding does not matter. Classification is even-odd with the domain rectangle as an implicit outer loop, so USD's unstated keep/discard rule never has to be guessed (crates/lunco-usd-geometry/src/trim.rs).
• Parameter space is anisotropic and non-linear. On a cylinder, u spans circumference while v spans height, and a rational arc parameterises non-uniformly — at the quarter point of a 90° span the true angle is 21.598°, not 22.5°. A circle authored naively renders as a squashed, mis-sized shape.
• A trim failure renders UNTRIMMED with a warning — bigger than authored, never smaller. A hole that doesn't appear is a log line, not a silent nothing.
• Trim gives you no reveal: a trimmed surface has no side walls, so the wall thickness at the opening is open. Closing it needs a ruled surface lofted between the two loops, authored separately.

Materials

Bind a UsdPreviewSurface; the Looks scope is convention only, enforced nowhere.

def Scope "Looks" {
    def Material "Shell" {
        token outputs:surface.connect = </Widget/Looks/Shell/Shader.outputs:surface>
        def Shader "Shader" {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor = (0.42, 0.40, 0.38)
            float inputs:roughness = 0.9
            float inputs:metallic = 0.0
        }
    }
}

Read: diffuseColor, emissiveColor, metallic, roughness, normal, occlusion, opacity, opacityThreshold, ior, clearcoat, clearcoatRoughness, useSpecularWorkflow, specularColor.

• MaterialBindingAPI does NOT need applying. Resolution uses compute_bound_material via ::on, so bindings inherit down namespace and collection-based bindings work (crates/lunco-usd-bevy/src/lib.rs). Applying it is harmless.
• primvars:displayColor must be an ARRAY. color3f[] primvars:displayColor = [(r,g,b)]. A scalar color3f is silently ignored, and the bare displayColor alias is not read at all. Same for float[] primvars:displayOpacity. Values are linear, not sRGB.
• displayColor is the ONE place a colour is authored, shader or not. A WGSL shader opts in with //!@engine display_color and the engine fills that uniform from the prim's composed primvars:displayColor — so a shader-bound part is still painted the ordinary USD way. Don't author a parallel colour input on the Shader prim; use inputs:* only for what displayColor cannot express (accents, panel scale, wear). An explicit inputs:display_color overrides the fill.
• inputs:* authored directly on a gprim is not read — put it on a bound Shader.
• doubleSided (on the gprim, default false) is required for anything you can see through — a trimmed surface reads as a hole from one side and nothing from the other without it.
• Alpha: opacity < 1 or a connected inputs:opacity → Blend; opacityThreshold > 0 → Mask. For a symbol that must bypass lighting, normals, and shadows, apply LunCoSurfaceAPI to the gprim and author bool lunco:surface:unlit = true. This maps to PbrLook.unlit; it is not emissive radiance and must not be simulated with an emissive-only surface.
• Navigational annotations use the authored opacity appropriate to their visual job. The reusable route-point dome is translucent, unlit, and shadowless, with a bright green unvisited colour. The generic route policy applies a gray transient material-colour override when its sensor event reaches the point. Its invisible Trigger remains a separate overlap-only prim.
• For an annotation that is genuinely meant to emit visible radiance, use inputs:emissiveColor; for one that must not emit light, keep that input black. lunco:surface:additive is reserved for authored additive glow surfaces and is not a substitute for unlit presentation.
• Textures: UsdUVTexture via inputs:file, wrapS/wrapT, inputs:sourceColorSpace. There is no UV primvar reader — UsdPrimvarReader_float2/inputs:st is inert; UVs come from the mesh's own primvars:st. If distinct metallic and roughness textures are both connected, the metallic one is silently dropped (one Bevy slot).

Custom WGSL is bindable through a standard composed UsdShade.Material and UsdShade.Shader, using uniform asset info:wgsl:sourceAsset = @lunco://shaders/x.wgsl@ and typed inputs:* parameters on the Shader. The same material-binding resolution handles inherited and collection bindings. Binding a library shader with no @fragment entry (e.g. pbr_lit.wgsl) is an authored render error; bind a complete material shader instead.