51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
# Editor Session Recovery
|
|
|
|
Blacksite stores restart metadata in the user state directory, separate from project assets and
|
|
source-controlled settings:
|
|
|
|
- `$XDG_STATE_HOME/blacksite-editor/session.ron`, or
|
|
- `~/.local/state/blacksite-editor/session.ron` when `XDG_STATE_HOME` is unset.
|
|
|
|
The file uses schema v1 and is written transactionally. It contains project and scene paths, dock
|
|
and hierarchy metadata, non-destructive panel visibility, finite viewport camera bookmarks, and a
|
|
clean-shutdown marker. It never contains scene contents, unsaved tool previews, environment values,
|
|
or credentials.
|
|
|
|
## Restart behavior
|
|
|
|
- **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. The prompt blocks interaction with the safe scene until either choice is made.
|
|
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).
|
|
- Dirty Materials, Material Instances, import settings, and project content defaults receive
|
|
editor-local recovery snapshots after two seconds of inactivity. Five generations are retained
|
|
outside project `assets/`. Startup restoration never overwrites source: a changed fingerprint
|
|
restores the document as a conflict. Returning the document exactly to its source value clears
|
|
older recovery generations; startup defensively ignores any recovery value that already matches
|
|
source. See
|
|
[ADR 0047](../adr/0047-editor-authored-asset-documents.md).
|
|
|
|
An unknown newer session schema is ignored safely. Legacy unversioned session documents migrate to
|
|
v1 after finite camera bookmark validation.
|
|
|
|
## Diagnostic bundles
|
|
|
|
**Window → Diagnostics → Export Diagnostic Bundle** writes a timestamped RON report under
|
|
`$XDG_STATE_HOME/blacksite-editor/diagnostics` or
|
|
`~/.local/state/blacksite-editor/diagnostics`. The write uses the same transactional replace
|
|
primitive as session and scene recovery data.
|
|
|
|
The v1 report allowlists editor and Bevy versions, target OS/architecture and build profile,
|
|
renderer adapter/backend/driver identity, project and active-scene paths, dirty flags, aggregate
|
|
level/brush validation counts, the prior-abnormal-shutdown flag, and up to 32 bounded Scene I/O
|
|
events. It excludes ECS and scene payloads, asset contents, environment values, host/user identity,
|
|
credentials, access tokens, camera transforms, and modal operator state. Review the plain-text RON
|
|
file before sharing it when project paths are sensitive.
|