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

ADR 0005: Prefab Instance and Asset Registry

Status

Accepted

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.
• 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.

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.
• Registry must be version-controlled with the project.