Use Asset Library

Use the asset library

Almost everything in LunCoSim is an asset file, not a Rust type. A part, a vehicle, a material, a subsystem's physics, a mission script — all of them are files under assets/ that the engine discovers at runtime.

Rust ships parameterized behaviours; it never hardcodes a thing. If you are about to add a Rust struct for a specific rover, habitat, or shader, stop and add a file instead.

Related: author-usd-component (how to write the .usda), build-vehicle (assemble parts), build-usd-scene (assemble a scene), author-scenario (rhai), run-modelica (.mo), validate-assets (pre-flight before you run). Design: 56-asset-resolution-and-cache.md, 50-usd-driven-visuals.md.

Where things live

The canonical human/AI map is assets/README.md. Read it before adding a file; the filesystem is the runtime manifest and the README defines the stable taxonomy.

Architecture boundary

• USD owns assembly, transforms, variants, references, and wiring.
• Modelica owns continuous/domain math.
• Rhai owns scenario orchestration, rules, scoring, and assertions.
• The task kernel is reusable mechanism; Rhai owns authored behavior policy.
• Rust owns only general heavy runtime capabilities and bridges; expose their controls to Rhai instead of baking mission policy into Rust.

For a generic human/AI assembly workflow, use the hot-reloadable assets/scripting/tools/model_authoring.rhai facade. Keep its reusable reads, plans, and checks generic; put Twin-specific recipes beside the Twin. Pair any observable asset/linter regression with a USD fixture and Rhai scene observer under assets/scenes/tests/ and assets/scenarios/tests/.

Environment facts are produced by a distinct components/environment/probe.usda source prim. Never make a Modelica/Python consumer declare gravity_accel or a direction-target triplet as its own output and connect that output back to itself. EnvironmentProbe outputs use <target-id>_mount_x/y/z; reusable Modelica consumers use the generic target_mount_x/y/z inputs, and their wires choose which object supplies the direction.

The engine-recognized source extensions are walked into the discovery manifest (crates/lunco-assets-runtime/src/discovery.rs): .usda, .wgsl, .rhai, .mo, .py, .sysml, .kerml. .mo (Modelica), .py (optional Python), and SysML/KerML sources are catalogued both because a .usda/Twin names them and so they can be browsed directly. Python is not the standard scenario backend; Rhai is. The Scenarios menu groups registered source files by type. Non-source data (.json, .toml) is not walked: it is read by a subsystem or evaluated ad hoc, not browsed as an authored asset.

The lunco:// scheme

lunco://<rel> = the runtime assets/<rel>, with that root's packed cache and the shared cache after authored assets. The runtime root is selected by the fallible lunco_assets_core::assets_dir_abs() from LUNCO_ASSET_ROOT when set, otherwise executable/package ancestry before current-directory ancestry. An invalid override or unresolved library stops admission with an error; callers propagate that error instead of inventing a root. The asset owner provides typed Bevy load addresses, preserving literal # and % filenames. The complete read order comes from lunco_assets_core::library_roots() in crates/lunco-assets-core/src/lib.rs. twin://<assigned-mount>/<rel> is the same shape one level down: the Twin's authored root, its <twin>/.cache, then the global cache. This lets Twins reuse a global downloaded product without putting a machine path into USD. Authored bytes always win over materialised ones. Schemes are registered in crates/lunco-assets-runtime/src/asset_sources.rs; twin:// is stateful, it is not a second texture scheme. Use the existing logical lunco:// or twin:// identity for every delivered artifact. Canonical URI construction, separator normalization, and traversal validation come from the dependency-free lunco-assets-path crate; source roots and bytes are admitted by lunco-assets-runtime using the identity and cache contracts from lunco-assets-core. For reopened Twins, use the authority returned by the current mount, never reconstruct it from the manifest name or retain an outgoing address. Follow the canonical mount identity contract for provenance and scenario synchronization. Verify replacement content through the production app; resolver seam tests alone do not prove Bevy cache behavior. Native USD payloads, texture inputs, and Rhai asset sources use the typed native admission contract. Pass the stage's actual AssetServer path and current TwinRoots to the asset owner; keep its Result<AssetPath> through loading and attach labels separately. Verify a valid native filename with URI characters and a rejected foreign or retired mount through the production consumer; do not register an unrestricted file: source or enable unapproved paths to make a fixture load.

Anything the cache fallback can serve is DECLARED in an Assets.toml and downloaded only on request (Settings ▸ Downloadable data, the Twin Browser Files section's Twin assets rows, or the lunco-assets CLI) — the engine never fetches on its own, so an asset that is merely declared resolves to nothing until someone asks for it. The browser rows are only a view of lunco_assets_datasets::DatasetRegistry; they must emit its typed request/cancel commands and never create a second downloader or parse cache paths. The optional lunco-assets package composes native workers from lunco-assets-transport, lunco-assets-download, and lunco-assets-processing; consumers that only inspect declarations or state should depend on lunco-assets-datasets.

All requesters use the download section of the one settings file owned by lunco-settings. DownloadSettings.max_attempts includes the first request; retry waits are exponential and capped. Native and browser fetches retain received bytes and resume with HTTP Range when the origin supports it. Callers must pass the shared settings resource through the existing asset/API surface rather than adding a local retry loop or path.

A bare relative path is not "wrong" — it is resolved against the anchoring document's directory, keeping that document's scheme. That is why it bites:

# ✅ engine library — works no matter who mounts this file
prepend references = @lunco://components/mobility/wheel.usda@
prepend references = @lunco://components/power/battery.usda@

# ✅ a file sitting next to a Twin scene
uniform asset info:sourceAsset = @twin://my_mission/gnc.rhai@

# ⚠️ only legal when this file is itself inside assets/ AND never Twin-mounted
uniform asset info:sourceAsset = @scenarios/foo.rhai@

# ❌ always — `..` escapes the root and returns NotFound
prepend references = @../../components/mobility/wheel.usda@

The active program contract is visible in the runtime status. A Modelica or optional Python source with no declared inputs:/outputs: is reported as source-only; it is not treated as a running participant. AttachProgram is the canonical way to add the source and its explicit scalar contract. "My model does nothing" should be diagnosed by checking CosimStatus and GetBrokenConnections, not by assuming a hidden fallback. The production scene-test catalog reports read and parse status for every discovered .usd* asset, and the sandbox smoke scenario asserts that shipped USD sources are readable and parseable. Only validate-assets catches a broken references arc before you launch.

Rhai import uses the same canonical asset identity as USD. Use a logical lunco://… or twin://… URI, an assets-root /… path, or a path relative to the importing script. RhaiSourceLoader loads every literal import as a Bevy dependency; unused scripts are not preloaded.

The source asset owner qualifies default Bevy paths as lunco:// before it publishes source text or prepared ASTs. Scenario roots, imports, and unloads use the same canonical identity; Twin paths retain twin://. Consumers commit the complete loaded import graph before binding or starting a source because Bevy can report graph readiness before its Added messages are consumed.

Add a USD component

Write one file = one spawnable thing. The full authoring reference is author-usd-component; the library rules are:

#usda 1.0
( defaultPrim = "Widget"   # ← lunco:spawnable is ONLY read here
  upAxis = "Y"  metersPerUnit = 1.0
  doc = """What this is." """ )

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

How it reaches the palette (crates/lunco-scene-catalog/src/catalog.rs):

So components/power/solar_panel.usda lands under "Power" — not "Components". A file with no parent folder lands in "Other". Nothing is hardcoded; moving the file changes its category.

• lunco:spawnable defaults to false — it is opt-in.
• It must sit on the stage's defaultPrim. On any other prim the palette never sees it (child lunco:spawnable is a different feature — subpart selection).
• An unreadable file is not spawnable and logs CATALOG: … unreadable.
• Editing an already-scanned file? Send RescanSpawnCatalog — the scan caches per asset. Adding a new file is picked up automatically on native (the filesystem is the manifest).