Add collaborative authored-file safety
This commit is contained in:
1 parent
b4aa61e394
commit
5a82a9ee29
23 files changed
+2857
-89
No files matched your search
@@ -23,6 +23,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| [navigation-authoring.md](navigation-authoring.md) | Bounds, source geometry, deterministic bake, viewport path preview, and runtime query workflow |
|
||||
| [extensibility.md](extensibility.md) | Static authoring component lifecycle registration, stable IDs, composition, and generic history |
|
||||
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
|
||||
| [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
|
||||
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
|
||||
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
|
||||
|
||||
@@ -43,6 +44,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|
||||
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027 |
|
||||
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, ADR 0027 |
|
||||
| `project/` | Workspace, settings UI, user prefs, support diagnostics | roadmap Phase 1 |
|
||||
| `project/collaboration.rs` | Guarded authored writes, asynchronous Git status, and optional ownership providers | collaborative-file-safety.md, ADR 0037 |
|
||||
| `project/session.rs` | Versioned XDG session document, clean marker, and safe resume | session-recovery.md, ADR 0024 |
|
||||
| `project/diagnostics_bundle.rs` | Privacy-bounded transactional support report export | session-recovery.md, ADR 0024 |
|
||||
| `project/launcher.rs` | Strict project inspection, CLI activation, recent filtering, and sandbox scaffolding | project-launcher.md, ADR 0025 |
|
||||
@@ -86,6 +88,7 @@ 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).
|
||||
- **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.
|
||||
- **Viewport shading** (toolbar): **Lit** (default WYSIWYG), **Unlit** (base-color debug), **Colliders** (hide meshes, emphasize collider gizmos). The viewport combines active shading/render path in one bottom-right chip, draws a camera-relative X/Y/Z orientation widget, identifies the primary selection in a responsive top-right HUD, and previews asset placement with a pointer card, placement reticle, corner brackets, and highlighted drop boundary.
|
||||
|
||||
@@ -29,6 +29,7 @@ Native-only dependencies (`rfd`, BRP HTTP) stay in `editor`. `settings`, `shared
|
||||
| `ActorIconsPlugin` | Selectable actor root billboard icons |
|
||||
| `EditorVisualizersPlugin` | Collider/light/spawn/prefab/runtime visualizers and selectable proxies |
|
||||
| `SceneIoPlugin` | Level New/Open/Save, recent paths |
|
||||
| `CollaborationPlugin` | Exact authored-file guards, asynchronous Git status, optional ownership providers |
|
||||
| `OperatorPlugin` | Active operator lifecycle/status for commands and modal tools |
|
||||
| `SettingsUiPlugin` | egui Project Settings panel |
|
||||
| `EditorUiPlugin` | Dock, themed egui shell, viewport overlays, menus, status bar |
|
||||
@@ -76,6 +77,15 @@ The bounded in-session scene I/O event log feeds the Diagnostics window so a lat
|
||||
does not erase a save or recovery failure.
|
||||
See [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
|
||||
|
||||
`project/collaboration.rs` wraps user-authored publication with BLAKE3 baselines and a second
|
||||
revision/read-only check immediately before the same-directory rename. Scene tabs, prefab source
|
||||
Apply/history, staged Material documents, and Project Settings use this shared boundary. Its worker
|
||||
observes path-scoped Git porcelain and optional ownership providers without blocking the frame loop
|
||||
or changing repository state; conflict recovery is explicit Reload, metadata comparison, Save As,
|
||||
or Cancel. Generated artifacts remain under their subsystem-owned regeneration policy. See
|
||||
[collaborative-file-safety.md](collaborative-file-safety.md) and
|
||||
[ADR 0037](../adr/0037-collaborative-authored-file-safety.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
|
||||
@@ -151,7 +161,7 @@ The egui layer lives under `crates/editor/src/ui/`:
|
||||
| `diagnostics.rs` | Detailed stats (Window → Diagnostics, Asset Browser footer) |
|
||||
| `layout.rs` | Dock layout RON persistence in `editor_prefs.ron` |
|
||||
|
||||
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
|
||||
The Viewport fills the tab (no inline help text). Gizmo/grid/play controls sit on a near-black semi-transparent overlay, and `G` hides editor-only overlays for a clean game view. The fixed dark status strip prioritizes `SceneIo.status` feedback and also shows scene path/dirty state, compact active-file collaboration status, mode, selection count, history, and the active operator. Long feedback is truncated responsively and available in a hover tooltip. Dock layout restores from `~/.config/bevy-fps/editor_prefs.ron` on startup; **View → Reset Layout** restores defaults.
|
||||
|
||||
**Follow-up (Phase 4b):** inspector search and richer per-asset previews.
|
||||
|
||||
@@ -247,7 +257,7 @@ PIE stop restores player simulation state only; authored `LevelObject` edits mad
|
||||
| `viewport/` | Camera, selection, gizmos, render views, panel settings |
|
||||
| `play/` | PIE session, editor mode, net editor profiles |
|
||||
| `assets/` | Catalog, asset DB, static mesh artifacts, prefab overrides |
|
||||
| `project/` | Project I/O and settings UI |
|
||||
| `project/` | Project I/O, settings UI, authored-file safety, and observational collaboration status |
|
||||
| `ext/` | Command palette, BRP, game panel adapters |
|
||||
| `history/` | Undo commands + plugin |
|
||||
| `ui/` | egui dock shell |
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# Collaborative File Safety
|
||||
|
||||
Blacksite protects loaded user-authored documents with exact content revisions. This layer covers
|
||||
scene and prefab documents, editable Material and Material Instance assets, and `assets/project.ron`.
|
||||
Generated import artifacts, registries, thumbnails, navigation bakes, recovery snapshots, and package output keep
|
||||
their subsystem-owned regeneration rules and never interrupt editing with authored-file conflicts.
|
||||
|
||||
## Status Surfaces
|
||||
|
||||
The bottom status strip shows a compact state for the active saved scene. The selected asset's
|
||||
Details header shows the same state when the asset has an on-disk source. Hover either indicator for
|
||||
the path, Git state, read-only state, ownership detail, and scanner diagnostics.
|
||||
|
||||
When Git is available, Blacksite distinguishes clean, modified, untracked, and conflicted files.
|
||||
The path-scoped scanner uses only `rev-parse` and NUL-delimited `status --porcelain`; it never
|
||||
stages, commits, resets, checks out, restores, or discards files. A missing Git executable or
|
||||
project outside a repository is a normal quiet state.
|
||||
|
||||
## Save Conflicts
|
||||
|
||||
On load, the editor records a BLAKE3 revision and file metadata. Save verifies that revision before
|
||||
preparing the atomic replacement and again immediately before rename. A changed, newly created, or
|
||||
read-only target remains untouched and opens the collaborative-file dialog.
|
||||
|
||||
The dialog provides:
|
||||
|
||||
- **Reload**: discard the editor draft for that document and load the current disk revision.
|
||||
- **Compare Metadata**: show expected/current revision, byte size, modified time, and permissions.
|
||||
- **Save As**: preserve the editor draft at a separately chosen path, guarded against a create race.
|
||||
- **Cancel**: keep the editor draft and make no filesystem change.
|
||||
|
||||
There is intentionally no force-overwrite action. Resolve or preserve the other revision first.
|
||||
|
||||
## Ownership Providers
|
||||
|
||||
Teams can register an implementation of `FileOwnershipProvider` with
|
||||
`register_file_ownership_provider`. Providers receive the active project root and a bounded list of
|
||||
currently tracked project-relative paths on the background scan worker. They return owner/lock
|
||||
details per path.
|
||||
|
||||
A lock held by another user blocks authored publication and uses the same recovery dialog. Provider
|
||||
errors appear only in indicator details; the exact filesystem revision guard continues to work. An
|
||||
empty provider registry performs no calls and adds no UI.
|
||||
|
||||
## Recovery Notes
|
||||
|
||||
- Scene Reload explicitly replaces the active dirty document with disk content and clears its local
|
||||
history. Use Save As first when both versions matter.
|
||||
- Material Reload discards only the staged Details draft and reloads the asset on the next draw.
|
||||
- Project Settings Reload strictly parses the current manifest, reapplies it live, and refreshes the
|
||||
panel draft; invalid external RON stays blocked and visible.
|
||||
- Prefab Apply conflicts keep instance overrides intact. Reload tears down stale hydration and
|
||||
queues the current source for rehydration; retry Apply after reviewing Changed Base/conflict
|
||||
state, or Save As to preserve the proposed source copy.
|
||||
- Prefab source undo/redo stays blocked when the exact expected source revision is absent.
|
||||
|
||||
The architectural policy is recorded in
|
||||
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md).
|
||||
@@ -147,7 +147,7 @@ with implementation sequencing in
|
||||
| Milestone | Exit condition | Status |
|
||||
|-----------|----------------|--------|
|
||||
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
|
||||
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#48 are complete. Source-control safety #49 and final readiness gate #50 remain; packaged acceptance is deferred until requested by the project owner. |
|
||||
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#48 are complete. #49 implementation and source/headless acceptance are complete, with live visual acceptance pending; final readiness gate #50 remains. Packaged acceptance is deferred until requested by the project owner. |
|
||||
|
||||
Production readiness is not inferred from feature count. Gitea
|
||||
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
|
||||
|
||||
Reference in new issue
Block a user