Make imported asset fingerprints deterministic

This commit is contained in:
Rbanh committed 2026-07-13 11:23:06 -04:00
1 parent a048233fce
commit e1b2f86a49
27 files changed
+798 -135

No files matched your search

+1
View File
@@ -57,6 +57,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [0040](adr/0040-terrain-material-layer-weights.md) | Four-channel terrain material layers, compact normalized weights, and raster transport |
| [0041](adr/0041-transactional-editor-physics-placement.md) | Paused editor physics ownership and transactional gravity placement |
| [0042](adr/0042-guarded-editor-shutdown-and-document-savepoints.md) | Guarded native editor exit and canonical per-document clean checkpoints |
| [0043](adr/0043-content-addressed-import-fingerprints.md) | Content-addressed imported-source identity and byte-preserving artifact publication |
## Editor framework
@@ -13,7 +13,12 @@ retaining explicit, separate paths for skinned geometry and generic full-scene d
## Decision
Model imports now generate deterministic project artifacts under `assets/meshes/generated/*.static_mesh.ron`. The artifact records stable part IDs, source path, format, source fingerprint, 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.
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`.
@@ -35,4 +40,6 @@ Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts int
- 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.
@@ -42,6 +42,12 @@ startup entrypoint. Unknown newer scene schemas are rejected rather than down-st
requirements are explicit findings; for example, Solari projects record the required forward-path
fallback QA when ray tracing is unavailable.
Imported model, texture, and audio registry records, animation manifests, and static-mesh manifests
share the content-addressed fingerprint contract in
[ADR 0043](0043-content-addressed-import-fingerprints.md). Validation hashes source bytes and catches
same-size changes without consulting mtimes. The validation entry point is read-only; CI asserts that
running both level and sample validation leaves the checkout unchanged.
Terrain descriptors participate in the same actor-owned dependency pass. Their authored dimensions,
height and weight grids, chunk settings, base material, and material layers are validated before
hydration so a sample or shipping scene cannot hide an invalid or unresolved terrain reference.
@@ -58,3 +64,5 @@ hydration so a sample or shipping scene cannot hide an invalid or unresolved ter
editor UI and headless tooling consume the same scene ordering and validation result.
- CI must hydrate Git LFS before validation because a pointer file is intentionally treated as
missing runtime content.
- Validators report stale or incomplete import fingerprints with repair guidance but never rewrite
the registry or generated artifacts.
@@ -0,0 +1,55 @@
# ADR 0043: Content-Addressed Import Fingerprints
## Status
Accepted
## Context
Generated model artifacts and the project asset registry must be stable across contributors, CI,
Git worktrees, and LFS checkouts. Git does not preserve source-file modification times. Persisting a
checkout mtime as source identity therefore caused the editor to rewrite otherwise equivalent
animation and static-mesh manifests during startup. Static-mesh manifests also used only byte length
and mtime, so a same-size source edit could evade the persisted identity contract.
Formatting-only publication was a second source of noise. Re-serializing an equivalent RON
document could normalize its final newline or layout even when import semantics had not changed.
That made clean-checkout release evidence unreliable and obscured intentional asset edits.
## Decision
`shared::AssetSourceFingerprint` is the persisted imported-source identity. It contains the exact
source byte length and lowercase BLAKE3 digest. Filesystem timestamps are not serialized or compared
as semantic identity; an importer may use them only as an in-memory scan hint before confirming
content.
The asset registry stores this fingerprint for every imported model, texture, and audio source.
Content identity also drives unique move reconciliation, so metadata-only drift cannot replace a
stable registry UUID. Ambiguous copies still receive a new identity.
Animation and static-mesh manifests use the same fingerprint. Animation schema v3 already contained
a content hash, so its schema remains v3 and legacy `modified_unix_secs` fields are accepted as
ignored unknown metadata. Static-mesh schema v4 replaces its length-plus-mtime record with length
plus BLAKE3. Existing schema-v3 static artifacts are regenerated once; unrelated assets are not
reimported.
Registry and generated-manifest writers parse the existing RON and compare the semantic value before
publication. Equivalent documents preserve their exact existing bytes, including layout and final
newlines. Changed documents publish canonical pretty RON.
Authoritative project validation remains read-only. It validates registry, animation, and
static-mesh fingerprints by length and digest, including same-size source edits. CI runs both
headless validators and then asserts that tracked and untracked checkout state is unchanged.
## Consequences
- A source touch or fresh checkout mtime cannot dirty the project.
- Same-size source edits invalidate the affected registry/manifests deterministically.
- Model, texture, and audio IDs survive uniquely identifiable moves by content.
- Initial migration adds fingerprints to imported registry records and upgrades static manifests to
schema v4. Legacy animation files can remain byte-identical indefinitely because their timestamp
field is ignored.
- Startup hashing reads imported source bytes. Future scan caches may use metadata to avoid work,
but they must verify content before persisting a changed identity.
- External glTF/FBX dependency paths remain explicit manifest dependencies; extending fingerprints
to a dependency graph requires a separate versioned contract.
+11 -4
View File
@@ -68,10 +68,11 @@ serialize into authored scenes.
`SkinnedMeshRenderer`, skeleton references, and clip references carry the model registry UUID. Generated
artifacts are keyed by that UUID; source paths are cached resolution and repair hints. When one
model is moved or renamed on disk, catalog refresh reconciles it by its animation-manifest content
hash, preserves the UUID, and regenerates both manifests with the new source path. An identical copy
is not treated as a move while the original still exists. Ambiguous content matches intentionally
receive a new identity rather than silently binding the wrong asset.
model is moved or renamed on disk, catalog refresh reconciles it by the registry's shared
content-addressed source fingerprint, preserves the UUID, and regenerates both manifests with the
new source path. The same registry policy covers textures and audio clips. An identical copy is not
treated as a move while the original still exists. Ambiguous content matches intentionally receive
a new identity rather than silently binding the wrong asset.
Scene schema v3 migrates legacy animated actors that paired `ModelRef` with
`AnimationControllerDesc` to the dedicated skinned renderer. Generic `ImportedModel + ModelRef`
@@ -83,6 +84,12 @@ used as identity. Animation-manifest schema v1 artifacts must be reimported to g
signatures; schema v3 adds the explicit default-clip ID. Schema v2 deserializes as Imported rest
pose and never receives an inferred default.
Source identity uses exact byte length plus BLAKE3 and never checkout mtime. Existing animation
schema-v3 files may retain a legacy `modified_unix_secs` field in their exact bytes; the current
reader ignores it, and an equivalent refresh preserves the whole file unchanged. Static-mesh schema
v4 uses the same content fingerprint. See
[ADR 0043](../adr/0043-content-addressed-import-fingerprints.md).
## Validation And Format Boundary
Interactive diagnostics and `cargo validate-levels` resolve registry UUIDs, generated manifests,
+5 -1
View File
@@ -224,7 +224,11 @@ the Edit-to-Play boundary restore the complete runtime snapshot. See
- **Processing:** the asset registry generates normalized model manifests under
`assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset
labels, whether each part is skin-bound, source metadata, dependencies, and import settings.
These artifacts are hidden from the Asset Browser catalog.
Model, texture, and audio registry records use byte length plus BLAKE3 source identity; model
manifests use the same policy. Semantic RON comparison preserves exact existing bytes for an
equivalent refresh, so checkout mtimes and formatting do not dirty project content. See
[ADR 0043](../adr/0043-content-addressed-import-fingerprints.md). These artifacts are hidden from
the Asset Browser catalog.
- **Browser subassets:** model rows can expand into a content shelf backed by the generated
manifest. Unrigged mesh subassets place as independent `StaticMeshRenderer` actors. A skinned
subasset places its owning source through `SkinnedMeshRenderer`, retaining joints and inverse bind
+2 -1
View File
@@ -2,7 +2,8 @@
## Shipped
- Stable asset registry (`assets/.index/registry.ron`) with import settings
- Stable asset registry (`assets/.index/registry.ron`) with import settings and content-addressed
model/texture/audio source fingerprints
- Prefab instances (`PrefabInstance`) + save-as-prefab workflow
- Unsaved-scene guards on New/Open/Recent
- Hierarchy additive select, reparent/unparent undo, multi-entity gizmo delta