Blacksite/docs/adr/0006-scene-schema-versioning.md

ADR 0006: Scene Schema Versioning

Status

Accepted

Context

Levels under assets/levels/ need forward-compatible migrations as authoring components evolve (M5).

Decision

• Track schema_version in scene files (wrapper or sidecar during transition).
• Provide scene_schema module with migrate_scene_text and validate_level_file.
• Route editor save/load through scene::document::SceneDocument, an internal Bevy-free seam that preserves DynamicScene RON while exposing stable actor/component document identities and patch operations for tools.
• CI / xtask validate-levels loads all committed levels and recursively validates every committed prefab graph, failing on unknown versions or invalid links/override payloads.
• Keep scene Bevy-free. A narrow loader adapter in game validates and migrates .scn.ron assets through scene, strips the schema envelope in memory, and then invokes Bevy's WorldDeserializer. The packaged game and editor therefore hydrate the same versioned prefab files that authoring and CI validate.

Consequences

• Breaking component changes require a migration step and version bump.
• Editor saves wrap levels and prefabs with the schema header; the runtime adapter removes only the envelope before Bevy deserialization.
• The current storage format remains DynamicScene RON; SceneDocument is not a BSN/JSN migration.