BS-JD-002 - Scene document abstraction above DynamicScene RON #4

New Issue

Rbanh · 2026-06-06T01:45:33-04:00

Rbanh commented

2026-06-06 01:45:33 -04:00

Summary

Introduce a SceneDocument layer that tools edit instead of touching Bevy serialization directly, while still round-tripping through current DynamicScene RON.

Why

A document layer makes future diffs, prefab overrides, migrations, and possible BSN/JSN-style formats mechanical instead of tool-specific rewrites.

Implementation notes

Create crates/scene/src/document.rs with SceneDocument, SceneEntity, SceneComponentBlob, and ScenePatch.
Save path: World -> SceneDocument -> DynamicScene RON text.
Load path: RON text -> SceneDocument -> World.
Add patch operations for component set/remove, entity add/delete, reparent, rename, and transform set.
Keep raw Bevy Entity IDs out of document data.

Acceptance criteria

Current levels round-trip through SceneDocument with validator-compatible output.
Save validation still rejects hydrated runtime components.
Transform edit, rename, and component add/remove can be represented as ScenePatch.
Debug logging makes failed migration/diff output readable.

Tests/docs

Golden round-trip tests for current scenes and schema migration. Update scene authoring flow docs and create ADR if format direction hardens.

## Summary Introduce a `SceneDocument` layer that tools edit instead of touching Bevy serialization directly, while still round-tripping through current DynamicScene RON. ## Why A document layer makes future diffs, prefab overrides, migrations, and possible BSN/JSN-style formats mechanical instead of tool-specific rewrites. ## Implementation notes - Create `crates/scene/src/document.rs` with `SceneDocument`, `SceneEntity`, `SceneComponentBlob`, and `ScenePatch`. - Save path: World -> SceneDocument -> DynamicScene RON text. - Load path: RON text -> SceneDocument -> World. - Add patch operations for component set/remove, entity add/delete, reparent, rename, and transform set. - Keep raw Bevy Entity IDs out of document data. ## Acceptance criteria - [ ] Current levels round-trip through `SceneDocument` with validator-compatible output. - [ ] Save validation still rejects hydrated runtime components. - [ ] Transform edit, rename, and component add/remove can be represented as `ScenePatch`. - [ ] Debug logging makes failed migration/diff output readable. ## Tests/docs Golden round-trip tests for current scenes and schema migration. Update scene authoring flow docs and create ADR if format direction hardens.

Rbanh added this to the M0 - Foundation and polish seams milestone 2026-06-06 01:45:34 -04:00

Rbanh added the

labels 2026-06-06 01:45:34 -04:00

Rbanh referenced this issue

2026-06-06 01:49:27 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Rbanh commented

2026-06-06 03:11:35 -04:00

Starting this next.

Initial implementation target:

Add crates/scene/src/document.rs with SceneDocument, SceneEntity, SceneComponentBlob, and ScenePatch types.
Keep the first pass as an internal seam over current DynamicScene RON rather than a format migration.
Add round-trip/patch tests where possible before wiring deeper SceneIo behavior.
Update docs/editor/architecture.md and/or docs index for the scene authoring flow.

Scope guard: no BSN/JSN migration yet; existing RON save/load behavior should remain compatible.

Starting this next. Initial implementation target: - Add `crates/scene/src/document.rs` with `SceneDocument`, `SceneEntity`, `SceneComponentBlob`, and `ScenePatch` types. - Keep the first pass as an internal seam over current DynamicScene RON rather than a format migration. - Add round-trip/patch tests where possible before wiring deeper SceneIo behavior. - Update `docs/editor/architecture.md` and/or docs index for the scene authoring flow. Scope guard: no BSN/JSN migration yet; existing RON save/load behavior should remain compatible.

Rbanh commented

2026-06-06 03:16:23 -04:00

Implementation progress in working tree:

Added scene::document with SceneDocument, SceneEntity, SceneEntityId, SceneComponentBlob, ScenePatch, and SceneTransform.
SceneDocument is Bevy-free and schema-aware; it migrates/validates current DynamicScene RON and exposes stable actor/component concepts without using raw Bevy Entity IDs as document identity.
Added patch representation for set/remove component, add/delete entity, reparent, rename, and set transform.
Routed editor SceneIo save/load through SceneDocument while preserving current DynamicScene RON storage.
Updated scene architecture docs and ADR 0006 to record the internal document seam.

Verification:

cargo fmt --check
cargo test -p scene
cargo check --workspace --all-targets

Remaining before closing:

Expand patch application from in-memory document representation into actual RON/document emission where tools need direct document mutation.
Add deeper golden round-trip coverage for committed scenes and migrations if this becomes the primary mutation layer.

Implementation progress in working tree: - Added `scene::document` with `SceneDocument`, `SceneEntity`, `SceneEntityId`, `SceneComponentBlob`, `ScenePatch`, and `SceneTransform`. - `SceneDocument` is Bevy-free and schema-aware; it migrates/validates current DynamicScene RON and exposes stable actor/component concepts without using raw Bevy `Entity` IDs as document identity. - Added patch representation for set/remove component, add/delete entity, reparent, rename, and set transform. - Routed editor `SceneIo` save/load through `SceneDocument` while preserving current DynamicScene RON storage. - Updated scene architecture docs and ADR 0006 to record the internal document seam. Verification: - `cargo fmt --check` - `cargo test -p scene` - `cargo check --workspace --all-targets` Remaining before closing: - Expand patch application from in-memory document representation into actual RON/document emission where tools need direct document mutation. - Add deeper golden round-trip coverage for committed scenes and migrations if this becomes the primary mutation layer.

Rbanh commented

2026-06-06 03:50:43 -04:00

Implemented and pushed in 2054fa2 (Advance M0 scene and rendering foundations).

What landed:

Added scene::document::SceneDocument, SceneEntity, stable document IDs, component blobs, and ScenePatch vocabulary for component set/remove, entity add/delete, reparent, rename, and transform set.
Routed editor save/load through the document layer while preserving current Bevy DynamicScene RON storage.
Kept raw Bevy Entity IDs out of document identity; actor IDs are used where available and anonymous document IDs are assigned otherwise.
Added round-trip/patch tests and kept scene schema validation active.
Updated scene authoring docs and ADR 0006.

Verification:

cargo test -p scene
cargo test -p settings
cargo test -p shared hydration
cargo test -p game_hot rendering::
cargo check --workspace --all-targets
cargo check --workspace --all-targets --all-features

Notes:

This intentionally keeps the on-disk format as RON for now. Patch application is represented in-memory; broader tool adoption of SceneDocument patches should continue through BS-JD-004/operator work.

Implemented and pushed in `2054fa2` (`Advance M0 scene and rendering foundations`). What landed: - Added `scene::document::SceneDocument`, `SceneEntity`, stable document IDs, component blobs, and `ScenePatch` vocabulary for component set/remove, entity add/delete, reparent, rename, and transform set. - Routed editor save/load through the document layer while preserving current Bevy DynamicScene RON storage. - Kept raw Bevy `Entity` IDs out of document identity; actor IDs are used where available and anonymous document IDs are assigned otherwise. - Added round-trip/patch tests and kept scene schema validation active. - Updated scene authoring docs and ADR 0006. Verification: - `cargo test -p scene` - `cargo test -p settings` - `cargo test -p shared hydration` - `cargo test -p game_hot rendering::` - `cargo check --workspace --all-targets` - `cargo check --workspace --all-targets --all-features` Notes: - This intentionally keeps the on-disk format as RON for now. Patch application is represented in-memory; broader tool adoption of SceneDocument patches should continue through BS-JD-004/operator work.

Rbanh closed this issue

2026-06-06 03:50:47 -04:00

Rbanh referenced this issue

2026-06-06 03:50:56 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Sign in to join this conversation.