Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
cadb37341d
Blacksite/docs/editor/session-recovery.md

3.1 KiB
Raw Blame History

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.
  • 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.

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.