Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity
19c4d017dc
Blacksite/docs/adr/0009-authoring-vs-hydrated.md
Rbanh f29712d158
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Initial project import
2026-06-05 21:44:45 -04:00

1.3 KiB
Raw Blame History

ADR 0009: Authoring vs hydrated components

Status

Accepted

Context

Level data must round-trip through save/load without leaking runtime ECS components (meshes, Bevy lights, physics, scene instances). Editors that expose raw ECS in the main inspector cause users to edit hydrated state that is overwritten on the next hydration pass.

Decision

  • Authoring components (Primitive, StaticMeshRenderer, MaterialDesc, MaterialOverride, LightDesc, ModelRef, RigidBodyDesc, ColliderDesc, legacy PhysicsBody, ActorKind, etc.) are the only components written to .scn.ron.
  • Hydration in crates/shared/src/hydration/ generates runtime components in a fixed Update chain.
  • Save path uses an explicit DynamicSceneBuilder allowlist and strip_hydrated_entity on each entity before serialize.

Consequences

  • Hydration modules must strip conflicting runtime components before re-insert (especially lights).
  • Static mesh renderer hydration spawns generated child mesh parts; those children are runtime state, not durable scene entities. Static mesh collision is authored through ColliderDesc::StaticMesh and hydrated onto generated mesh children.
  • Inspector and BRP mutate authoring components only.
  • CI and unit tests cover strip/hydrate invariants in shared.