72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
# ADR 0047: Editor Authored-Asset Documents and Two-Phase Publication
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Material controls previously updated the viewport immediately but also wrote source when a pointer
|
|
interaction ended. That publication could trigger file guards, Git refresh, watcher work,
|
|
thumbnail invalidation, and whole-project processing on the editor frame thread. A slider release
|
|
therefore behaved like an implicit save and could freeze the editor.
|
|
|
|
Project RON files and registry metadata are already suitable authoritative source documents. The
|
|
editor needs a fast, durable edit boundary without adding an opaque asset database or conflating
|
|
editor-dirty documents with source-control status.
|
|
|
|
## Decision
|
|
|
|
The editor owns an `AuthoredAssetDocumentStore` keyed by stable asset ID and document kind. It
|
|
holds clean and current values, source path, loaded file revision, editor revision, publication
|
|
error, recovery state, and derived-processing state for Materials, Material Instances, model import
|
|
settings, Texture import settings, and project content defaults.
|
|
|
|
Interactive controls mutate the current document and `blacksite_surface`'s stable-ID-keyed
|
|
`LiveMaterialDocumentOverlay` in the same tick. `SurfaceMaterialCache` is the sole owner of project
|
|
Material and Material Instance handles; resolution is overlay-first and disk-second. Controls
|
|
perform no source write, watcher refresh, Git query, thumbnail invalidation, or derived processing,
|
|
including when the pointer is released. Dirtiness is derived from `current != clean` and remains
|
|
distinct from Git `MODIFIED`, `UNTRACKED`, and `CONFLICT` state.
|
|
|
|
The cache never polls file metadata or reparses a project Material for every bound entity. Explicit
|
|
Save and accepted watcher events invalidate the disk generation once; interactive overlay
|
|
revisions mutate the existing cached handle in place. Imported glTF/FBX source materials stay on
|
|
their AssetServer-owned path and do not enter the project-material resolver.
|
|
|
|
`Ctrl+S` saves the last edited context. `Ctrl+Shift+S` and **File > Save All** save every dirty
|
|
scene, authored asset document, and project setting. Source publication remains guarded and atomic.
|
|
Registry-backed documents use a clean registry baseline plus per-document overlays so saving one
|
|
setting cannot publish another unsaved setting.
|
|
|
|
Successful source publication advances the clean value, then classifies its
|
|
`DerivedProcessingImpact`. Scalar, color, emissive, shader-value, label, and render-state Material
|
|
changes queue no derived work. ARM/ORM texture or channel changes queue material packing; Texture
|
|
settings, model settings, and project defaults queue only their exact dependency closure. Packing
|
|
signatures exclude scalar multipliers and are checked before image decoding so an existing
|
|
content-addressed artifact can be reused. The previous valid runtime artifact remains authoritative until replacement
|
|
publication succeeds; a processing failure is reported separately and does not make saved source
|
|
dirty again. Stale job completions are ignored.
|
|
|
|
Dirty asset documents receive editor-local recovery snapshots after two seconds of inactivity,
|
|
with five generations retained outside `assets/`. Startup restoration never overwrites source: a
|
|
changed source fingerprint restores the document as an external conflict. Guarded shutdown and
|
|
project switching count scenes, assets, and project settings in the same Save All / Discard /
|
|
Cancel decision. Returning a document exactly to its clean value retires any older recovery
|
|
generation on the next editor tick. Startup also discards a recovery envelope whose value already
|
|
matches authoritative source, covering a crash between the clean edit and that cleanup tick.
|
|
|
|
## Consequences
|
|
|
|
- Parameter editing and pointer release stay frame-local and responsive.
|
|
- Material and direct-base Instance users share one stable live handle authority instead of
|
|
competing editor and renderer caches.
|
|
- Saving source and generating derived artifacts are observable, independent phases.
|
|
- The project remains plain, reviewable RON plus source assets; no asset binary database is added.
|
|
- Unsaved editor state survives selection changes and can be recovered after a crash without
|
|
affecting Git until the user saves.
|
|
- Packaging and read-only processing validation must reject required pending or failed derived
|
|
work rather than silently packaging stale content.
|
|
- Import, extract, create, rename, move, and delete remain explicit immediate transactions because
|
|
they create or remove project identity.
|