46 lines
2.9 KiB
Markdown
46 lines
2.9 KiB
Markdown
# 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](0043-content-addressed-import-fingerprints.md), 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.
|