Usd Projection

USD → ECS projection

Before adding a field or reader branch, use luncosim-architecture and the standard-schema boundary. Prefer the OpenUSD schema that owns the concept. A migration is a clean cutover: update the authored source and all readers, delete the superseded spelling and compatibility branch, regenerate schema artifacts, and add a negative test. Never make the ECS projection a second source of truth.

USD is the source of truth. The ECS is a projection of it. Every entity you see is a rendering of a prim. Nothing is authoritative because it is in the world; it is in the world because it is in the document.

That single sentence generates every rule below.

The pipeline, end to end

UsdOp  ──►  UsdDocumentRegistry::apply   (journals + inverts)
              │
              ▼
          openusd Stage (the live CanonicalStage, NonSend)
              │  StageSink fires → RawStageChange { resynced, info_only }
              ▼
          project_stage_changes            (lunco-usd-commands/src/live_consume.rs)
              ├── resynced   → structural: spawn / despawn prims
              └── info_only  → attribute-only: translate, rotate, domes …
              │
              ▼
          UsdVisualProjectionQueued  (bounded ECS binding queue)
              │
              ▼
          UsdVisualPlugin (lunco-usd-bevy/src/lib.rs)
              └── match reader.type_name(path) → visual components
                         │
                         ▼
          UsdAnimationPlugin (lunco-usd-bevy-animation)
              └── sample authored timeSamples into visual intent

The asset loader composes the fetched layer closure and snapshots the complete default-time UsdRead surface into UsdStageProjectionPlan on its worker. The Add, UsdPrimPath observer and sync_usd_visuals both feed the same UsdVisualProjectionQueued marker. process_queued_usd_visuals drains that queue with its configured per-frame budget, but the extractor reads only the owned plan during initial materialisation; it does not parse USD, walk a live stage, or resolve composed bindings on the UI thread. CPU mesh-data geometry uses the render-free lunco-usd-geometry package, while its existing async compute path and only Bevy asset insertion remain on the main thread. After the initial asset generation, explicit live edits use the canonical StageView and the same extractor contract.

The scene transaction closes from asset and structural-projection outcomes. UsdSceneProjectionFailed on the running mount must fail and clear that transaction before a generation can commit; preview errors are separately owned. Missing default roots and nonexistent or non-prim explicit targets are visible projection failures. Verify the failure edge as well as queue drainage.

Incremental structural reconciliation resolves a live path through the UsdPrimPath lifecycle index keyed by stage asset and prim path. Insert and removal observers maintain it, including component replacement and preview duplicates; do not add a per-frame Added query or scan the full scene for each changed path. The canonical stage records a weak identity for each merged Arc<StageRecipe> so subsequent instances of that loaded revision skip cloning and comparing its full layer closure. A reloaded recipe has a new identity and must merge its current bytes before authoring the reference. Live instance handles own asset lifetime; the index and weak recipe cache are derived state. Transform edits update every indexed entity sharing that stage/path, including preview copies. Scale is applied only beneath UsdPreviewOnly; a live body's scale remains unchanged. Structural reconciliation still excludes previews. For a document-backed runtime reference spawn, the authored document keeps the reference arc. The live canonical stage receives only the instance root while an instance-scoped view over the shared immutable prepared snapshot projects the source asset's defaultPrim subtree. The view maps paths into the instance namespace and stores root pose and lunco:catalogId overrides; creating the view is constant time with respect to the source prim count. The first other authored edit composes the reference once, then shared promotion state switches every entity clone to the canonical reader. Root deletion can remove an unpromoted instance without composing its source. Keep simple QueryUsdPrim reads on the same plan; explicit geometry/topology queries use the owning document's composed stage. A failed promotion faults the mounted scene and rejects that live edit.

The stage ID committed by the document projection owner identifies the live stage; use stage_asset_for_document rather than an asset-server filename lookup. Source-text and stage assets may share a path but have different types. Changes to a document's root scene are projected by its canonical stage. Only different recipe roots that compose the changed layer are dependent refresh targets; the root scene never refreshes itself as a dependent stage.

For a bounded typed edit, the dependent owner composes the current persistent document layers directly to Sdf Data on a worker, then patches only the affected prim specs and fields in the existing canonical stage with one Stage::batch_edit. The normal sink projects those paths into ECS before an active-stage progress hold is released. Afterward, a background worker serializes the changed source and composes the immutable asset plan for a later mount. That plan refresh does not hold simulation progress or reset the live scene. Coarse composition edits and updates that span multiple changed source layers use the full-stage reset owner.

Native asset inputs follow the shared preparation gate: preserve the reader's current prepared table, retain edits/hints across superseded jobs, and release UsdNativeAssetPreparation only after that exact stage revision reaches live consumption or teardown. A queued visual or installed policy must remain deferred while native preparation holds its generation.

Doc-backed Twin admission is also asset-event driven. UsdSourceText is loaded through the shared typed load_asset_path address and registered source scheme; scene, preview, schema, reference and transitive layer readers preserve literal filename characters and attach Bevy labels separately. AssetEvent and AssetLoadFailedEvent advance or fail the pending document transaction. The default Twin path parses the exact source revision through native AsyncWorkAdmission, commits it through DocumentRegistry::open_prepared_file, restores the runtime overlay, and serializes a cloned persistent document on the worker pool. Source text and document generation are checked again before the Twin overlay is published and LoadScene is submitted. Runtime sidecar read/parse and editor-preview initial serialization remain synchronous; wasm worker transport for this path is not installed, so the owner reports that boundary visibly. The live USD stage stays with its thread-affine owner. Referenced stage closures follow the same event boundary before a reference is authored onto the live stage. Each instance retains the real source handle and one shared UsdReferenceSnapshot containing the canonical recipe, unscoped plan and actual loaded source revision. The canonical stage caches only weak snapshot identities: warm sibling reuse must validate the exact scene origin, current source recipe/plan and live mount before skipping address I/O and composition. Native file-URI references prepare confined typed addresses and StageRecipe::reanchor composition on the shared bounded reference lane, used by incremental spawns and coarse rebuilds. Preserve authored layer bytes and absolute identifiers; never inject transport aliases into the resolver. Publication rechecks exact stage lifetime/generation, source, operation, live mount and loaded source revision; worker panics become terminal completion errors. Current reference and document-projection holds remain through ordered projection, and replaced requests cannot consume outgoing completions. Each instance carries only its namespace, root identity, and root overrides; descendants reuse that view through the same queue. The entity reader invalidates that prepared source when the canonical stage generation changes, so authored overrides are always read from the live composed stage. Do not add frame-count timeouts, per-frame load polls, or direct filesystem reads to this path. After admission, DocumentChanged and stage-asset lifecycle events wake the single sync_twin_overlays owner; do not add a per-frame generation scan or a viewport-specific edit/reload path.

On first projection, the twin:// stage already contains the document's current base and runtime layers. Replay transient view edits from the document's bounded view-operation suffix since its current source baseline. Do not query the global op ring from generation zero: runtime restores are non-op generation changes, and persistent edits do not belong in the view replay. If the view suffix has expired, rebuild from the complete composed document.

For the mounted primary scene, reference fetches stay parallel but live-stage mutation and terminal failure publication follow reference operation order. A later completed reference remains prepared until every earlier active reference for that scene resolves. Keep its ready or failed outcome while deferred; never let asset completion order choose composition or fault order. Preview stages do not acquire this simulation-specific commit barrier. The production route_lifecycle Rhai scene gate covers the fixed-tick readiness contract with multiple live references; low-level owner tests cover the ready-prefix ordering seam.

The Editor is document-scoped. DocumentId from the existing DocumentRegistry<UsdDocument> identifies the file being edited; the Twin Browser opens the explicit OpenUsdPreview { preview, doc_id, edit_target } session and can later use FocusUsdPreview or CloseUsdPreview. A session owns one projected composed stage; OpenUsdPreviewView { preview, view } adds a camera/render target over that stage for another dock tab or split. FocusUsdPreviewView and CloseUsdPreviewView address the exact view. Native editor view-model resources are keyed by UsdPreviewId and derive one entry per open session; panels paint the focused view's session entry. Visible preview targets are bounded by UsdPreviewRenderBudget (2048 px per axis, 4,194,304 pixels per view, and 8,388,608 visible pixels per frame by default), while hidden view cameras stay inactive. The shared ECS selection is a focused-session projection restored from editor-owned session selection, not a document identity. Panel writes use the session's explicit DocumentId, LayerId, and projection generation.

The active Twin's asynchronous workspace restore recreates saved view tabs over the same document-scoped preview session and restores each view's camera and presentation settings. Reopening the same file reuses the registered document; use the explicit Open view action to add another perspective. A view tab without a restored session is dropped from the saved dock layout rather than shown empty.

Preview projection is a presentation scope over the same composed stage. It owns one session-local light and excludes authored scene-wide DistantLight/DomeLight prims from that render layer; authored local SphereLight/RectLight prims remain part of the assembly. A preview is ready only after its root and descendants are synced and that subtree's visual queue plus asynchronous mesh phase have settled. Consumers use the typed projection_ready state from InspectUsdViewport; they do not infer readiness from a document generation or camera state.

Each UsdPreviewView also exposes Visual and Text modes over that same session. Visual mode renders the projected stage; Text mode displays an asynchronous, generation-matched authored or composed USDA snapshot as read-only text. SetUsdPreviewViewMode and SetUsdPreviewTextLayer change only view presentation, so they preserve the document, projected stage, selection, camera, and lifecycle identity. Text snapshots are coalesced per session and discarded when the document generation or preview lease changes; they do not create a second parser, document registry, or source writer.

When an agent needs to answer “what is visible?” or edit the item a user has open, call the UI-owned InspectUsdViewport query (or assembly_edit::viewport()) and correlate its explicit preview/view handles with CaptureScreenshot. The query is presentation context, not a second document registry: use the returned doc_id, edit_target, and projection generation with document inspection and typed edit commands. Never infer identity from a tab title, filesystem basename, entity order, or the live simulation viewport.

The Files section sends a .usda, .usd, or .usdc click through the existing BrowserAction::OpenFile and async document pipeline. The emitting Twin's resolved absolute path is preserved, so an inactive Twin is not accidentally anchored on the active one. Once the document is admitted, the viewport derives its document-backed UsdPreviewId::for_document with LayerId::root(), opens the session's primary UsdPreviewView as an instance-backed dock tab, and focuses that exact tab. File reads capture FileDocumentAdmission before dispatch and validate the resolved runtime owner before publication. A retired owner cannot install a late source; repeated requests coalesce only with the same admission snapshot. Indexed Twin source requests and leases retire by exact TwinId, and stored document ownership fences deletion after a source rebind. Preview admission rejects retired document owners; private restored snapshots explicitly belong to Application. See the source lifetime contract. Browser file picks carry request-owned bytes into this same asynchronous preparation pipeline. Each successful import installs a fresh pathless Application document; the filename is display data, even when another pick has the same name. Native Save-As requests pin the exact source owner before the backend starts. Browser Save-As uses a fallible download and only publishes saved state after admission. Repeated admitted clicks reuse the same document, preview session and view tab. Explicit FocusUsdPreview and FocusUsdPreviewView commands foreground their matching instance tab as well; replacing or closing a session removes its view tabs with the presentation resources. The preview root carries UsdPreviewOnly, the USD projection ownership fence. Consumers that can create simulation side effects must use the shared bounded is_preview_only ancestry helper rather than names, stage handles, or missing physics components. Authored controls and program projection use that same ancestry fence. Cosim discovery marks preview prims examined without loading their programs, and wire derivation excludes preview descendants so duplicate USD paths cannot claim mounted-scene endpoints. Live operator entities are admitted only through their UsdSceneRoot ownership. The USD DEM bridge marks preview terrain prims examined without creating DemTerrainRequest; preview DEMs must not create collider rings, analytic query sources, or hold mission physics. Relief in an isolated Editor terrain preview still needs a separate render-only terrain realization and spatial demand. Mounted-scene live-edit reconciliation ignores preview copies when looking up an entity by stage and USD path, so a preview duplicate cannot satisfy the mounted scene's structural spawn or refresh. Procedural scene backgrounds are also excluded from previews because the skybox renderer has one scene-wide owner. Unscoped QueryUsdPrim reads select the mounted scene by ignoring UsdPreviewOnly roots; preview roots do not make live queries ambiguous. Never choose an editor stage by entity count, insertion order, or the current simulation viewport, and never use an active-viewport fallback for an entity that lacks an explicit document binding.

When an agent is creating or modifying a reusable assembly, use the dedicated interactive Assembly Editor runbook. It requires a headful production window, explicit document/preview handles, typed USD edits, a screenshot after each coherent change, and a user-feedback checkpoint. This projection skill owns the implementation boundary behind that workflow; it does not authorize direct USDA or ECS edits.

For agent or editor synchronization, call SyncUsdDocument with the explicit document generation. Use its typed delta while the cursor is covered; consume the returned base/runtime layer snapshot when a full reload or expired history window breaks the authored-operation stream. Full reloads advance the projection generation without adding a fabricated authored operation. Reject future cursors. To edit a composed path, call ResolveUsdTarget with the explicit document id, prim path, and @root@ or @runtime@ target. A referenced or payloaded path that has a local authored opinion in the current document is valid from that document layer while the existing CanonicalStage projection catches up; a composed-only path still requires the mounted canonical stage. Use the returned edit_scope and typed-operation validation rather than treating a composed read as permission to move or remove a referenced/variant prim. Do not inspect flat layer data as a replacement for OpenUSD PCP resolution or use it to invent a composed-only target.

For a transient edit target that a tool has just authored, pass authored_children: true to ResolveUsdTarget when it needs that layer's direct child paths before scene projection settles. This returns the selected layer's primChildren paths only; it does not resolve or enumerate composed children.

Agents and editor automation should use the built-in assembly_edit Rhai library. It is a thin wrapper over OpenFile, InspectUsdDocument, InspectUsdViewport, ResolveUsdTarget, SyncUsdDocument, ApplyUsdOp/ApplyUsdOps (including SetTimeSample and RemoveTimeSample for keyframes), AttachComponent, DetachComponent, UndoDocument/RedoDocument, CreateUsdProposal, InspectUsdEditSession, ReviewUsdProposal, and CommitUsdProposal; it does not create another document registry, resolver, USDA writer, or operation log. open returns the normal asynchronous command acknowledgement and callers discover the resulting id through ListOpenDocuments. Read helpers require an explicit doc_id; authored helpers require doc_id, an edit target, and a USD path. Their optional parent_gen is the existing stale-write precondition, and batch, transform, or a keyframe change land as typed journal/undo operations. A proposal requires a generation and explicit SourceAsset/Assembly/ InstanceOverride scope, validates without mutating the document, and is visible through InspectUsdEditSession. Mute/unmute and reject are review-only; commit rechecks generation, layer revision, origin, file watermark, scope, and typed validation before using the ordinary grouped journal/undo path. A conflict requires a fresh proposal; no automatic rebase or overwrite exists. Use the tool catalog and completion query to discover the source and signatures.

A scene loaded from disk and a prim authored at runtime therefore produce identical entities without one heavy deferred-command flush monopolising the window. The queue marker is the projection ownership fence: one prepared hierarchy creates one child under its USD parent, so the projector does not scan the world for duplicate stage paths. The same composed path is valid in separate scene mounts and runtime instances; hierarchy and instance identity scope those projections.

Generated Modelica domain projection follows the same ownership and change set rule: apply the shared is_domain_network_root predicate before selecting a synthesizer, then revisit only queued root entities. Live USD changes arrive as typed UsdSceneChangeBatch path sets and are routed through the canonical stage/root/member reverse index; stage-asset changes and generation gaps only requeue roots on that stage. Reserve the all-prim pass for initial discovery. Do not use the USD wiring latch as a membership signal, add a second stage scan, or use a name-based candidate list. After validation, publish the generated source and interface, link the source to its normal Modelica document, then let lifecycle compile admission dispatch it. Do not send a worker compile directly from USD projection; the standard path owns document-generation and session fencing for generated and authored models alike. Lifecycle projection is followed by stable identity admission and API/path index publication before the time spine releases simulation. Newly projected references must resolve by path on their first resumed tick through that ordered runtime path. The generated-source browser/API projection has its own source/document invalidation boundary. Do not gate it on live ModelicaModel output or clock changes; those are solver state and must stay in the Modelica runtime owner. Member class discovery is driven by ModelicaSource asset load, failure, and modification events. Do not add a time-based give-up deadline or poll pending sources on stable frames; an unavailable source remains explicitly pending until the asset owner publishes a terminal outcome.