Make imported asset fingerprints deterministic
This commit is contained in:
1 parent
a048233fce
commit
e1b2f86a49
27 files changed
+798
-135
No files matched your search
@@ -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.
|
||||
@@ -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,
|
||||
|
||||
@@ -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,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
|
||||
|
||||
Reference in new issue
Block a user