Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/collider-diagnostics
Blacksite/docs/editor/session-recovery.md
Rbanh 0553a85220
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Build production-ready editor authoring workflows
2026-07-11 12:41:04 -04:00

2.1 KiB
Raw Permalink 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: 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.
  • Dirty scene data remains governed by the independent scene recovery workflow in ADR 0023.

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.