Blacksite/docs/adr/0017-normalized-static-mesh-assets.md

ADR 0017: Normalized Static Mesh Assets

Status

Accepted

Context

glTF/GLB and FBX previously entered the editor as imported scenes through ModelRef, with runtime hydration loading a format-specific WorldAssetRoot. That path is still useful for full scene playback, but it makes ordinary static mesh placement depend on source format behavior and prevents the inspector from exposing a stable renderer component.

The editor needs model drag/drop to create editable static mesh actors for unrigged geometry while retaining explicit, separate paths for skinned geometry and generic full-scene data.

Decision

Model imports now generate deterministic project artifacts under assets/meshes/generated/*.static_mesh.ron. The artifact records stable part IDs, source path, format, the content-addressed source fingerprint owned by ADR 0043, import settings, mesh/material subasset labels, source node/material metadata, dependency paths, and warnings for metadata that is not played by the static mesh path.

The saved scene authoring component is StaticMeshRenderer. Its slots reference imported mesh/material assets by EditorAssetRef (asset_id + sub_asset_id) rather than source file paths. Hydration resolves those refs through the generated artifact, spawns runtime child Mesh3d parts, and strips/regenerates them like other hydrated ECS. Built-in primitives remain Primitive, and explicit full-scene placement remains ImportedModel + ModelRef.

Asset import settings choose the default placement mode:

• StaticAsset creates ActorKind::StaticMesh + StaticMeshRenderer for unrigged sources; when collider generation is enabled it also creates RigidBodyDesc + ColliderDesc::StaticMesh.
• Sources containing skin-bound primitives or animation route to ActorKind::SkinnedMesh + SkinnedMeshRenderer and never create static renderer slots or automatic triangle-mesh colliders (ADR 0033).
• SceneInstance creates the legacy ActorKind::ImportedModel + ModelRef.

Hierarchy mode is also stored per asset. SingleActor places all mesh parts into one renderer. SourceHierarchy creates an authored root with child static mesh actors.

Consequences

• glTF/GLB and FBX placement consume the same renderer contract after processing.
• Scene files store renderer intent, not runtime Bevy mesh/material handles.
• Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector.
• Skinned parts are marked in artifact schema v2 and excluded from static renderer construction and hydration. Animation playback uses the dedicated contract in ADRs 0031 and 0033.
• Static-mesh schema v4 uses byte length plus BLAKE3 rather than checkout mtime, so a source touch is a no-op while a same-size byte edit is detected.
• Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs.