Blacksite/docs/adr/0005-prefab-instance-and-asset-registry.md

ADR 0005: Prefab Instance and Asset Registry

Status

Accepted for asset identity; structural ownership superseded by ADR 0027

Context

Editor prefab placement and content pipeline work (H1/H2) require stable asset identity across sessions. The asset browser previously regenerated UUIDs on every sync, breaking references.

Decision

• Persist stable AssetId (UUID) per assets/ path in assets/.index/registry.ron.
• Scene-instance ModelRef stores the registry UUID plus a cached source path. Hydration resolves the UUID-keyed generated manifest first, allowing uniquely identified model moves to retain scene and animation references.
• Catalog refresh reconciles a missing model record to one new path only when its generated content hash has exactly one match. Copies and ambiguous matches receive new IDs.
• Introduce PrefabInstance { asset_id, source_path, overrides_ron } on placed prefab roots alongside hydration via PrefabRef.
• Scene save includes PrefabInstance and gameplay marker components from shared.
• The initial structural boundary treated instance contents as read-only and required Unpack before authored structural edits. ADR 0027 replaces that boundary with explicit generated-member ownership while retaining this ADR's asset and instance identity.

Consequences

• Prefab paths can be resolved through the registry for dependency tracking.
• Override apply/revert (H2) builds on overrides_ron without changing the instance component shape.
• Stable child identity, authored local children, nested instances, variants, and recursive graph validation are defined by ADR 0027.
• Registry must be version-controlled with the project.
• Legacy path-only ModelRef values remain readable but require reassignment before they gain stable move resolution.