Guard editor shutdown and track clean savepoints
This commit is contained in:
1 parent
62b538999d
commit
4b33f32357
19 files changed
+1944
-129
No files matched your search
@@ -56,6 +56,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
|
||||
| [0039](adr/0039-inline-height-grid-terrain-foundation.md) | Inline authored height grids with deterministic runtime-only chunk hydration |
|
||||
| [0040](adr/0040-terrain-material-layer-weights.md) | Four-channel terrain material layers, compact normalized weights, and raster transport |
|
||||
| [0041](adr/0041-transactional-editor-physics-placement.md) | Paused editor physics ownership and transactional gravity placement |
|
||||
| [0042](adr/0042-guarded-editor-shutdown-and-document-savepoints.md) | Guarded native editor exit and canonical per-document clean checkpoints |
|
||||
|
||||
## Editor framework
|
||||
|
||||
@@ -119,6 +120,7 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
|
||||
| `terrain_material_layers_*.plan.md` | Terrain shared-material layers, normalized weights, blended hydration, and modal painting |
|
||||
| `operator_invariants_completion_*.plan.md` | Production operator dispatch, interruption, rollback, cleanup, and undo/redo acceptance |
|
||||
| `editor_sample_regression_pack_*.plan.md` | Five-area sample manifest, editor catalog, deterministic validation, and native regression acceptance |
|
||||
| `guarded_shutdown_savepoints_*.plan.md` | Native close coordination, asynchronous Save All, and canonical history clean points |
|
||||
|
||||
## Crate responsibilities (quick reference)
|
||||
|
||||
|
||||
@@ -34,12 +34,19 @@ assets, mark a scene clean, enter source control, or silently replace authored w
|
||||
or Discard removes that scene's recovery generations. Save Recovery Copy As writes the snapshot
|
||||
to a separate transactional scene file without changing the active scene or recovery lifecycle.
|
||||
- A successful manual save retires recovery generations for that scene.
|
||||
- A successful load or manual save establishes that tab's canonical authored-content checkpoint.
|
||||
Undo and redo compare the current stable authored projection with this checkpoint to derive dirty
|
||||
state. Failed writes, cancelled Save As, and recovery restores do not advance it.
|
||||
- Native editor exit is authorized only after all dirty scene tabs save successfully or the user
|
||||
explicitly discards them. See [ADR 0042](0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
- Interrupted manual writes retain the previous complete destination on filesystems with atomic
|
||||
same-directory rename semantics.
|
||||
- Recovery is machine-local and does not pollute builds or source control.
|
||||
- Undoing exactly to the last loaded or saved authored state clears the dirty marker without
|
||||
weakening recovery after direct edits or failed saves.
|
||||
- Autosave still performs authored serialization and hydration rebuild work. Performance
|
||||
instrumentation and background snapshotting remain follow-up work under the production roadmap.
|
||||
- Unsaved new scenes do not yet have a stable recovery identity; they require a later session-ID
|
||||
|
||||
@@ -20,8 +20,10 @@ untrusted serialized ECS state.
|
||||
- Session schema v1 allowlists metadata only: project root, active scene path, saved dock-layout
|
||||
text, hierarchy expansion paths, non-destructive panel visibility, and finite camera bookmark
|
||||
transforms.
|
||||
- Write the session transactionally. Startup immediately writes `clean_shutdown: false`; normal
|
||||
`AppExit` writes the final document with `clean_shutdown: true`.
|
||||
- Write the session transactionally. Startup immediately writes `clean_shutdown: false`; only an
|
||||
editor-shutdown-coordinator-authorized `AppExit` writes the final document with
|
||||
`clean_shutdown: true`. Direct `AppExit`, forced termination, and process failure retain the
|
||||
abnormal marker. See [ADR 0042](0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
- A clean prior session may restore its active scene and non-destructive UI state automatically.
|
||||
An abnormal prior session starts from the normal safe scene and requires explicit confirmation
|
||||
before opening the prior scene.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# ADR 0042: Guarded Editor Shutdown And Document Savepoints
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Bevy's default native-window policy closes a requested window and exits after the final window is
|
||||
gone. That policy bypasses Blacksite's scene-tab and project-switch confirmations, so a compositor
|
||||
close request could silently discard dirty authored work. Reading `WindowCloseRequested` in another
|
||||
system is insufficient because Bevy's default close system has its own message cursor and still
|
||||
despawns the window.
|
||||
|
||||
Scene dirtiness was also independent of editor history. Every undo or redo marked the active scene
|
||||
dirty, even when undo restored the exact state that had last loaded or saved. Undo depth alone is
|
||||
not a valid savepoint: editor commands contain runtime entity IDs and are intentionally cleared when
|
||||
tabs switch, while saves may establish a clean point in the middle of a timeline.
|
||||
|
||||
## Decision
|
||||
|
||||
- The full editor disables Bevy's automatic close-on-request behavior. The game and Project Browser
|
||||
keep their existing native-window policy.
|
||||
- One editor shutdown coordinator owns native window close, **File > Quit**, project switching, and
|
||||
programmatic editor-exit requests. It coalesces duplicate requests and is the only normal path
|
||||
authorized to emit `AppExit`.
|
||||
- Final authorization runs in a dedicated main schedule after Bevy's `Last` schedule. The guard
|
||||
rechecks dirty scene state after every editor authoring system, then clean-session persistence
|
||||
runs after that finalizer in the same post-`Last` schedule.
|
||||
- A clean editor exits immediately. Dirty scene tabs enter one non-blocking native decision with
|
||||
explicit **Save All**, **Discard**, and **Cancel** actions. Save completion, including an untitled
|
||||
tab's Save As picker, is applied on the main thread. The coordinator exits only after every dirty
|
||||
tab saves or the user explicitly discards; cancel or failure retains the live session.
|
||||
- Clean-session persistence accepts only an exit authorized by the coordinator. Crashes, forced
|
||||
termination, and unguarded `AppExit` retain the abnormal-session marker.
|
||||
- Every scene tab owns a canonical authored-content checkpoint established by a successful load or
|
||||
save. The projection uses stable actor IDs, stable parent actor IDs, sorted component identities,
|
||||
and scene composition; it excludes transient Bevy entity numbers and runtime hydration.
|
||||
- A committed edit marks the active tab dirty. Successful undo or redo compares the current
|
||||
canonical authored projection with that tab's checkpoint. Equality clears the dirty marker;
|
||||
divergence sets it. Failed saves and recovery restores do not advance the checkpoint.
|
||||
- Editor command stacks remain active-document runtime state and are still cleared on tab switches.
|
||||
Checkpoint ownership belongs to the document tab, so dirty truth survives those clears.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Native close can no longer silently discard authored scene tabs, and the editor remains responsive
|
||||
while confirmation or Save As dialogs are open.
|
||||
- A normal exit requires an explicit editor-owned authorization. New code must request shutdown
|
||||
through the coordinator instead of writing `AppExit` directly.
|
||||
- Undoing to the last saved authored state clears title and tab dirty indicators, including after a
|
||||
save at nonzero history depth. Redo or a divergent branch marks the document dirty again.
|
||||
- Reconciliation serializes the authored projection after undo and redo. This is more work than a
|
||||
depth comparison, but it is bounded to explicit history navigation and remains correct across
|
||||
direct non-history repairs, entity respawns, and tab switches.
|
||||
- Operating-system process kill and power loss cannot be confirmed; recovery and abnormal-session
|
||||
handling remain the safety boundary for those cases.
|
||||
@@ -111,6 +111,10 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
components on load and component transactions, and does not prohibit compatible composition such
|
||||
as renderer plus light. Component validation owns requirements and geometry-source conflicts.
|
||||
- **Scene persistence and recovery** use transactional same-directory writes for authored scenes and bounded user-local recovery snapshots for dirty saved scenes. Recovery runs every 120 seconds by default, keeps five generations, never marks the scene clean, and appears as a status/File-menu restore or discard action when newer than the authored file. Restore leaves the original scene dirty until manually saved. See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
|
||||
- **Guarded shutdown and clean savepoints** route native close, **File > Quit**, project switching,
|
||||
and programmatic exit through one non-blocking Save All / Discard / Cancel coordinator. Each tab's
|
||||
dirty marker is reconciled against its canonical last-loaded-or-saved authored projection after
|
||||
undo/redo. See [ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
- **Collaborative file safety** records exact content revisions for loaded scenes, prefab source operations, editable materials, and Project Settings, then rechecks them immediately before atomic publication. External changes, create races, read-only files, and optional ownership locks keep the existing bytes intact and open Reload/Compare Metadata/Save As/Cancel recovery. Git status is asynchronous, observational, and absent without noise outside a repository. See [collaborative-file-safety.md](collaborative-file-safety.md) and [ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
|
||||
- **Scene visualizers** expose actor root icons, colliders, lights, player spawns, gameplay markers, volumes, prefab/model anchors, Project Sun, and runtime player/camera markers without changing saved scene data. Spot lights show inner/outer cones and cameras show near/far frusta. Viewport options independently gate visualizer categories and include actor icon and transform-gizmo size sliders.
|
||||
- **Clean game-view overlay** (`G`) hides editor chrome, grid, selection outlines, transform gizmos, actor root icons, visualizers, and selectable proxies without changing camera ownership; `Ctrl+G` toggles grid.
|
||||
|
||||
@@ -87,11 +87,20 @@ or Cancel. Generated artifacts remain under their subsystem-owned regeneration p
|
||||
[collaborative-file-safety.md](collaborative-file-safety.md) and
|
||||
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
|
||||
|
||||
`project/shutdown.rs` owns native close, **File > Quit**, project switching, and programmatic editor
|
||||
exit. The editor launch configuration leaves native close requests open; the coordinator coalesces
|
||||
them, retries the shared native-dialog broker when busy, and authorizes `AppExit` only after clean
|
||||
state, successful Save All, or explicit Discard. Scene I/O owns the asynchronous per-tab save
|
||||
transaction and reports completion back to the coordinator. Final authorization and clean-session
|
||||
persistence run in an editor schedule inserted after Bevy's `Last`, so material drops, brush/gizmo
|
||||
finalizers, and every other authoring system finish before the last dirty-state check. See
|
||||
[ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
|
||||
`project/session.rs` owns the independent versioned restart document under the user state
|
||||
directory. It snapshots allowlisted paths, panel visibility, dock/hierarchy metadata, and camera
|
||||
bookmarks, writes a running marker at startup, and records clean `AppExit`. Abnormal sessions do
|
||||
not auto-open the prior scene; the explicit safe-resume prompt is the only path back. See
|
||||
[ADR 0024](../adr/0024-versioned-editor-session-state.md).
|
||||
bookmarks, writes a running marker at startup, and records clean state only for a coordinator-
|
||||
authorized `AppExit`. Abnormal sessions do not auto-open the prior scene; the explicit safe-resume
|
||||
prompt is the only path back. See [ADR 0024](../adr/0024-versioned-editor-session-state.md).
|
||||
|
||||
`project/diagnostics_bundle.rs` exports a separate, transactional support report from an explicit
|
||||
metadata allowlist. It summarizes build/renderer identity, project paths, dirty state, aggregate
|
||||
@@ -200,7 +209,7 @@ the Edit-to-Play boundary restore the complete runtime snapshot. See
|
||||
1. User edits entities with `LevelObject` + reflectable components from `shared`.
|
||||
2. `EditorOnly` entities (cameras, helpers) are filtered from hierarchy and save; visualizer proxies can be picked but resolve back to source entities.
|
||||
3. Player placement is stored as `PlayerSpawn`; the runtime `Player` is never serialized.
|
||||
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through `scene::document::SceneDocument`. The active tab is materialized in the ECS world; inactive tabs retain normalized authored snapshots and independent dirty/recovery state. `SceneComposition` resources reference validated project-relative subscenes by stable IDs, and runtime-only `ComposedSceneMember` ownership prevents child actors from being flattened into the owner save. See [multi-scene-composition.md](multi-scene-composition.md) and ADR 0026.
|
||||
4. `SceneIo` writes native Bevy dynamic scenes under `assets/levels/`, routed through `scene::document::SceneDocument`. The active tab is materialized in the ECS world; inactive tabs retain normalized authored snapshots, canonical clean checkpoints, and independent dirty/recovery state. Undo/redo reconciles stable authored content rather than transient ECS entity IDs. `SceneComposition` resources reference validated project-relative subscenes by stable IDs, and runtime-only `ComposedSceneMember` ownership prevents child actors from being flattened into the owner save. See [multi-scene-composition.md](multi-scene-composition.md), ADR 0026, and [ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
5. Hydration systems in `game` spawn meshes, colliders, lights, static mesh renderer parts, and
|
||||
dedicated skinned-model hierarchies at runtime. Level-object roots are initialized with Bevy
|
||||
visibility hierarchy components before generated children are attached, so authoring
|
||||
|
||||
@@ -6,6 +6,11 @@ save/discard/cancel prompt when needed. **File > Open Scene...** opens another t
|
||||
discarding the active document. Save and Save As affect the active tab, while project switching
|
||||
offers to save every modified tab.
|
||||
|
||||
Each tab also retains a canonical checkpoint of the last successfully loaded or saved authored
|
||||
projection. History commands remain active-tab runtime state, but undo and redo reconcile against
|
||||
that document checkpoint. Returning exactly to the checkpoint clears only that tab's dirty marker;
|
||||
redo, a divergent edit, failed save, or restored recovery remains dirty.
|
||||
|
||||
## Composition workflow
|
||||
|
||||
The **Composition** menu beside the tabs edits the active scene's persisted `SceneComposition`:
|
||||
|
||||
@@ -16,6 +16,13 @@ loop or editor rendering.
|
||||
- Collaborative Save As performs the same revision and destination checks after selection.
|
||||
- Close or project switch never treats an opened Save As picker as a completed save. When a save
|
||||
remains pending, the transition pauses and can be retried after saving.
|
||||
- Native window close, **File > Quit**, project switch, and programmatic editor exit share the
|
||||
guarded-shutdown coordinator. Dirty scene tabs present exact **Save All**, **Discard**, and
|
||||
**Cancel** actions. Save All remains pending through each untitled tab's Save As result and exits
|
||||
only after every dirty tab is clean; cancellation or failure preserves the live session.
|
||||
- A close request received while another native dialog owns the broker remains queued. The editor
|
||||
rechecks dirty state and retries acquisition after that workflow completes instead of dropping
|
||||
the request or opening a competing dialog.
|
||||
|
||||
## Covered Surfaces
|
||||
|
||||
@@ -24,6 +31,8 @@ subscene selection, collaborative conflict copies, Project Browser folder select
|
||||
confirmations. New workflows must use the broker instead of calling `rfd` from an egui/Bevy system.
|
||||
|
||||
See [ADR 0038](../adr/0038-non-blocking-native-dialog-broker.md).
|
||||
Guarded exit ownership and document savepoints are defined by
|
||||
[ADR 0042](../adr/0042-guarded-editor-shutdown-and-document-savepoints.md).
|
||||
|
||||
Live native-Wayland acceptance is recorded in the
|
||||
[native-dialog responsiveness evaluation](evaluations/native-dialog-responsiveness/).
|
||||
@@ -13,10 +13,14 @@ or credentials.
|
||||
|
||||
## Restart behavior
|
||||
|
||||
- **Clean shutdown:** the last authored scene and non-destructive UI state are restored.
|
||||
- **Clean shutdown:** after the guarded exit path saves all dirty scene tabs or receives explicit
|
||||
Discard confirmation, the last authored scene and non-destructive UI state are restored.
|
||||
- **Abnormal shutdown:** the editor opens its normal safe scene and displays **Recover Editor
|
||||
Session**. **Resume Last Scene** opens only the previous authored scene. **Continue Safe** keeps
|
||||
the startup scene. Modal tools and dirty preview state are never restored.
|
||||
- Native window close, **File > Quit**, project switching, and programmatic editor exit use one
|
||||
non-blocking Save All / Discard / Cancel workflow. Cancel and failed saves keep the session open.
|
||||
Direct `AppExit`, process kill, and crashes are not recorded as clean shutdowns.
|
||||
- Dirty scene data remains governed by the independent scene recovery workflow in
|
||||
[ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
|
||||
|
||||
|
||||
Reference in new issue
Block a user