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
@@ -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.
|
||||
Reference in new issue
Block a user