Compare commits

..
Author SHA1 Message Date
Rbanh 931f561e7f Document FBX dependency acceptance
CI / Format, lint, test, build (push) Has been cancelled
2026-07-13 14:08:25 -04:00
Rbanh 3e30c61c71 Resolve FBX external texture dependencies 2026-07-13 13:41:23 -04:00
Rbanh 7e99243a78 Record deterministic asset acceptance
CI / Format, lint, test, build (push) Waiting to run
2026-07-13 12:09:19 -04:00
Rbanh cbd380a941 Stabilize asset registry publication order 2026-07-13 11:46:51 -04:00
Rbanh e1b2f86a49 Make imported asset fingerprints deterministic 2026-07-13 11:23:06 -04:00
Rbanh a048233fce Record guarded shutdown and scoped UI acceptance
CI / Format, lint, test, build (push) Waiting to run
2026-07-13 10:23:56 -04:00
Rbanh 9e23ae731f Fix scoped editor UI action state 2026-07-13 06:39:30 -04:00
Rbanh 4b33f32357 Guard editor shutdown and track clean savepoints 2026-07-13 05:12:43 -04:00
Rbanh 62b538999d Record sample pack native acceptance
CI / Format, lint, test, build (push) Waiting to run
2026-07-13 04:18:56 -04:00
Rbanh d52cc2e3b7 Fix sample hydration rendering regressions 2026-07-13 03:07:31 -04:00
Rbanh 06010c5922 Add editor sample regression pack 2026-07-13 01:52:58 -04:00
92 changed files with 9130 additions and 1235 deletions

No files matched your search

+1
View File
@@ -7,6 +7,7 @@ rustflags = ["-C", "link-arg=-fuse-ld=mold"]
[alias] [alias]
clean-target = "run -p xtask --bin clean-target --" clean-target = "run -p xtask --bin clean-target --"
validate-levels = "run -p xtask --features validate-levels --bin validate-levels --" validate-levels = "run -p xtask --features validate-levels --bin validate-levels --"
validate-samples = "run -p xtask --features validate-samples --bin validate-samples --"
bake-navigation = "run -p xtask --features validate-levels --bin bake-navigation --" bake-navigation = "run -p xtask --features validate-levels --bin bake-navigation --"
package-project = "run -p xtask --features validate-levels --bin package-project --" package-project = "run -p xtask --features validate-levels --bin package-project --"
upgrade-project = "run -p xtask --features validate-levels --bin upgrade-project --" upgrade-project = "run -p xtask --features validate-levels --bin upgrade-project --"
@@ -0,0 +1,38 @@
# Deterministic Imported-Asset Fingerprints
**Status:** Complete at `cbd380a9413411667a83f74b66c5a2feda5e1af7`; see
[`docs/editor/evaluations/deterministic-asset-fingerprints/`](../../docs/editor/evaluations/deterministic-asset-fingerprints/).
## Scope
Implement Gitea #56 so imported-source identity is content-addressed and editor/validator runs do
not rewrite project artifacts because checkout timestamps or serialization whitespace changed.
## Contract
- Persist one shared fingerprint for imported model, texture, and audio sources: byte length plus a
BLAKE3 digest of the exact source bytes.
- Do not persist or compare source mtimes as semantic identity. Legacy timestamp fields remain
readable but are ignored.
- Static-mesh and animation manifests use the same content identity as the asset registry.
- Preserve stable registry UUIDs across metadata-only drift and uniquely identifiable source moves.
- Before writing a registry or generated manifest, compare the parsed semantic document; preserve
the existing bytes when the result is equivalent.
- Project validators stay read-only and validate both length and digest, including same-size edits.
## Implementation
1. Add the shared fingerprint type and migrate animation/static-mesh contracts.
2. Persist fingerprints for model, texture, and audio registry records and generalize move recovery.
3. Make registry and manifest publication semantic and byte-preserving.
4. Extend static-mesh and registry validation plus focused migration/read-only tests.
5. Update ADRs, asset-pipeline docs, CI clean-worktree assertion, and committed generated artifacts.
## Verification
- Focused editor and scene tests for mtime-only drift, same-size changes, legacy manifests,
byte-preserving equivalent refresh, imported source kinds, and read-only validation.
- Formatting, diff check, clippy, and workspace all-target tests.
- Native editor startup and asset refresh with before/after Git status and source timestamp drift.
- `cargo validate-levels --project .` and `cargo validate-samples --project .`, followed by a clean
worktree assertion. Packaged-runtime tests remain deferred by owner direction.
@@ -0,0 +1,66 @@
# Editor Sample Regression Pack
Date: 2026-07-13
Issue: BS-JD-501 / Gitea #32
Milestone: M5 - Regression, docs, and first-hour UX
## Goal
Ship a deterministic five-scene editor regression pack that is easy to open from the editor and
that fails headless validation when its catalog, authored data, or referenced assets drift. The pack
must cover Brush, Material, Terrain, Physics Placement, and Rendering workflows.
## Decisions
- `assets/samples/editor_samples.ron` is the conventional, versioned pack manifest. This remains a
QA/editor convention and does not extend `ProjectSettings`.
- The manifest is parsed and validated in the `scene` crate. Editor UI and headless tooling consume
that one representation.
- Every entry has a stable ID, label, area, project-relative `.scn.ron` path, summary, and nonempty
operator checks. Manifest order is menu and report order.
- Exactly one entry for each required area is release-gated. Scene paths must remain regular files
inside `assets/levels/`; traversal, absolute paths, symlink escapes, duplicates, and future schemas
are blocking.
- Existing accepted terrain, physics-placement, and rendering fixtures remain canonical entries.
Add dedicated brush and material scenes under `assets/levels/samples/` and strengthen weak visual
anchors in the existing fixtures instead of duplicating them.
- `cargo validate-samples --project .` combines pack-specific structure/feature checks with the
authoritative `validate_project` report. It verifies stable actor IDs, required area components,
authoring-only scene documents, and referenced content.
- Terrain descriptors and their shared material layers become first-class project-validation input.
Actor-owned invalid descriptors or missing material references are blocking findings.
- `File > Open Sample` is backed by a cached project catalog and opens through normal scene-tab I/O.
Invalid or unavailable catalogs produce a disabled, actionable row rather than a panic.
- CI hydrates Git LFS before content validation and runs both validation commands. Packaged-runtime
tests remain deferred by project-owner request.
## Implementation
1. Add the manifest schema, deterministic report, safe path resolver, and sample feature checks to
`scene::sample_pack`, with malformed/missing/duplicate/path-escape fixture tests.
2. Add typed `TerrainDesc` validation and base/layer material dependency collection to authoritative
project validation, including owner-attributed tests.
3. Add the `validate-samples` xtask binary, Cargo alias, JSON mode, stable console summary, and CI
steps. Enable LFS hydration at checkout and verify hydrated objects.
4. Add the five-entry manifest, `brush_blockout.scn.ron`, and `material_lab.scn.ron`. Give every
sample actor a stable `ActorId`; add visible rendering anchors and distinct physics shapes where
the current fixtures are ambiguous.
5. Load the catalog after project startup, render `File > Open Sample` in manifest order, and route a
selected stable ID through scene I/O. Add unknown-entry and deterministic-row tests.
6. Add a no-GPU typed-deserialization test over every manifest scene so unknown Bevy component
registrations fail before native QA.
7. Document pack contracts, per-scene checks, release commands, and the editor workflow. Update ADR
0028, the root README checklist/controls, editor/docs indexes, feature guides, roadmap status,
debt audit, and production-readiness evidence.
8. Run source gates, open all five samples through the native menu, exercise one representative tool
interaction per area, inspect logs, and attach representative native issue images when useful.
## Acceptance
- Five manifest entries cover all required areas and open through `File > Open Sample`.
- Every entry type-deserializes and has stable actor IDs plus its required authored feature.
- `validate-levels` reports terrain material dependencies and has no blocking findings.
- `validate-samples` is deterministic, CI-backed, and exits nonzero for pack or project blockers.
- Native viewport captures are nonblank, correctly framed, and free of missing-reference, hydration,
render, or operator errors.
- Documentation gives contributors a single release-use workflow and explains every sample check.
@@ -0,0 +1,44 @@
# FBX External Texture Dependencies
**Issue:** Gitea #58 (`BS-JD-210`)
## Goal
Make FBX external texture discovery deterministic from import through runtime loading. Missing or
unsafe references must be reported before the Asset Browser queues Bevy loads, while an explicit
Authoring Override remains a supported untextured workflow.
## Scope
1. Add one path-safe FBX texture-reference resolver shared by the local `bevy_ufbx` loader and the
editor asset pipeline. Normalize separators, deduplicate references, retain relative `textures/`
and `.fbm/` layouts, and reject absolute or parent-traversing references.
2. Decode external images through the FBX `LoadContext`, reuse one handle per normalized path, and
consolidate unavailable dependency logging so duplicate ufbx texture records cannot create
repeated asset-server failures.
3. Generate static-mesh dependencies from parsed FBX texture references. Treat them as required for
Source Materials and as declared-but-optional for Authoring Override during read-only project
validation.
4. Replace the FBX-only file copy with a staged bundle transaction that preflights every referenced
file, preserves relative sidecar layout, backs up overwritten destinations, and rolls back a
partial commit.
5. Preflight source-material thumbnails, retain neutral direct FBX mesh/model previews, and expose a
stable failure reason plus missing dependency status in the Asset Browser.
6. Deliberately normalize the committed painted-chair fixture to Authoring Override rather than add
large absent 2K textures.
## Verification
- Unit tests for sibling `textures/`, `.fbm/`, duplicate references, missing files, path traversal,
destination symlink containment, transactional preservation, consolidated project findings, and
read-only validation.
- `cargo fmt`, focused crate tests, workspace Clippy, workspace tests, `validate-levels`, and
`validate-samples`. Packaged tests remain deferred by project-owner direction.
- Native editor QA for the painted chair and an intentionally broken Source Materials variant,
including log inspection and screenshots published as ordinary Gitea attachments.
## Documentation
- Record the cross-crate dependency/override contract in ADR 0044.
- Update editor architecture, Asset Browser workflow, root controls/checklist, documentation maps,
and an issue-specific evaluation record.
@@ -0,0 +1,62 @@
# Guarded Shutdown And History Savepoints
Date: 2026-07-13
Issue: BS-PR-709 / Gitea #55
Milestone: M7 - Production Readiness
## Goal
Route every editor-exit surface through one non-blocking dirty-document decision and make scene
dirtiness follow the authored undo timeline. Closing the native window, choosing File > Quit, and
requesting an editor exit programmatically must never silently discard dirty scene tabs.
## Decisions
- The editor disables Bevy's automatic close-and-exit systems and owns primary-window close
requests. A guarded-shutdown resource is the single authority that may emit `AppExit`.
- The final dirty-state recheck and `AppExit` authorization run in a dedicated schedule after
Bevy's `Last`; session clean-marker persistence runs after that finalizer.
- Native window close, File > Quit, and internal editor quit requests enqueue the same shutdown
intent. Repeated requests while confirmation or Save As is pending are coalesced.
- Clean sessions exit immediately. Dirty sessions use the shared `NativeDialogBroker` and a single
Save All / Discard / Cancel decision. Cancel preserves all tabs and live editor state; Discard
exits without rewriting authored files; Save All exits only after every dirty tab is saved.
- Untitled tabs and other asynchronous Save As work keep shutdown pending until their dialog result
is applied on the main thread. Cancellation or any failed write returns the editor to an idle,
dirty, recoverable state and does not emit `AppExit`.
- Each scene tab retains a canonical authored-content checkpoint established only by a successful
load or save. The checkpoint is keyed by stable actor identity, canonical component order, stable
parent identity, and scene composition rather than transient Bevy entity numbers.
- Push marks the active document dirty. Undo and redo serialize the authoritative authored
projection and compare it with that tab's checkpoint, so saving at nonzero history depth,
returning to that point, branching, tab switches, and direct non-history mutations remain exact.
## Implementation
1. Add per-tab canonical clean checkpoints to scene I/O and reconcile `SceneIo::dirty` after push,
undo, redo, save, load, and document switches without persisting Entity-ID-based history stacks.
2. Add focused history tests for undo-to-clean, redo-away-from-clean, save at nonzero depth,
branching before/after the clean point, and tab isolation.
3. Add a guarded-shutdown plugin/resource that intercepts `WindowCloseRequested`, accepts menu and
programmatic requests, coordinates non-blocking confirmation/save completion, and emits the only
final `AppExit` for the full editor.
4. Make Save All report complete, pending, cancelled, or failed explicitly. Resume pending shutdown
after untitled Save As completion and preserve the originating tab plus dirty state on failure.
5. Add File > Quit and route Switch Project's exit half through the same guard without spawning a
replacement process until the dirty-document decision succeeds.
6. Update ADR 0023, native-dialog/session-recovery documentation, editor architecture guidance,
root README controls/checklist, and production-readiness evidence.
7. Run formatting, strict Clippy, workspace tests, and focused headless state-machine tests. Keep
packaged tests deferred by project-owner direction.
8. Launch the exact editor commit under Hyprland. Exercise Cancel, Discard, Save All, clean close,
File > Quit, and the compositor close button; verify the editor remains responsive during native
dialogs, no state is lost on cancel/failure, and no process or warning remains after exit.
## Acceptance
- Native close, File > Quit, and programmatic editor exit share one guarded implementation.
- One or many dirty tabs cannot be lost without explicit Discard; failed or cancelled saves do not
exit and preserve the session.
- Undoing exactly to the saved state clears the dirty marker; redo or a divergent edit restores it.
- Saving at nonzero history depth establishes a new clean point without deleting useful history.
- Headless state-machine tests and exact-commit native Linux QA pass with clean logs.
+13
View File
@@ -17,6 +17,11 @@ jobs:
steps: steps:
- name: Checkout - name: Checkout
uses: actions/checkout@v4 uses: actions/checkout@v4
with:
lfs: true
- name: Verify Git LFS checkout
run: git lfs fsck
- name: Install Linux dependencies - name: Install Linux dependencies
run: | run: |
@@ -55,6 +60,14 @@ jobs:
- name: Validate level scenes - name: Validate level scenes
run: cargo validate-levels run: cargo validate-levels
- name: Validate editor sample pack
run: cargo validate-samples
- name: Assert validation leaves checkout clean
run: |
git diff --exit-code
test -z "$(git ls-files --others --exclude-standard)"
- name: Clippy launch feature matrix - name: Clippy launch feature matrix
run: cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings run: cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings
+23 -6
View File
@@ -27,6 +27,7 @@ cargo clippy --workspace --all-targets -- -D warnings
cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings
cargo test --workspace cargo test --workspace
cargo validate-levels cargo validate-levels
cargo validate-samples
cargo bake-navigation --project . --check cargo bake-navigation --project . --check
# Validate one artifact without opening a game window # Validate one artifact without opening a game window
cargo run -p game -- --validate-navigation assets/navigation/generated/navigation_showcase_humanoid.nav.ron cargo run -p game -- --validate-navigation assets/navigation/generated/navigation_showcase_humanoid.nav.ron
@@ -56,8 +57,9 @@ cargo run -p editor --bin project_launcher --features dev
``` ```
The installed **Blacksite Editor** desktop entry also exposes **Open Project Browser** from its The installed **Blacksite Editor** desktop entry also exposes **Open Project Browser** from its
desktop action menu. In the editor, **File > Switch Project...** performs a clean shutdown and desktop action menu. In the editor, **File > Switch Project...** uses the guarded Save All / Discard /
opens the same browser; choosing a project starts a fresh editor process with that root. Cancel shutdown path before opening the same browser; choosing a project starts a fresh editor
process with that root.
### Hot reload (gameplay iteration) ### Hot reload (gameplay iteration)
@@ -135,7 +137,7 @@ deep-stale variants.
| Click empty viewport / `Esc` | Deselect | | Click empty viewport / `Esc` | Deselect |
| `Delete` / `Backspace` | Delete selection | | `Delete` / `Backspace` | Delete selection |
| `Ctrl+D` | Duplicate selection | | `Ctrl+D` | Duplicate selection |
| `Ctrl+Z` / `Ctrl+Shift+Z` / `Ctrl+Y` | Undo / redo | | `Ctrl+Z` / `Ctrl+Shift+Z` / `Ctrl+Y` | Undo / redo; returning exactly to the last loaded or saved authored state clears that scene tab's dirty marker |
| `F2` in Hierarchy | Rename selection | | `F2` in Hierarchy | Rename selection |
| `W` / `E` / `R` | Translate / rotate / scale gizmo; multi-selection uses one grouped gizmo and undo step | | `W` / `E` / `R` | Translate / rotate / scale gizmo; multi-selection uses one grouped gizmo and undo step |
| `X` | Toggle world/local gizmo orientation | | `X` | Toggle world/local gizmo orientation |
@@ -164,7 +166,8 @@ deep-stale variants.
| Drag actor between rows / onto Scene Root (Hierarchy, Manual sort) | Reorder siblings / unparent to the root | | Drag actor between rows / onto Scene Root (Hierarchy, Manual sort) | Reorder siblings / unparent to the root |
| Hierarchy lock | Excludes the actor from selection, gizmos, multi-drag, structural drops, and mutating context actions | | Hierarchy lock | Excludes the actor from selection, gizmos, multi-drag, structural drops, and mutating context actions |
| Hierarchy context | Group selection, create authored local children below linked prefab roots, remove/reparent generated members through same-layer structural overrides, or unparent | | Hierarchy context | Group selection, create authored local children below linked prefab roots, remove/reparent generated members through same-layer structural overrides, or unparent |
| File menu | New, non-blocking native Open/Save As, recovery restore/keep-copy/discard when available, Import Assets, Export Selection, Save Selection As Prefab (including linked-root variants), Recent Scenes | | File menu | New, non-blocking native Open/Save As, **Open Sample** for the five-area regression pack, recovery restore/keep-copy/discard when available, Import Assets, Export Selection, Save Selection As Prefab (including linked-root variants), Recent Scenes, Switch Project, and Quit |
| Window close / **File > Quit** | Clean sessions exit immediately; dirty scene tabs use one non-blocking **Save All / Discard / Cancel** decision, and cancel or failed saves keep the editor open |
| Status strip / Asset Details source-state chip | Inspect compact clean, modified, untracked, conflicted, read-only, and optional ownership status; hover for the source path and provider details | | Status strip / Asset Details source-state chip | Inspect compact clean, modified, untracked, conflicted, read-only, and optional ownership status; hover for the source path and provider details |
| Authored File Not Saved dialog | Resolve an external edit, read-only target, or ownership lock with Reload, Compare Metadata, Save As, or Cancel; the editor never offers force overwrite | | Authored File Not Saved dialog | Resolve an external edit, read-only target, or ownership lock with Reload, Compare Metadata, Save As, or Cancel; the editor never offers force overwrite |
| Main toolbar, right side | Switch or close independent scene tabs, create an untitled tab, and manage loaded/locked composed subscenes | | Main toolbar, right side | Switch or close independent scene tabs, create an untitled tab, and manage loaded/locked composed subscenes |
@@ -374,6 +377,8 @@ The `.vscode/` folder is preconfigured:
- [ADR 0017: Normalized Static Mesh Assets](docs/adr/0017-normalized-static-mesh-assets.md) - [ADR 0017: Normalized Static Mesh Assets](docs/adr/0017-normalized-static-mesh-assets.md)
- [ADR 0034: Registry-driven Authoring Components](docs/adr/0034-registry-driven-authoring-components.md) - [ADR 0034: Registry-driven Authoring Components](docs/adr/0034-registry-driven-authoring-components.md)
- [ADR 0037: Collaborative Authored-File Safety](docs/adr/0037-collaborative-authored-file-safety.md) - [ADR 0037: Collaborative Authored-File Safety](docs/adr/0037-collaborative-authored-file-safety.md)
- [ADR 0043: Content-Addressed Import Fingerprints](docs/adr/0043-content-addressed-import-fingerprints.md)
- [ADR 0044: Sandboxed FBX External Texture Dependencies](docs/adr/0044-sandboxed-fbx-external-texture-dependencies.md)
## Project Layout ## Project Layout
@@ -409,6 +414,8 @@ crates/
- [x] Transactional physics placement with real Avian gravity/colliders, paused Edit-mode physics, prerequisite diagnostics, isolated non-selected bodies, exact cancel, and grouped transform undo ([ADR 0041](docs/adr/0041-transactional-editor-physics-placement.md), [workflow guide](docs/editor/physics-placement.md), [Gitea #25](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/25)) - [x] Transactional physics placement with real Avian gravity/colliders, paused Edit-mode physics, prerequisite diagnostics, isolated non-selected bodies, exact cancel, and grouped transform undo ([ADR 0041](docs/adr/0041-transactional-editor-physics-placement.md), [workflow guide](docs/editor/physics-placement.md), [Gitea #25](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/25))
- [x] Collider authoring health shared by the inspector, Collider viewport, Diagnostics panel, and physics placement, with scaled shape overlays, cooked mesh bounds, missing/stale/invalid/oversized findings, and undoable dimension-preserving shape switching ([collider guide](docs/editor/collider-authoring.md), [Gitea #26](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/26)) - [x] Collider authoring health shared by the inspector, Collider viewport, Diagnostics panel, and physics placement, with scaled shape overlays, cooked mesh bounds, missing/stale/invalid/oversized findings, and undoable dimension-preserving shape switching ([collider guide](docs/editor/collider-authoring.md), [Gitea #26](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/26))
- [x] Non-blocking native file/folder/confirmation broker across scene, asset, prefab, composition, collaboration, and Project Browser workflows ([ADR 0038](docs/adr/0038-non-blocking-native-dialog-broker.md), [workflow guide](docs/editor/native-dialogs.md), [Gitea #52](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/52)) - [x] Non-blocking native file/folder/confirmation broker across scene, asset, prefab, composition, collaboration, and Project Browser workflows ([ADR 0038](docs/adr/0038-non-blocking-native-dialog-broker.md), [workflow guide](docs/editor/native-dialogs.md), [Gitea #52](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/52))
- [x] Guarded native/menu/programmatic editor shutdown with asynchronous multi-tab Save All / Discard / Cancel and canonical per-tab clean checkpoints for exact undo/redo dirtiness ([ADR 0042](docs/adr/0042-guarded-editor-shutdown-and-document-savepoints.md), [Gitea #55](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/55))
- [x] Scoped egui action safety for toolbar/navigation spawns, Inspector state, cross-panel selection/tab requests, diagnostics selection, and full-slice selection precedence ([evaluation](docs/editor/evaluations/scoped-ui-actions/), [Gitea #57](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/57))
- [x] Asset import, static mesh/prefab placement, texture assignment, and selection export - [x] Asset import, static mesh/prefab placement, texture assignment, and selection export
- [x] PIE player-only snapshot/restore (authored `LevelObject` edits persist on stop) - [x] PIE player-only snapshot/restore (authored `LevelObject` edits persist on stop)
- [x] Unified viewport render-to-texture target + Play session bootstrap - [x] Unified viewport render-to-texture target + Play session bootstrap
@@ -417,11 +424,18 @@ crates/
- [x] Cursor/VSCode workspace tasks + launch configs - [x] Cursor/VSCode workspace tasks + launch configs
- [x] Opaque Wayland window launch defaults + SDR/HDR runtime toggle - [x] Opaque Wayland window launch defaults + SDR/HDR runtime toggle
- [x] CI workflow for format, check, clippy, tests, and binary builds - [x] CI workflow for format, check, clippy, tests, and binary builds
- [x] Deterministic five-area editor sample regression pack with stable actor IDs, **File > Open Sample**, typed scene checks, headless validation, and committed brush/material/terrain/physics/rendering fixtures ([sample guide](docs/editor/sample-regression-pack.md), [Gitea #32](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/32))
- [x] ADRs for roadmap architecture and Bevy migration policy - [x] ADRs for roadmap architecture and Bevy migration policy
- [x] Determinism harness: same inputs over same ticks produce the same state summary/hash - [x] Determinism harness: same inputs over same ticks produce the same state summary/hash
- [x] Production operator invariants across palette dispatch, assets/material drops, brush/terrain/physics modal tools, grouping/lighting, and the transform finalizer: stable terminal status, exact cancel/failure rollback, helper cleanup, grouped history, and repeated undo/redo projections ([testing contract](docs/editor/operator-regression-testing.md), [evaluation](docs/editor/evaluations/operator-invariants/), [Gitea #33](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/33)) - [x] Production operator invariants across palette dispatch, assets/material drops, brush/terrain/physics modal tools, grouping/lighting, and the transform finalizer: stable terminal status, exact cancel/failure rollback, helper cleanup, grouped history, and repeated undo/redo projections ([testing contract](docs/editor/operator-regression-testing.md), [evaluation](docs/editor/evaluations/operator-invariants/), [Gitea #33](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/33))
- [x] Verify: `cargo fmt --check` / `cargo check --workspace` / `cargo clippy --workspace` / strict foundation clippy / `cargo test -p sim` - [x] Verify: `cargo fmt --check` / `cargo check --workspace` / `cargo clippy --workspace` / strict foundation clippy / `cargo test -p sim`
- [x] Stable asset registry with UUIDs + import settings in asset browser details - [x] Stable asset registry with UUIDs + import settings in asset browser details
- [x] Deterministic imported-source fingerprints for models, textures, and audio; BLAKE3-backed
static/animation manifests; byte-preserving equivalent refresh; and read-only validator checkout
assertions ([ADR 0043](docs/adr/0043-content-addressed-import-fingerprints.md), [evaluation](docs/editor/evaluations/deterministic-asset-fingerprints/), [Gitea #56](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/56))
- [x] Sandboxed FBX external-texture discovery for sibling and `.fbm/` layouts, transactional
referenced-bundle import, manifest-first consolidated validation, deduplicated loader reads, and
stable Asset Browser dependency status ([ADR 0044](docs/adr/0044-sandboxed-fbx-external-texture-dependencies.md), [Gitea #58](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/58))
- [x] Asset Browser expandable model subasset shelves, independent mesh/material/texture thumbnails, staged import/material details with shader-schema parameters, context actions, and trash-first file removal - [x] Asset Browser expandable model subasset shelves, independent mesh/material/texture thumbnails, staged import/material details with shader-schema parameters, context actions, and trash-first file removal
- [x] Audio clip catalog/import foundation for Ogg, WAV, MP3, and FLAC with dedicated filtering, file details, and stable runtime-resolvable asset references - [x] Audio clip catalog/import foundation for Ogg, WAV, MP3, and FLAC with dedicated filtering, file details, and stable runtime-resolvable asset references
- [x] Audio source/listener authoring, non-dirty spatial audition, viewport icons/range gizmos, stable buses, PIE/runtime parity, device diagnostics, and shared release validation ([ADR 0030](docs/adr/0030-audio-authoring-and-bus-schema.md); production acceptance completed in [Gitea #47](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/47)) - [x] Audio source/listener authoring, non-dirty spatial audition, viewport icons/range gizmos, stable buses, PIE/runtime parity, device diagnostics, and shared release validation ([ADR 0030](docs/adr/0030-audio-authoring-and-bus-schema.md); production acceptance completed in [Gitea #47](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/47))
@@ -469,8 +483,11 @@ crates/
- The editor asset browser is filesystem-backed with folder/tree navigation, grid/list views, - The editor asset browser is filesystem-backed with folder/tree navigation, grid/list views,
texture and model thumbnails (glTF albedo fast-path; offscreen render studio for FBX and texture and model thumbnails (glTF albedo fast-path; offscreen render studio for FBX and
untextured models), material sphere thumbnails, search/filter/sort controls, expandable model untextured models), material sphere thumbnails, search/filter/sort controls, expandable model
subasset shelves, and a staged details pane. **File → Import Assets** subasset shelves, and a staged details pane. **File -> Import Assets**
accepts glTF/GLB and **FBX** (binary; copies sibling `.fbm` texture folders when present). accepts glTF/GLB and binary **FBX**. FBX import parses and transactionally preserves every safe
referenced sibling `textures/` or `.fbm/` file while rejecting traversal and external absolute
paths before project content changes. Missing source textures appear once in validation and Asset
Browser dependency status; **Authoring Override** deliberately permits an untextured model.
Model assets generate normalized model manifests under `assets/meshes/generated/`; drag/drop uses Model assets generate normalized model manifests under `assets/meshes/generated/`; drag/drop uses
**Renderable Asset (Auto)**. Unrigged sources use `StaticMeshRenderer` with imported asset refs **Renderable Asset (Auto)**. Unrigged sources use `StaticMeshRenderer` with imported asset refs
and optional separate static mesh colliders. Skin-bound or animated sources and their subasset placement use and optional separate static mesh colliders. Skin-bound or animated sources and their subasset placement use
+531 -441
View File
File diff suppressed because it is too large. Load diff
@@ -35,7 +35,7 @@
), ),
}), }),
2: (components: { 2: (components: {
"bevy_ecs::name::Name": "Placement Prop A", "bevy_ecs::name::Name": "Placement Cuboid",
"bevy_transform::components::transform::Transform": ( "bevy_transform::components::transform::Transform": (
translation: (-2.0, 3.0, 0.0), translation: (-2.0, 3.0, 0.0),
rotation: (0.1305262, 0.0, 0.0, 0.9914449), rotation: (0.1305262, 0.0, 0.0, 0.9914449),
@@ -70,7 +70,7 @@
), ),
}), }),
3: (components: { 3: (components: {
"bevy_ecs::name::Name": "Placement Prop B", "bevy_ecs::name::Name": "Placement Sphere",
"bevy_transform::components::transform::Transform": ( "bevy_transform::components::transform::Transform": (
translation: (0.0, 5.0, 0.0), translation: (0.0, 5.0, 0.0),
rotation: (0.0, 0.2164396, 0.0, 0.976296), rotation: (0.0, 0.2164396, 0.0, 0.976296),
@@ -96,16 +96,16 @@
parameters: [], parameters: [],
textures: [], textures: [],
), ),
"shared::components::Primitive": (shape: Box, size: (1.0, 1.6, 1.0)), "shared::components::Primitive": (shape: Sphere, size: (1.6, 1.6, 1.6)),
"shared::components::RigidBodyDesc": (body: Static), "shared::components::RigidBodyDesc": (body: Static),
"shared::components::ColliderDesc": ( "shared::components::ColliderDesc": (
enabled: true, enabled: true,
is_trigger: false, is_trigger: false,
shape: Cuboid(x_length: 1.0, y_length: 1.6, z_length: 1.0), shape: Sphere(radius: 0.8),
), ),
}), }),
4: (components: { 4: (components: {
"bevy_ecs::name::Name": "Placement Prop C", "bevy_ecs::name::Name": "Placement Capsule",
"bevy_transform::components::transform::Transform": ( "bevy_transform::components::transform::Transform": (
translation: (2.0, 7.0, 0.0), translation: (2.0, 7.0, 0.0),
rotation: (0.092296, 0.092296, -0.008077, 0.991405), rotation: (0.092296, 0.092296, -0.008077, 0.991405),
@@ -131,12 +131,12 @@
parameters: [], parameters: [],
textures: [], textures: [],
), ),
"shared::components::Primitive": (shape: Box, size: (1.4, 0.8, 1.0)), "shared::components::Primitive": (shape: Box, size: (0.9, 1.8, 0.9)),
"shared::components::RigidBodyDesc": (body: Static), "shared::components::RigidBodyDesc": (body: Static),
"shared::components::ColliderDesc": ( "shared::components::ColliderDesc": (
enabled: true, enabled: true,
is_trigger: false, is_trigger: false,
shape: Cuboid(x_length: 1.4, y_length: 0.8, z_length: 1.0), shape: Capsule(radius: 0.45, height: 1.8),
), ),
}), }),
5: (components: { 5: (components: {
+235 -62
View File
@@ -1,68 +1,241 @@
(schema_version: 4,resources: { (schema_version: 4, resources: {}, entities: {
}, 1: (components: {
entities: { "bevy_ecs::name::Name": "Rendering Lab Floor",
4294968001: (components: { "bevy_transform::components::transform::Transform": (
"bevy_ecs::name::Name": "Fog Volume", translation: (1.0, -0.25, 0.0),
"bevy_transform::components::transform::Transform": ( rotation: (0.0, 0.0, 0.0, 1.0),
translation: (0.0, 2.0, 0.0), scale: (1.0, 1.0, 1.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
), ),
"shared::components::ActorKind": PostProcessVolume, "shared::components::ActorId": ("rendering-showcase-floor"),
"shared::components::LevelObject": (), "shared::components::ActorKind": StaticMesh,
"shared::components::PostProcessVolumeDesc": ( "shared::components::EditorVisibility": (visible: true),
half_extents: (6.0, 3.0, 6.0), "shared::components::HierarchySiblingIndex": (0),
priority: 0, "shared::components::LevelObject": (),
blend_distance: 2.0, "shared::components::Primitive": (shape: Box, size: (38.0, 0.5, 12.0)),
overrides: ( "shared::components::MaterialDesc": (
fog_density: Some(0.004), shader: (kind: StandardLit, schema_path: None, shader_path: None),
fog_color: Some((r: 0.5, g: 0.55, b: 0.65, a: 1.0)), base_color: (r: 0.12, g: 0.14, b: 0.16, a: 1.0),
), metallic: 0.05,
fullscreen_effect: None, roughness: 0.72,
profile: None, emissive_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
label: Some("Foggy courtyard"), emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: None,
parameters: [],
textures: [],
), ),
}), }),
4294968002: (components: { 2: (components: {
"bevy_ecs::name::Name": "Dark Exposure Volume", "bevy_ecs::name::Name": "Vignette Anchor",
"bevy_transform::components::transform::Transform": ( "bevy_transform::components::transform::Transform": (
translation: (14.0, 2.0, 0.0), translation: (-12.0, 1.2, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0), rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0), scale: (1.0, 1.0, 1.0),
), ),
"shared::components::ActorKind": PostProcessVolume, "shared::components::ActorId": ("rendering-showcase-vignette-anchor"),
"shared::components::LevelObject": (), "shared::components::ActorKind": StaticMesh,
"shared::components::PostProcessVolumeDesc": ( "shared::components::EditorVisibility": (visible: true),
half_extents: (4.0, 2.5, 4.0), "shared::components::HierarchySiblingIndex": (1),
priority: 5, "shared::components::LevelObject": (),
blend_distance: 1.5, "shared::components::Primitive": (shape: Sphere, size: (2.4, 2.4, 2.4)),
overrides: ( "shared::components::MaterialDesc": (
exposure_ev100: Some(9.5), shader: (kind: StandardLit, schema_path: None, shader_path: None),
bloom: Some(false), base_color: (r: 0.82, g: 0.18, b: 0.2, a: 1.0),
), metallic: 0.08,
fullscreen_effect: None, roughness: 0.38,
profile: Some("assets/rendering_profiles/cave_dark.ron"), emissive_color: (r: 1.0, g: 0.2, b: 0.2, a: 1.0),
label: Some("Cave mouth"), emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: None,
parameters: [],
textures: [],
), ),
}), }),
4294968003: (components: { 3: (components: {
"bevy_ecs::name::Name": "Vignette FX Volume", "bevy_ecs::name::Name": "Fog Anchor",
"bevy_transform::components::transform::Transform": ( "bevy_transform::components::transform::Transform": (
translation: (-12.0, 2.0, 0.0), translation: (0.0, 1.4, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0), rotation: (0.0, 0.258819, 0.0, 0.9659258),
scale: (1.0, 1.0, 1.0), scale: (1.0, 1.0, 1.0),
), ),
"shared::components::ActorKind": PostProcessVolume, "shared::components::ActorId": ("rendering-showcase-fog-anchor"),
"shared::components::LevelObject": (), "shared::components::ActorKind": StaticMesh,
"shared::components::PostProcessVolumeDesc": ( "shared::components::EditorVisibility": (visible: true),
half_extents: (5.0, 2.0, 5.0), "shared::components::HierarchySiblingIndex": (2),
priority: 2, "shared::components::LevelObject": (),
blend_distance: 2.0, "shared::components::Primitive": (shape: Box, size: (2.8, 2.8, 2.8)),
overrides: (), "shared::components::MaterialDesc": (
fullscreen_effect: Some("assets/post_fx/vignette.ron"), shader: (kind: StandardLit, schema_path: None, shader_path: None),
profile: None, base_color: (r: 0.1, g: 0.58, b: 0.72, a: 1.0),
label: Some("Vignette demo"), metallic: 0.15,
roughness: 0.35,
emissive_color: (r: 0.1, g: 0.58, b: 0.72, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: None,
parameters: [],
textures: [],
), ),
}), }),
}, 4: (components: {
) "bevy_ecs::name::Name": "Exposure Anchor",
"bevy_transform::components::transform::Transform": (
translation: (14.0, 1.3, 0.0),
rotation: (0.0, -0.1736482, 0.0, 0.9848078),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-exposure-anchor"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (3),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (3.0, 2.6, 3.0)),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.92, g: 0.62, b: 0.12, a: 1.0),
metallic: 0.12,
roughness: 0.32,
emissive_color: (r: 1.0, g: 0.65, b: 0.12, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: None,
parameters: [],
textures: [],
),
}),
5: (components: {
"bevy_ecs::name::Name": "Emissive Comparison Panel",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 2.6, -4.8),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-emissive-panel"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (4),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (26.0, 1.2, 0.25)),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.15, g: 0.22, b: 0.28, a: 1.0),
metallic: 0.0,
roughness: 0.35,
emissive_color: (r: 0.55, g: 0.85, b: 1.0, a: 1.0),
emissive_intensity: 2500.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/emissive_panel.ron"),
parameters: [],
textures: [],
),
}),
6: (components: {
"bevy_ecs::name::Name": "Fog Volume",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 2.0, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-fog-volume"),
"shared::components::ActorKind": PostProcessVolume,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (5),
"shared::components::LevelObject": (),
"shared::components::PostProcessVolumeDesc": (
half_extents: (6.0, 3.0, 6.0),
priority: 0,
blend_distance: 2.0,
overrides: (
fog_density: Some(0.004),
fog_color: Some((r: 0.5, g: 0.55, b: 0.65, a: 1.0)),
),
fullscreen_effect: None,
profile: None,
label: Some("Foggy courtyard"),
),
}),
7: (components: {
"bevy_ecs::name::Name": "Dark Exposure Volume",
"bevy_transform::components::transform::Transform": (
translation: (14.0, 2.0, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-exposure-volume"),
"shared::components::ActorKind": PostProcessVolume,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (6),
"shared::components::LevelObject": (),
"shared::components::PostProcessVolumeDesc": (
half_extents: (4.0, 2.5, 4.0),
priority: 5,
blend_distance: 1.5,
overrides: (
exposure_ev100: Some(9.5),
bloom: Some(false),
),
fullscreen_effect: None,
profile: Some("assets/rendering_profiles/cave_dark.ron"),
label: Some("Cave mouth"),
),
}),
8: (components: {
"bevy_ecs::name::Name": "Vignette FX Volume",
"bevy_transform::components::transform::Transform": (
translation: (-12.0, 2.0, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-vignette-volume"),
"shared::components::ActorKind": PostProcessVolume,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (7),
"shared::components::LevelObject": (),
"shared::components::PostProcessVolumeDesc": (
half_extents: (5.0, 2.0, 5.0),
priority: 2,
blend_distance: 2.0,
overrides: (),
fullscreen_effect: Some("assets/post_fx/vignette.ron"),
profile: None,
label: Some("Vignette demo"),
),
}),
9: (components: {
"bevy_ecs::name::Name": "Rendering Lab Sun",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 10.0, 5.0),
rotation: (-0.3826834, 0.0, 0.0, 0.9238795),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("rendering-showcase-sun"),
"shared::components::ActorKind": Light,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (8),
"shared::components::LevelObject": (),
"shared::components::LightDesc": (
kind: Directional,
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
intensity: 100000.0,
range: 0.0,
shadows: true,
inner_angle_deg: 25.0,
outer_angle_deg: 35.0,
),
}),
})
@@ -0,0 +1,332 @@
(schema_version: 4, resources: {}, entities: {
1: (components: {
"bevy_ecs::name::Name": "Foundation Brush",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 0.5, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-brush-foundation"),
"shared::components::ActorKind": Brush,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (0),
"shared::components::LevelObject": (),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.55, g: 0.54, b: 0.52, a: 1.0),
metallic: 0.0,
roughness: 0.85,
emissive_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/concrete.ron"),
parameters: [],
textures: [],
),
"shared::components::BrushDesc": (
kind: Additive,
faces: [
(
id: ("face:+x"),
plane: (normal: (1.0, 0.0, 0.0), distance: 5.0),
vertices: [(5.0, -0.5, -4.0), (5.0, 0.5, -4.0), (5.0, 0.5, 4.0), (5.0, -0.5, 4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-x"),
plane: (normal: (-1.0, 0.0, 0.0), distance: 5.0),
vertices: [(-5.0, -0.5, 4.0), (-5.0, 0.5, 4.0), (-5.0, 0.5, -4.0), (-5.0, -0.5, -4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+y"),
plane: (normal: (0.0, 1.0, 0.0), distance: 0.5),
vertices: [(-5.0, 0.5, -4.0), (-5.0, 0.5, 4.0), (5.0, 0.5, 4.0), (5.0, 0.5, -4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-y"),
plane: (normal: (0.0, -1.0, 0.0), distance: 0.5),
vertices: [(-5.0, -0.5, 4.0), (-5.0, -0.5, -4.0), (5.0, -0.5, -4.0), (5.0, -0.5, 4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+z"),
plane: (normal: (0.0, 0.0, 1.0), distance: 4.0),
vertices: [(5.0, -0.5, 4.0), (5.0, 0.5, 4.0), (-5.0, 0.5, 4.0), (-5.0, -0.5, 4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-z"),
plane: (normal: (0.0, 0.0, -1.0), distance: 4.0),
vertices: [(-5.0, -0.5, -4.0), (-5.0, 0.5, -4.0), (5.0, 0.5, -4.0), (5.0, -0.5, -4.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
],
cast_shadows: true,
receive_shadows: true,
),
}),
2: (components: {
"bevy_ecs::name::Name": "Material Face Tower",
"bevy_transform::components::transform::Transform": (
translation: (-2.5, 3.0, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-brush-material-tower"),
"shared::components::ActorKind": Brush,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (1),
"shared::components::LevelObject": (),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.55, g: 0.54, b: 0.52, a: 1.0),
metallic: 0.0,
roughness: 0.85,
emissive_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/concrete.ron"),
parameters: [],
textures: [],
),
"shared::components::BrushDesc": (
kind: Additive,
faces: [
(
id: ("face:+x"),
plane: (normal: (1.0, 0.0, 0.0), distance: 1.25),
vertices: [(1.25, -2.0, -1.25), (1.25, 2.0, -1.25), (1.25, 2.0, 1.25), (1.25, -2.0, 1.25)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-x"),
plane: (normal: (-1.0, 0.0, 0.0), distance: 1.25),
vertices: [(-1.25, -2.0, 1.25), (-1.25, 2.0, 1.25), (-1.25, 2.0, -1.25), (-1.25, -2.0, -1.25)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+y"),
plane: (normal: (0.0, 1.0, 0.0), distance: 2.0),
vertices: [(-1.25, 2.0, -1.25), (-1.25, 2.0, 1.25), (1.25, 2.0, 1.25), (1.25, 2.0, -1.25)],
material: Some((
asset_id: "cc2769da-c9a5-4cb3-866a-cc81d0688ee2",
sub_asset_id: "material:instance",
label: "surface_tint_instance",
source_path: Some("assets/materials/surface_tint_instance.ron"),
)),
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-y"),
plane: (normal: (0.0, -1.0, 0.0), distance: 2.0),
vertices: [(-1.25, -2.0, 1.25), (-1.25, -2.0, -1.25), (1.25, -2.0, -1.25), (1.25, -2.0, 1.25)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+z"),
plane: (normal: (0.0, 0.0, 1.0), distance: 1.25),
vertices: [(1.25, -2.0, 1.25), (1.25, 2.0, 1.25), (-1.25, 2.0, 1.25), (-1.25, -2.0, 1.25)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-z"),
plane: (normal: (0.0, 0.0, -1.0), distance: 1.25),
vertices: [(-1.25, -2.0, -1.25), (-1.25, 2.0, -1.25), (1.25, 2.0, -1.25), (1.25, -2.0, -1.25)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
],
cast_shadows: true,
receive_shadows: true,
),
}),
3: (components: {
"bevy_ecs::name::Name": "Subtractive Marker",
"bevy_transform::components::transform::Transform": (
translation: (2.5, 2.0, 0.0),
rotation: (0.0, 0.258819, 0.0, 0.9659258),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-brush-subtractive-marker"),
"shared::components::ActorKind": Brush,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (2),
"shared::components::LevelObject": (),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.72, g: 0.14, b: 0.16, a: 1.0),
metallic: 0.05,
roughness: 0.4,
emissive_color: (r: 1.0, g: 0.25, b: 0.2, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: None,
parameters: [],
textures: [],
),
"shared::components::BrushDesc": (
kind: SubtractiveMarker,
faces: [
(
id: ("face:+x"),
plane: (normal: (1.0, 0.0, 0.0), distance: 1.0),
vertices: [(1.0, -1.0, -1.0), (1.0, 1.0, -1.0), (1.0, 1.0, 1.0), (1.0, -1.0, 1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-x"),
plane: (normal: (-1.0, 0.0, 0.0), distance: 1.0),
vertices: [(-1.0, -1.0, 1.0), (-1.0, 1.0, 1.0), (-1.0, 1.0, -1.0), (-1.0, -1.0, -1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+y"),
plane: (normal: (0.0, 1.0, 0.0), distance: 1.0),
vertices: [(-1.0, 1.0, -1.0), (-1.0, 1.0, 1.0), (1.0, 1.0, 1.0), (1.0, 1.0, -1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-y"),
plane: (normal: (0.0, -1.0, 0.0), distance: 1.0),
vertices: [(-1.0, -1.0, 1.0), (-1.0, -1.0, -1.0), (1.0, -1.0, -1.0), (1.0, -1.0, 1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:+z"),
plane: (normal: (0.0, 0.0, 1.0), distance: 1.0),
vertices: [(1.0, -1.0, 1.0), (1.0, 1.0, 1.0), (-1.0, 1.0, 1.0), (-1.0, -1.0, 1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
(
id: ("face:-z"),
plane: (normal: (0.0, 0.0, -1.0), distance: 1.0),
vertices: [(-1.0, -1.0, -1.0), (-1.0, 1.0, -1.0), (1.0, 1.0, -1.0), (1.0, -1.0, -1.0)],
material: None,
texture: None,
uv_offset: (0.0, 0.0),
uv_scale: (1.0, 1.0),
uv_rotation: 0.0,
smoothing_group: 0,
),
],
cast_shadows: true,
receive_shadows: true,
),
}),
4: (components: {
"bevy_ecs::name::Name": "Brush Lab Sun",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 8.0, 4.0),
rotation: (-0.3826834, 0.0, 0.0, 0.9238795),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-brush-sun"),
"shared::components::ActorKind": Light,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (3),
"shared::components::LevelObject": (),
"shared::components::LightDesc": (
kind: Directional,
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
intensity: 100000.0,
range: 0.0,
shadows: true,
inner_angle_deg: 25.0,
outer_angle_deg: 35.0,
),
}),
})
+189
View File
@@ -0,0 +1,189 @@
(schema_version: 4, resources: {}, entities: {
1: (components: {
"bevy_ecs::name::Name": "Material Lab Floor",
"bevy_transform::components::transform::Transform": (
translation: (0.0, -0.2, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-floor"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (0),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (14.0, 0.4, 8.0)),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.55, g: 0.54, b: 0.52, a: 1.0),
metallic: 0.0,
roughness: 0.85,
emissive_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/concrete.ron"),
parameters: [],
textures: [],
),
}),
2: (components: {
"bevy_ecs::name::Name": "Concrete Reference",
"bevy_transform::components::transform::Transform": (
translation: (-4.0, 1.0, 0.0),
rotation: (0.0, 0.2164396, 0.0, 0.976296),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-concrete"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (1),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (2.0, 2.0, 2.0)),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.55, g: 0.54, b: 0.52, a: 1.0),
metallic: 0.0,
roughness: 0.85,
emissive_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
emissive_intensity: 0.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/concrete.ron"),
parameters: [],
textures: [],
),
}),
3: (components: {
"bevy_ecs::name::Name": "Custom Surface Reference",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 1.2, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-custom-surface"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (2),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Sphere, size: (2.4, 2.4, 2.4)),
"shared::components::MaterialDesc": (
shader: (
kind: Custom,
schema_path: Some("assets/shaders/surface_tint.shader.ron"),
shader_path: Some("assets/shaders/surface_tint.wgsl"),
),
base_color: (r: 0.12, g: 0.42, b: 0.95, a: 1.0),
metallic: 0.15,
roughness: 0.28,
emissive_color: (r: 0.02, g: 0.08, b: 0.25, a: 1.0),
emissive_intensity: 3.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/surface_tint.ron"),
parameters: [
(name: "tint", value: Color((r: 0.12, g: 0.42, b: 0.95, a: 1.0))),
(name: "roughness", value: Float(0.28)),
(name: "metallic", value: Float(0.15)),
(name: "emissive", value: Color((r: 0.02, g: 0.08, b: 0.25, a: 1.0))),
(name: "emissive_intensity", value: Float(3.0)),
],
textures: [],
),
}),
4: (components: {
"bevy_ecs::name::Name": "Material Instance Reference",
"bevy_transform::components::transform::Transform": (
translation: (4.0, 1.0, 0.0),
rotation: (0.0, -0.1305262, 0.0, 0.9914449),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-instance"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (3),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (2.6, 2.0, 2.6)),
"shared::components::MaterialDesc": (
shader: (
kind: Custom,
schema_path: Some("assets/shaders/surface_tint.shader.ron"),
shader_path: Some("assets/shaders/surface_tint.wgsl"),
),
base_color: (r: 0.12, g: 0.42, b: 0.95, a: 1.0),
metallic: 0.15,
roughness: 0.28,
emissive_color: (r: 0.02, g: 0.08, b: 0.25, a: 1.0),
emissive_intensity: 3.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/surface_tint_instance.ron"),
parameters: [
(name: "tint", value: Color((r: 0.12, g: 0.42, b: 0.95, a: 1.0))),
(name: "roughness", value: Float(0.28)),
(name: "metallic", value: Float(0.15)),
(name: "emissive", value: Color((r: 0.02, g: 0.08, b: 0.25, a: 1.0))),
(name: "emissive_intensity", value: Float(3.0)),
],
textures: [],
),
}),
5: (components: {
"bevy_ecs::name::Name": "Emissive Reference Panel",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 2.3, -3.6),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-emissive-panel"),
"shared::components::ActorKind": StaticMesh,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (4),
"shared::components::LevelObject": (),
"shared::components::Primitive": (shape: Box, size: (9.0, 3.0, 0.25)),
"shared::components::MaterialDesc": (
shader: (kind: StandardLit, schema_path: None, shader_path: None),
base_color: (r: 0.15, g: 0.22, b: 0.28, a: 1.0),
metallic: 0.0,
roughness: 0.35,
emissive_color: (r: 0.55, g: 0.85, b: 1.0, a: 1.0),
emissive_intensity: 2500.0,
base_color_texture: None,
emissive_texture: None,
normal_map_texture: None,
metallic_roughness_texture: None,
material_asset_path: Some("assets/materials/emissive_panel.ron"),
parameters: [],
textures: [],
),
}),
6: (components: {
"bevy_ecs::name::Name": "Material Lab Sun",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 8.0, 4.0),
rotation: (-0.3826834, 0.0, 0.0, 0.9238795),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("sample-material-sun"),
"shared::components::ActorKind": Light,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (5),
"shared::components::LevelObject": (),
"shared::components::LightDesc": (
kind: Directional,
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
intensity: 100000.0,
range: 0.0,
shadows: true,
inner_angle_deg: 25.0,
outer_angle_deg: 35.0,
),
}),
})
@@ -1,5 +1,5 @@
( (
schema_version: 3, schema_version: 4,
asset_id: "113f74df-e39c-41d4-9b5b-e48efe541f7f", asset_id: "113f74df-e39c-41d4-9b5b-e48efe541f7f",
label: "RobotExpressive", label: "RobotExpressive",
source: ( source: (
@@ -7,7 +7,7 @@
format: "glb", format: "glb",
fingerprint: ( fingerprint: (
byte_len: 463988, byte_len: 463988,
modified_unix_secs: 1783799272, content_hash: "5869cb813e6a6093eda7af2824a9c13a582750e0443e88ce7c991a1f83415521",
), ),
dependencies: [], dependencies: [],
), ),
@@ -1,5 +1,5 @@
( (
schema_version: 3, schema_version: 4,
asset_id: "3f63f359-45eb-4cb2-8970-71921cbd7bd0", asset_id: "3f63f359-45eb-4cb2-8970-71921cbd7bd0",
label: "robot_expressive", label: "robot_expressive",
source: ( source: (
@@ -7,7 +7,7 @@
format: "glb", format: "glb",
fingerprint: ( fingerprint: (
byte_len: 463988, byte_len: 463988,
modified_unix_secs: 1783750957, content_hash: "5869cb813e6a6093eda7af2824a9c13a582750e0443e88ce7c991a1f83415521",
), ),
dependencies: [], dependencies: [],
), ),
@@ -1,5 +1,5 @@
( (
schema_version: 3, schema_version: 4,
asset_id: "b98ef565-3500-49e7-9935-f685fa9b2594", asset_id: "b98ef565-3500-49e7-9935-f685fa9b2594",
label: "painted_wooden_chair_02_2k", label: "painted_wooden_chair_02_2k",
source: ( source: (
@@ -7,9 +7,13 @@
format: "fbx", format: "fbx",
fingerprint: ( fingerprint: (
byte_len: 59964, byte_len: 59964,
modified_unix_secs: 1780713434, content_hash: "b12973a62dcb44589e380ea833eade726ae98a86c81084c842ee3801866d6a46",
), ),
dependencies: [], dependencies: [
"assets/models/textures/painted_wooden_chair_02_diff_2k.jpg",
"assets/models/textures/painted_wooden_chair_02_nor_gl_2k.exr",
"assets/models/textures/painted_wooden_chair_02_rough_2k.exr",
],
), ),
import: ( import: (
scale: 1.0, scale: 1.0,
@@ -17,7 +21,7 @@
lod0_only: true, lod0_only: true,
placement_mode: StaticAsset, placement_mode: StaticAsset,
hierarchy_mode: SingleActor, hierarchy_mode: SingleActor,
material_policy: SourceMaterials, material_policy: AuthoringOverride,
), ),
metadata: ( metadata: (
mesh_count: 1, mesh_count: 1,
@@ -48,4 +52,4 @@
), ),
], ],
warnings: [], warnings: [],
) )
+65
View File
@@ -0,0 +1,65 @@
(
schema_version: 1,
samples: [
(
id: "brush-blockout",
label: "Brush Blockout",
area: Brush,
scene: "assets/levels/samples/brush_blockout.scn.ron",
summary: "Convex additive brushes, a subtractive marker, and a shared face material for brush editing and CSG regression checks.",
checks: [
"valid authored BrushDesc geometry",
"shared brush-face material resolution",
"object, face, clip, and CSG selection targets",
],
),
(
id: "material-lab",
label: "Material Lab",
area: Material,
scene: "assets/levels/samples/material_lab.scn.ron",
summary: "A compact look-development stage for shared materials, material instances, custom surfaces, and emissive output.",
checks: [
"Material and Material Instance dependency resolution",
"standard, custom, and emissive surface hydration",
"primitive material assignment and targeted drops",
],
),
(
id: "terrain-authoring",
label: "Terrain Authoring",
area: Terrain,
scene: "assets/levels/terrain_authoring_showcase.scn.ron",
summary: "A deterministic height grid with shared material layers, normalized paint weights, chunks, and collision.",
checks: [
"TerrainDesc schema and normalized layer weights",
"shared terrain material dependency resolution",
"sculpt, paint, chunk, and collider hydration",
],
),
(
id: "physics-placement",
label: "Physics Placement",
area: PhysicsPlacement,
scene: "assets/levels/physics_placement_showcase.scn.ron",
summary: "Three visually distinct collider cases above a static floor for transactional multi-object settling.",
checks: [
"cuboid, sphere, and capsule collider diversity",
"multi-selection settle and grouped history",
"static floor collision and cancel restoration",
],
),
(
id: "rendering-lab",
label: "Rendering Lab",
area: Rendering,
scene: "assets/levels/rendering_showcase.scn.ron",
summary: "Visible comparison anchors for fog, exposure, rendering profiles, fullscreen effects, and emissive lighting.",
checks: [
"stable post-process volume ownership",
"rendering profile and fullscreen effect dependency resolution",
"visible fog, exposure, vignette, and emissive comparison anchors",
],
),
],
)
+8
View File
@@ -6,6 +6,7 @@
use std::collections::HashMap; use std::collections::HashMap;
use std::fs; use std::fs;
use bevy::material::OpaqueRendererMethod;
use bevy::mesh::MeshVertexBufferLayoutRef; use bevy::mesh::MeshVertexBufferLayoutRef;
use bevy::pbr::{ use bevy::pbr::{
ExtendedMaterial, MaterialExtension, MaterialExtensionKey, MaterialExtensionPipeline, ExtendedMaterial, MaterialExtension, MaterialExtensionKey, MaterialExtensionPipeline,
@@ -393,6 +394,9 @@ fn build_terrain_layer_material(
base: StandardMaterial { base: StandardMaterial {
base_color: Color::WHITE, base_color: Color::WHITE,
perceptual_roughness: 1.0, perceptual_roughness: 1.0,
// Terrain is intentionally absent from the Solari acceleration structure until its
// ray-tracing evaluator exists, so keep the layer blend in the raster forward pass.
opaque_render_method: OpaqueRendererMethod::Forward,
..default() ..default()
}, },
extension, extension,
@@ -1079,6 +1083,10 @@ mod tests {
assert_eq!(material.extension.uniform.uv_scales.y, 10.0); assert_eq!(material.extension.uniform.uv_scales.y, 10.0);
assert_eq!(material.extension.uniform.properties[0].w, 1.0); assert_eq!(material.extension.uniform.properties[0].w, 1.0);
assert_eq!(material.extension.uniform.properties[1].w, 1.0); assert_eq!(material.extension.uniform.properties[1].w, 1.0);
assert_eq!(
material.base.opaque_render_method,
OpaqueRendererMethod::Forward
);
assert_ne!( assert_ne!(
material.extension.uniform.base_colors[0], material.extension.uniform.base_colors[0],
material.extension.uniform.base_colors[1] material.extension.uniform.base_colors[1]
+32 -24
View File
@@ -3,7 +3,6 @@
use std::collections::BTreeSet; use std::collections::BTreeSet;
use std::fs; use std::fs;
use std::path::Path; use std::path::Path;
use std::time::UNIX_EPOCH;
use serde::Deserialize; use serde::Deserialize;
use shared::{ use shared::{
@@ -14,6 +13,7 @@ use shared::{
}; };
use crate::asset_db::AssetRecord; use crate::asset_db::AssetRecord;
use crate::assets::fingerprint::write_pretty_ron_if_changed;
pub fn animation_manifest_path(asset_id: &str) -> String { pub fn animation_manifest_path(asset_id: &str) -> String {
format!("{ANIMATION_ARTIFACT_DIR}/{asset_id}.animation.ron") format!("{ANIMATION_ARTIFACT_DIR}/{asset_id}.animation.ron")
@@ -32,15 +32,9 @@ pub fn refresh_animation_artifact(record: &mut AssetRecord) -> Result<AnimationM
record.dependencies.sort(); record.dependencies.sort();
record.dependencies.dedup(); record.dependencies.dedup();
let text = ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()) if write_pretty_ron_if_changed(&path, &manifest)
.map_err(|error| format!("could not serialize animation manifest: {error}"))?; .map_err(|error| format!("could not publish animation manifest {path}: {error}"))?
if let Some(parent) = Path::new(&path).parent() { {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
if fs::read_to_string(&path).ok().as_deref() != Some(text.as_str()) {
fs::write(&path, text)
.map_err(|error| format!("could not write animation manifest {path}: {error}"))?;
bevy::log::info!( bevy::log::info!(
"Animation manifest refreshed: source={} artifact={} skeletons={} clips={} runtime_supported={}", "Animation manifest refreshed: source={} artifact={} skeletons={} clips={} runtime_supported={}",
record.path, record.path,
@@ -63,7 +57,7 @@ pub fn load_animation_manifest(path: &str) -> Result<AnimationManifest, String>
pub fn build_animation_manifest(record: &AssetRecord) -> Result<AnimationManifest, String> { pub fn build_animation_manifest(record: &AssetRecord) -> Result<AnimationManifest, String> {
let bytes = fs::read(&record.path) let bytes = fs::read(&record.path)
.map_err(|error| format!("could not read {}: {error}", record.path))?; .map_err(|error| format!("could not read {}: {error}", record.path))?;
let fingerprint = source_fingerprint(&record.path, &bytes)?; let fingerprint = source_fingerprint(&bytes);
let format = source_format(&record.path)?; let format = source_format(&record.path)?;
match format.as_str() { match format.as_str() {
"gltf" | "glb" => build_gltf_manifest(record, format, fingerprint, &bytes), "gltf" | "glb" => build_gltf_manifest(record, format, fingerprint, &bytes),
@@ -582,19 +576,8 @@ fn fbx_matrix_bytes(matrix: &ufbx::Matrix) -> Vec<u8> {
.collect() .collect()
} }
fn source_fingerprint(path: &str, bytes: &[u8]) -> Result<AnimationSourceFingerprint, String> { fn source_fingerprint(bytes: &[u8]) -> AnimationSourceFingerprint {
let metadata = fs::metadata(path).map_err(|error| format!("could not stat {path}: {error}"))?; AnimationSourceFingerprint::from_bytes(bytes)
let modified_unix_secs = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or_default();
Ok(AnimationSourceFingerprint {
byte_len: metadata.len(),
modified_unix_secs,
content_hash: blake3::hash(bytes).to_hex().to_string(),
})
} }
fn source_format(path: &str) -> Result<String, String> { fn source_format(path: &str) -> Result<String, String> {
@@ -626,6 +609,7 @@ mod tests {
path: path.to_string_lossy().replace('\\', "/"), path: path.to_string_lossy().replace('\\', "/"),
label: "Animated Hero".into(), label: "Animated Hero".into(),
kind_tag: "Model".into(), kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings::default(), import_settings: ImportSettings::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
} }
@@ -754,6 +738,30 @@ mod tests {
fs::remove_dir_all(root).unwrap(); fs::remove_dir_all(root).unwrap();
} }
#[test]
fn legacy_mtime_metadata_does_not_rewrite_equivalent_animation_manifest() {
let root =
std::env::temp_dir().join(format!("blacksite-animation-legacy-{}", Uuid::new_v4()));
let path = write_animated_gltf(&root);
let manifest = build_animation_manifest(&fixture_record(&path)).unwrap();
let canonical =
ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()).unwrap();
let marker = format!("byte_len: {},", manifest.source.fingerprint.byte_len);
let legacy = canonical.replacen(
&marker,
&format!("{marker}\n modified_unix_secs: 123456,"),
1,
);
assert_ne!(legacy, canonical);
let artifact = root.join("legacy.animation.ron");
fs::write(&artifact, &legacy).unwrap();
assert!(!write_pretty_ron_if_changed(&artifact, &manifest).unwrap());
assert_eq!(fs::read_to_string(&artifact).unwrap(), legacy);
fs::remove_dir_all(root).unwrap();
}
#[test] #[test]
fn explicit_default_clip_is_stable_and_stale_ids_are_diagnostic() { fn explicit_default_clip_is_stable_and_stale_ids_are_diagnostic() {
let root = let root =
+177 -34
View File
@@ -2,9 +2,12 @@
use bevy::prelude::*; use bevy::prelude::*;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use shared::AssetSourceFingerprint;
use std::collections::{HashMap, HashSet}; use std::collections::{HashMap, HashSet};
use uuid::Uuid; use uuid::Uuid;
use crate::assets::fingerprint::{fingerprint_file, write_pretty_ron_if_changed};
/// Stable asset identity for dependency tracking and prefab references. /// Stable asset identity for dependency tracking and prefab references.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct AssetId(pub Uuid); pub struct AssetId(pub Uuid);
@@ -93,6 +96,8 @@ pub struct AssetRecord {
pub path: String, pub path: String,
pub label: String, pub label: String,
pub kind_tag: String, pub kind_tag: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source_fingerprint: Option<AssetSourceFingerprint>,
#[serde(default)] #[serde(default)]
pub import_settings: ImportSettings, pub import_settings: ImportSettings,
#[serde(default)] #[serde(default)]
@@ -122,9 +127,10 @@ fn sync_registry_from_browser(
return; return;
} }
let mut existing: HashMap<String, AssetRecord> = registry let previous_records = std::mem::take(&mut registry.records);
.records let mut existing: HashMap<String, AssetRecord> = previous_records
.drain(..) .iter()
.cloned()
.map(|record| (record.path.clone(), record)) .map(|record| (record.path.clone(), record))
.collect(); .collect();
let current_paths = assets let current_paths = assets
@@ -146,12 +152,30 @@ fn sync_registry_from_browser(
seen_paths.insert(path.clone(), ()); seen_paths.insert(path.clone(), ());
let kind_tag = format!("{:?}", asset.kind); let kind_tag = format!("{:?}", asset.kind);
let source_fingerprint = if imported_source_kind(&kind_tag) {
match fingerprint_file(&path) {
Ok(fingerprint) => Some(fingerprint),
Err(error) => {
warn!("Imported source fingerprint failed for {path}: {error}");
None
}
}
} else {
None
};
let mut record = if let Some(mut prior) = existing.remove(&path).or_else(|| { let mut record = if let Some(mut prior) = existing.remove(&path).or_else(|| {
take_uniquely_moved_model_record(&mut existing, &current_paths, &path, &kind_tag) source_fingerprint.as_ref().and_then(|fingerprint| {
take_uniquely_moved_import_record(
&mut existing,
&current_paths,
&kind_tag,
fingerprint,
)
})
}) { }) {
if prior.path != path { if prior.path != path {
info!( info!(
"Asset registry preserved model identity {} across move {} -> {}", "Asset registry preserved imported source identity {} across move {} -> {}",
prior.id.as_string(), prior.id.as_string(),
prior.path, prior.path,
path path
@@ -159,18 +183,26 @@ fn sync_registry_from_browser(
prior.path = path.clone(); prior.path = path.clone();
} }
prior.label = asset.label.clone(); prior.label = asset.label.clone();
prior.kind_tag = kind_tag; prior.kind_tag = kind_tag.clone();
prior prior
} else { } else {
AssetRecord { AssetRecord {
id: AssetId::new(), id: AssetId::new(),
path: path.clone(), path: path.clone(),
label: asset.label.clone(), label: asset.label.clone(),
kind_tag, kind_tag: kind_tag.clone(),
source_fingerprint: None,
import_settings: ImportSettings::default(), import_settings: ImportSettings::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
} }
}; };
if imported_source_kind(&kind_tag) {
if let Some(source_fingerprint) = source_fingerprint {
record.source_fingerprint = Some(source_fingerprint);
}
} else {
record.source_fingerprint = None;
}
if record.kind_tag == "Model" { if record.kind_tag == "Model" {
if let Err(error) = super::refresh_model_artifacts(&mut record) { if let Err(error) = super::refresh_model_artifacts(&mut record) {
warn!( warn!(
@@ -183,7 +215,8 @@ fn sync_registry_from_browser(
next_records.push(record); next_records.push(record);
} }
let changed = registry.records != next_records; sort_registry_records(&mut next_records);
let changed = previous_records != next_records;
registry.records = next_records; registry.records = next_records;
if changed { if changed {
registry.index_dirty = true; registry.index_dirty = true;
@@ -198,26 +231,32 @@ fn sync_registry_from_browser(
} }
} }
fn take_uniquely_moved_model_record( fn imported_source_kind(kind_tag: &str) -> bool {
matches!(kind_tag, "Model" | "Texture" | "AudioClip")
}
fn sort_registry_records(records: &mut [AssetRecord]) {
records.sort_by(|left, right| left.path.cmp(&right.path));
}
fn take_uniquely_moved_import_record(
existing: &mut HashMap<String, AssetRecord>, existing: &mut HashMap<String, AssetRecord>,
current_paths: &HashSet<String>, current_paths: &HashSet<String>,
new_path: &str,
kind_tag: &str, kind_tag: &str,
fingerprint: &AssetSourceFingerprint,
) -> Option<AssetRecord> { ) -> Option<AssetRecord> {
if kind_tag != "Model" { if !imported_source_kind(kind_tag) {
return None; return None;
} }
let bytes = std::fs::read(new_path).ok()?;
let content_hash = blake3::hash(&bytes).to_hex().to_string();
let candidates = existing let candidates = existing
.iter() .iter()
.filter_map(|(old_path, record)| { .filter_map(|(old_path, record)| {
if current_paths.contains(old_path) || record.kind_tag != "Model" { if current_paths.contains(old_path) || record.kind_tag != kind_tag {
return None; return None;
} }
let manifest_path = record.import_settings.animation_manifest_path.as_deref()?; recorded_source_fingerprint(record)
let manifest = super::animation::load_animation_manifest(manifest_path).ok()?; .is_some_and(|prior| prior == *fingerprint)
(manifest.source.fingerprint.content_hash == content_hash).then(|| old_path.clone()) .then(|| old_path.clone())
}) })
.collect::<Vec<_>>(); .collect::<Vec<_>>();
if candidates.len() != 1 { if candidates.len() != 1 {
@@ -226,6 +265,15 @@ fn take_uniquely_moved_model_record(
existing.remove(&candidates[0]) existing.remove(&candidates[0])
} }
fn recorded_source_fingerprint(record: &AssetRecord) -> Option<AssetSourceFingerprint> {
record.source_fingerprint.clone().or_else(|| {
let manifest_path = record.import_settings.animation_manifest_path.as_deref()?;
super::animation::load_animation_manifest(manifest_path)
.ok()
.map(|manifest| manifest.source.fingerprint)
})
}
pub fn find_asset_by_path(registry: &AssetRegistry, path: &str) -> Option<AssetRecord> { pub fn find_asset_by_path(registry: &AssetRegistry, path: &str) -> Option<AssetRecord> {
registry registry
.records .records
@@ -262,11 +310,16 @@ pub fn ensure_asset_record(
if let Some(record) = find_asset_by_path(registry, &path) { if let Some(record) = find_asset_by_path(registry, &path) {
return Ok(record); return Ok(record);
} }
let kind_tag = kind_tag.into();
let source_fingerprint = imported_source_kind(&kind_tag)
.then(|| fingerprint_file(&path).ok())
.flatten();
let record = AssetRecord { let record = AssetRecord {
id: AssetId::new(), id: AssetId::new(),
path, path,
label: label.into(), label: label.into(),
kind_tag: kind_tag.into(), kind_tag,
source_fingerprint,
import_settings: ImportSettings::default(), import_settings: ImportSettings::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
}; };
@@ -292,6 +345,9 @@ pub fn update_import_settings(
else { else {
return false; return false;
}; };
if record.import_settings == settings {
return false;
}
record.import_settings = settings; record.import_settings = settings;
registry.index_dirty = true; registry.index_dirty = true;
true true
@@ -302,13 +358,7 @@ pub fn registry_index_path() -> &'static str {
} }
pub fn save_registry(registry: &AssetRegistry) -> Result<(), String> { pub fn save_registry(registry: &AssetRegistry) -> Result<(), String> {
let path = registry_index_path(); write_pretty_ron_if_changed(registry_index_path(), &registry.records).map(|_| ())
if let Some(parent) = std::path::Path::new(path).parent() {
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
}
let text = ron::ser::to_string_pretty(&registry.records, ron::ser::PrettyConfig::default())
.map_err(|e| e.to_string())?;
std::fs::write(path, text).map_err(|e| e.to_string())
} }
pub fn load_registry() -> AssetRegistry { pub fn load_registry() -> AssetRegistry {
@@ -333,6 +383,101 @@ mod tests {
ANIMATION_MANIFEST_SCHEMA_VERSION, ANIMATION_MANIFEST_SCHEMA_VERSION,
}; };
#[test]
fn imported_source_policy_covers_model_texture_and_audio_only() {
for kind in ["Model", "Texture", "AudioClip"] {
assert!(imported_source_kind(kind), "missing imported kind {kind}");
}
for kind in ["Material", "Level", "Prefab", "PostProcessEffect"] {
assert!(
!imported_source_kind(kind),
"authored kind {kind} was hashed"
);
}
}
#[test]
fn registry_publication_order_is_stable_across_discovery_orders() {
let records = [
("assets/textures/z.png", "Texture"),
("assets/audio/a.ogg", "AudioClip"),
("assets/models/m.glb", "Model"),
]
.into_iter()
.map(|(path, kind_tag)| AssetRecord {
id: AssetId::new(),
path: path.into(),
label: path.into(),
kind_tag: kind_tag.into(),
source_fingerprint: None,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
})
.collect::<Vec<_>>();
let mut forward = records.clone();
let mut reverse = records.into_iter().rev().collect::<Vec<_>>();
sort_registry_records(&mut forward);
sort_registry_records(&mut reverse);
assert_eq!(forward, reverse);
assert_eq!(
forward
.iter()
.map(|record| record.path.as_str())
.collect::<Vec<_>>(),
[
"assets/audio/a.ogg",
"assets/models/m.glb",
"assets/textures/z.png",
]
);
}
#[test]
fn legacy_registry_record_loads_without_forcing_a_new_identity() {
let source = r#"(
id: ("00000000-0000-0000-0000-000000000000"),
path: "assets/textures/legacy.png",
label: "Legacy",
kind_tag: "Texture",
)"#;
let record: AssetRecord = ron::from_str(source).unwrap();
assert_eq!(record.id, AssetId(Uuid::nil()));
assert!(record.source_fingerprint.is_none());
assert_eq!(record.import_settings, ImportSettings::default());
}
#[test]
fn content_match_preserves_every_imported_source_kind_across_move() {
let fingerprint = AssetSourceFingerprint::from_bytes(b"stable imported bytes");
for kind in ["Model", "Texture", "AudioClip"] {
let record = AssetRecord {
id: AssetId::new(),
path: format!("assets/old/{kind}"),
label: kind.into(),
kind_tag: kind.into(),
source_fingerprint: Some(fingerprint.clone()),
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
};
let expected_id = record.id.clone();
let mut existing = HashMap::from([(record.path.clone(), record)]);
let moved = take_uniquely_moved_import_record(
&mut existing,
&HashSet::new(),
kind,
&fingerprint,
)
.expect("unique content identity should preserve the record");
assert_eq!(moved.id, expected_id);
assert!(existing.is_empty());
}
}
fn moved_model_fixture(bytes: &[u8]) -> (std::path::PathBuf, std::path::PathBuf, AssetRecord) { fn moved_model_fixture(bytes: &[u8]) -> (std::path::PathBuf, std::path::PathBuf, AssetRecord) {
let key = Uuid::new_v4(); let key = Uuid::new_v4();
let source_path = std::env::temp_dir().join(format!("blacksite-moved-model-{key}.glb")); let source_path = std::env::temp_dir().join(format!("blacksite-moved-model-{key}.glb"));
@@ -351,7 +496,6 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: AnimationSourceFingerprint { fingerprint: AnimationSourceFingerprint {
byte_len: bytes.len() as u64, byte_len: bytes.len() as u64,
modified_unix_secs: 0,
content_hash: blake3::hash(bytes).to_hex().to_string(), content_hash: blake3::hash(bytes).to_hex().to_string(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
@@ -371,6 +515,7 @@ mod tests {
path: old_path, path: old_path,
label: "Moved Model".into(), label: "Moved Model".into(),
kind_tag: "Model".into(), kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings { import_settings: ImportSettings {
animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()), animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()),
..Default::default() ..Default::default()
@@ -385,12 +530,13 @@ mod tests {
let (source_path, manifest_path, record) = moved_model_fixture(b"stable model bytes"); let (source_path, manifest_path, record) = moved_model_fixture(b"stable model bytes");
let expected_id = record.id.clone(); let expected_id = record.id.clone();
let mut existing = HashMap::from([(record.path.clone(), record)]); let mut existing = HashMap::from([(record.path.clone(), record)]);
let fingerprint = fingerprint_file(&source_path).unwrap();
let moved = take_uniquely_moved_model_record( let moved = take_uniquely_moved_import_record(
&mut existing, &mut existing,
&HashSet::new(), &HashSet::new(),
&source_path.to_string_lossy(),
"Model", "Model",
&fingerprint,
) )
.expect("unique moved model should retain its registry record"); .expect("unique moved model should retain its registry record");
@@ -406,13 +552,10 @@ mod tests {
let old_path = record.path.clone(); let old_path = record.path.clone();
let mut existing = HashMap::from([(old_path.clone(), record)]); let mut existing = HashMap::from([(old_path.clone(), record)]);
let current_paths = HashSet::from([old_path]); let current_paths = HashSet::from([old_path]);
let fingerprint = fingerprint_file(&source_path).unwrap();
let moved = take_uniquely_moved_model_record( let moved =
&mut existing, take_uniquely_moved_import_record(&mut existing, &current_paths, "Model", &fingerprint);
&current_paths,
&source_path.to_string_lossy(),
"Model",
);
assert!(moved.is_none()); assert!(moved.is_none());
assert_eq!(existing.len(), 1); assert_eq!(existing.len(), 1);
+3 -2
View File
@@ -1455,7 +1455,7 @@ pub fn import_external_assets(paths: &[PathBuf]) -> Result<usize, String> {
}; };
let dest_dir = import_dir_for_extension(extension); let dest_dir = import_dir_for_extension(extension);
if extension.eq_ignore_ascii_case("fbx") { if extension.eq_ignore_ascii_case("fbx") {
super::import::copy_fbx_with_sidecar(source, Path::new(dest_dir))?; super::import::copy_fbx_bundle(source, Path::new(dest_dir))?;
copied += 1; copied += 1;
continue; continue;
} }
@@ -1548,6 +1548,7 @@ mod tests {
path: asset.path.clone().unwrap(), path: asset.path.clone().unwrap(),
label: asset.label.clone(), label: asset.label.clone(),
kind_tag: "AudioClip".into(), kind_tag: "AudioClip".into(),
source_fingerprint: None,
import_settings: Default::default(), import_settings: Default::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
}], }],
@@ -1630,7 +1631,6 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: shared::AnimationSourceFingerprint { fingerprint: shared::AnimationSourceFingerprint {
byte_len: 1, byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(), content_hash: "fixture".into(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
@@ -1663,6 +1663,7 @@ mod tests {
path: "assets/models/robot.glb".into(), path: "assets/models/robot.glb".into(),
label: "Robot".into(), label: "Robot".into(),
kind_tag: "Model".into(), kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: crate::asset_db::ImportSettings { import_settings: crate::asset_db::ImportSettings {
animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()), animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()),
default_animation_clip_id: Some(clip_id.clone()), default_animation_clip_id: Some(clip_id.clone()),
+114
View File
@@ -0,0 +1,114 @@
use std::fs;
use std::path::Path;
use serde::de::DeserializeOwned;
use serde::Serialize;
use shared::AssetSourceFingerprint;
pub(crate) fn fingerprint_file(path: impl AsRef<Path>) -> Result<AssetSourceFingerprint, String> {
let path = path.as_ref();
let bytes = fs::read(path)
.map_err(|error| format!("could not read imported source {}: {error}", path.display()))?;
Ok(AssetSourceFingerprint::from_bytes(&bytes))
}
/// Writes canonical pretty RON only when the parsed document changes semantically.
///
/// Equivalent existing bytes, including custom formatting and final-newline policy, stay intact.
pub(crate) fn write_pretty_ron_if_changed<T>(
path: impl AsRef<Path>,
value: &T,
) -> Result<bool, String>
where
T: DeserializeOwned + PartialEq + Serialize,
{
let path = path.as_ref();
if fs::read_to_string(path)
.ok()
.and_then(|text| ron::from_str::<T>(&text).ok())
.is_some_and(|existing| existing == *value)
{
return Ok(false);
}
let text = ron::ser::to_string_pretty(value, ron::ser::PrettyConfig::default())
.map_err(|error| format!("could not serialize RON: {error}"))?;
if fs::read(path).ok().as_deref() == Some(text.as_bytes()) {
return Ok(false);
}
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::write(path, text)
.map_err(|error| format!("could not write {}: {error}", path.display()))?;
Ok(true)
}
#[cfg(test)]
mod tests {
use super::*;
use serde::Deserialize;
use std::fs::{File, FileTimes};
use std::time::{Duration, SystemTime};
use uuid::Uuid;
#[derive(Debug, Deserialize, PartialEq, Serialize)]
struct Fixture {
count: u32,
label: String,
}
fn fixture_path(name: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!(
"blacksite-fingerprint-{name}-{}.ron",
Uuid::new_v4()
))
}
#[test]
fn metadata_only_drift_does_not_change_content_identity() {
let path = fixture_path("mtime");
fs::write(&path, b"stable source bytes").unwrap();
let before = fingerprint_file(&path).unwrap();
File::options()
.write(true)
.open(&path)
.unwrap()
.set_times(
FileTimes::new().set_modified(SystemTime::now() + Duration::from_secs(86_400)),
)
.unwrap();
assert_eq!(fingerprint_file(&path).unwrap(), before);
fs::remove_file(path).unwrap();
}
#[test]
fn same_size_byte_change_updates_content_identity() {
let path = fixture_path("same-size");
fs::write(&path, b"source-a").unwrap();
let before = fingerprint_file(&path).unwrap();
fs::write(&path, b"source-b").unwrap();
let after = fingerprint_file(&path).unwrap();
assert_eq!(before.byte_len, after.byte_len);
assert_ne!(before.content_hash, after.content_hash);
fs::remove_file(path).unwrap();
}
#[test]
fn equivalent_ron_preserves_exact_existing_bytes() {
let path = fixture_path("semantic");
let existing = b"( label: \"stable\", count: 7, )\n\n";
fs::write(&path, existing).unwrap();
let value = Fixture {
count: 7,
label: "stable".into(),
};
assert!(!write_pretty_ron_if_changed(&path, &value).unwrap());
assert_eq!(fs::read(&path).unwrap(), existing);
fs::remove_file(path).unwrap();
}
}
+535 -42
View File
@@ -1,71 +1,564 @@
//! External asset import helpers (FBX sidecar folders, etc.). //! External asset bundle inspection and transactional import.
use std::collections::BTreeMap;
use std::fs; use std::fs;
use std::path::{Path, PathBuf}; use std::path::{Component, Path, PathBuf};
/// Copies an FBX file and its sibling `.fbm` embedded-texture folder when present. use bevy_ufbx::texture::external_texture_paths;
pub fn copy_fbx_with_sidecar(source: &Path, dest_dir: &Path) -> Result<(), String> {
let Some(file_name) = source.file_name() else { #[derive(Debug, Clone, PartialEq, Eq)]
return Err("FBX import path has no file name".into()); pub(crate) struct FbxDependencyInspection {
}; pub relative_paths: Vec<String>,
fs::create_dir_all(dest_dir) pub resolved_paths: Vec<PathBuf>,
.map_err(|err| format!("could not create {}: {err}", dest_dir.display()))?; pub missing_paths: Vec<PathBuf>,
let dest = dest_dir.join(file_name); }
fs::copy(source, &dest).map_err(|err| {
/// Parses every external FBX texture reference without loading it through Bevy.
pub(crate) fn inspect_fbx_dependencies(source: &Path) -> Result<FbxDependencyInspection, String> {
let bytes = fs::read(source)
.map_err(|error| format!("could not read FBX {}: {error}", source.display()))?;
let filename_hint = source.to_string_lossy();
let scene = ufbx::load_memory(
&bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
filename: ufbx::StringOpt::Ref(&filename_hint),
..Default::default()
},
)
.map_err(|error| format!("could not parse FBX {}: {error:?}", source.display()))?;
let relative_paths = external_texture_paths(&scene).map_err(|errors| {
format!( format!(
"could not copy {} to {}: {err}", "unsafe FBX texture reference(s) in {}: {}",
source.display(), source.display(),
dest.display() errors
.into_iter()
.map(|error| error.to_string())
.collect::<Vec<_>>()
.join("; ")
) )
})?; })?;
let source_root = source.parent().unwrap_or_else(|| Path::new(""));
let canonical_root = fs::canonicalize(source_root).map_err(|error| {
format!(
"could not resolve FBX source directory {}: {error}",
source_root.display()
)
})?;
let mut resolved_paths = Vec::new();
let mut missing_paths = Vec::new();
for relative_path in &relative_paths {
let resolved = source_root.join(relative_path);
if !resolved.is_file() {
missing_paths.push(resolved.clone());
resolved_paths.push(resolved);
continue;
}
let canonical = fs::canonicalize(&resolved).map_err(|error| {
format!(
"could not resolve FBX dependency {}: {error}",
resolved.display()
)
})?;
if !canonical.starts_with(&canonical_root) {
return Err(format!(
"FBX dependency {} resolves outside source directory {}",
resolved.display(),
source_root.display()
));
}
resolved_paths.push(resolved);
}
missing_paths.sort();
Ok(FbxDependencyInspection {
relative_paths,
resolved_paths,
missing_paths,
})
}
if let Some(fbm_dir) = fbm_sidecar_dir(source) { /// Returns one stable browser-facing error for all missing FBX source textures.
if fbm_dir.is_dir() { pub(crate) fn validate_fbx_dependencies(source: &Path) -> Result<(), String> {
let dest_fbm = dest_dir.join(fbm_dir.file_name().unwrap_or_default()); let inspection = inspect_fbx_dependencies(source)?;
copy_dir_recursive(&fbm_dir, &dest_fbm)?; if inspection.missing_paths.is_empty() {
return Ok(());
}
Err(format!(
"missing {} FBX source texture(s): {}",
inspection.missing_paths.len(),
inspection
.missing_paths
.iter()
.map(|path| path.to_string_lossy().replace('\\', "/"))
.collect::<Vec<_>>()
.join(", ")
))
}
/// Copies an FBX and every referenced external texture as one staged filesystem transaction.
pub fn copy_fbx_bundle(source: &Path, dest_dir: &Path) -> Result<(), String> {
let inspection = inspect_fbx_dependencies(source)?;
if !inspection.missing_paths.is_empty() {
return Err(format!(
"FBX import is missing {} required texture(s): {}",
inspection.missing_paths.len(),
inspection
.missing_paths
.iter()
.map(|path| path.display().to_string())
.collect::<Vec<_>>()
.join(", ")
));
}
let file_name = source
.file_name()
.ok_or_else(|| "FBX import path has no file name".to_string())?;
let mut entries = BTreeMap::new();
entries.insert(PathBuf::from(file_name), source.to_path_buf());
for (relative, resolved) in inspection
.relative_paths
.iter()
.zip(inspection.resolved_paths.iter())
{
let relative = PathBuf::from(relative);
if let Some(existing) = entries.insert(relative.clone(), resolved.clone()) {
if existing != *resolved {
return Err(format!(
"FBX import maps multiple source files to {}",
relative.display()
));
}
} }
} }
Ok(()) copy_bundle_transactionally(&entries, dest_dir)
} }
fn fbm_sidecar_dir(source: &Path) -> Option<PathBuf> { fn copy_bundle_transactionally(
let stem = source.file_stem()?.to_str()?; entries: &BTreeMap<PathBuf, PathBuf>,
let parent = source.parent()?; dest_dir: &Path,
Some(parent.join(format!("{stem}.fbm"))) ) -> Result<(), String> {
} fs::create_dir_all(dest_dir)
.map_err(|error| format!("could not create {}: {error}", dest_dir.display()))?;
let canonical_dest_dir = fs::canonicalize(dest_dir).map_err(|error| {
format!(
"could not resolve FBX import destination {}: {error}",
dest_dir.display()
)
})?;
for relative in entries.keys() {
validate_bundle_relative_path(relative)?;
validate_existing_destination_parents(dest_dir, &canonical_dest_dir, relative)?;
let target = dest_dir.join(relative);
if target.is_dir() {
return Err(format!(
"FBX import target {} is an existing directory",
target.display()
));
}
}
fn copy_dir_recursive(source: &Path, dest: &Path) -> Result<(), String> { let stage_root = dest_dir.join(format!(".blacksite-import-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(dest) let staged_root = stage_root.join("new");
.map_err(|err| format!("could not create {}: {err}", dest.display()))?; let backup_root = stage_root.join("backup");
for entry in fs::read_dir(source).map_err(|err| err.to_string())? { let stage_result = (|| {
let entry = entry.map_err(|err| err.to_string())?; for (relative, source) in entries {
let src_path = entry.path(); let staged = staged_root.join(relative);
let dest_path = dest.join(entry.file_name()); if let Some(parent) = staged.parent() {
if src_path.is_dir() { fs::create_dir_all(parent).map_err(|error| {
copy_dir_recursive(&src_path, &dest_path)?; format!(
} else { "could not create import staging {}: {error}",
fs::copy(&src_path, &dest_path).map_err(|err| { parent.display()
)
})?;
}
fs::copy(source, &staged).map_err(|error| {
format!( format!(
"could not copy {} to {}: {err}", "could not stage FBX bundle file {} as {}: {error}",
src_path.display(), source.display(),
dest_path.display() relative.display()
) )
})?; })?;
} }
commit_staged_bundle(
entries,
dest_dir,
&canonical_dest_dir,
&staged_root,
&backup_root,
)
})();
let cleanup_result = fs::remove_dir_all(&stage_root);
match (stage_result, cleanup_result) {
(Err(error), _) => Err(error),
(Ok(()), Ok(())) => Ok(()),
(Ok(()), Err(error)) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
(Ok(()), Err(error)) => {
bevy::log::warn!(
"FBX bundle imported but staging cleanup failed for {}: {error}",
stage_root.display()
);
Ok(())
}
}
}
fn validate_bundle_relative_path(relative: &Path) -> Result<(), String> {
if relative.as_os_str().is_empty()
|| !relative
.components()
.all(|component| matches!(component, Component::Normal(_)))
{
return Err(format!(
"FBX import target path {} is not a safe relative path",
relative.display()
));
} }
Ok(()) Ok(())
} }
fn validate_existing_destination_parents(
dest_dir: &Path,
canonical_dest_dir: &Path,
relative: &Path,
) -> Result<(), String> {
let mut current = dest_dir.to_path_buf();
let Some(parent) = relative.parent() else {
return Ok(());
};
for component in parent.components() {
let Component::Normal(segment) = component else {
return Err(format!(
"FBX import target path {} is not a safe relative path",
relative.display()
));
};
current.push(segment);
let metadata = match fs::symlink_metadata(&current) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => break,
Err(error) => {
return Err(format!(
"could not inspect FBX import target {}: {error}",
current.display()
));
}
};
if metadata.file_type().is_symlink() {
return Err(format!(
"FBX import target parent {} is a symbolic link",
current.display()
));
}
if !metadata.is_dir() {
return Err(format!(
"FBX import target parent {} is not a directory",
current.display()
));
}
let canonical = fs::canonicalize(&current).map_err(|error| {
format!(
"could not resolve FBX import target parent {}: {error}",
current.display()
)
})?;
if !canonical.starts_with(canonical_dest_dir) {
return Err(format!(
"FBX import target parent {} resolves outside destination {}",
current.display(),
dest_dir.display()
));
}
}
Ok(())
}
fn commit_staged_bundle(
entries: &BTreeMap<PathBuf, PathBuf>,
dest_dir: &Path,
canonical_dest_dir: &Path,
staged_root: &Path,
backup_root: &Path,
) -> Result<(), String> {
let mut installed = Vec::new();
let mut backups = Vec::new();
for relative in entries.keys() {
let target = dest_dir.join(relative);
let staged = staged_root.join(relative);
if let Some(parent) = target.parent() {
if let Err(error) = fs::create_dir_all(parent) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not create import target {}: {error}",
parent.display()
),
);
}
let canonical_parent = match fs::canonicalize(parent) {
Ok(canonical_parent) => canonical_parent,
Err(error) => {
return rollback_bundle(
&installed,
&backups,
format!(
"could not resolve import target {}: {error}",
parent.display()
),
);
}
};
if !canonical_parent.starts_with(canonical_dest_dir) {
return rollback_bundle(
&installed,
&backups,
format!(
"FBX import target {} resolves outside destination {}",
parent.display(),
dest_dir.display()
),
);
}
}
if target.exists() {
let backup = backup_root.join(relative);
if let Some(parent) = backup.parent() {
if let Err(error) = fs::create_dir_all(parent) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not create import backup {}: {error}",
parent.display()
),
);
}
}
if let Err(error) = fs::rename(&target, &backup) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not back up import target {}: {error}",
target.display()
),
);
}
backups.push((backup, target.clone()));
}
if let Err(error) = fs::rename(&staged, &target) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not publish import target {}: {error}",
target.display()
),
);
}
installed.push(target);
}
Ok(())
}
fn rollback_bundle(
installed: &[PathBuf],
backups: &[(PathBuf, PathBuf)],
cause: String,
) -> Result<(), String> {
let mut rollback_errors = Vec::new();
for target in installed.iter().rev() {
if let Err(error) = fs::remove_file(target) {
if error.kind() != std::io::ErrorKind::NotFound {
rollback_errors.push(format!("remove {}: {error}", target.display()));
}
}
}
for (backup, target) in backups.iter().rev() {
if let Err(error) = fs::rename(backup, target) {
rollback_errors.push(format!(
"restore {} to {}: {error}",
backup.display(),
target.display()
));
}
}
if rollback_errors.is_empty() {
Err(cause)
} else {
Err(format!(
"{cause}; rollback also failed: {}",
rollback_errors.join("; ")
))
}
}
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::fbm_sidecar_dir; use super::*;
use std::path::Path;
fn temp_root(label: &str) -> PathBuf {
std::env::temp_dir().join(format!("blacksite-fbx-{label}-{}", uuid::Uuid::new_v4()))
}
fn committed_chair_bytes() -> Vec<u8> {
fs::read(
Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx"),
)
.unwrap()
}
fn replace_equal_length(bytes: &mut [u8], from: &[u8], to: &[u8]) -> usize {
assert_eq!(from.len(), to.len());
let mut count = 0;
let mut offset = 0;
while let Some(index) = bytes[offset..]
.windows(from.len())
.position(|window| window == from)
{
let start = offset + index;
bytes[start..start + from.len()].copy_from_slice(to);
offset = start + from.len();
count += 1;
}
count
}
fn write_textures(root: &Path, folder: &str) {
let folder = root.join(folder);
fs::create_dir_all(&folder).unwrap();
for name in [
"painted_wooden_chair_02_diff_2k.jpg",
"painted_wooden_chair_02_nor_gl_2k.exr",
"painted_wooden_chair_02_rough_2k.exr",
] {
fs::write(folder.join(name), name.as_bytes()).unwrap();
}
}
#[test] #[test]
fn fbm_sidecar_path() { fn committed_chair_reports_one_stable_missing_dependency_state() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx");
let error = validate_fbx_dependencies(&path).unwrap_err();
assert!(error.starts_with("missing 3 FBX source texture(s):"));
assert_eq!(error.matches("painted_wooden_chair_02_").count(), 3);
}
#[test]
fn sibling_texture_bundle_is_copied_with_relative_layout() {
let root = temp_root("sibling");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
write_textures(&source_root, "textures");
copy_fbx_bundle(&source, &destination).unwrap();
assert!(destination.join("chair.fbx").is_file());
assert!(destination
.join("textures/painted_wooden_chair_02_diff_2k.jpg")
.is_file());
assert!(!destination.read_dir().unwrap().any(|entry| entry
.unwrap()
.file_name()
.to_string_lossy()
.starts_with(".blacksite-import-")));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn fbm_texture_bundle_is_copied_with_relative_layout() {
let root = temp_root("fbm");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
let source = source_root.join("chair.fbx");
let mut bytes = committed_chair_bytes();
assert!(replace_equal_length(&mut bytes, b"textures/", b"test.fbm/") > 0);
fs::write(&source, bytes).unwrap();
write_textures(&source_root, "test.fbm");
copy_fbx_bundle(&source, &destination).unwrap();
assert!(destination
.join("test.fbm/painted_wooden_chair_02_diff_2k.jpg")
.is_file());
fs::remove_dir_all(root).unwrap();
}
#[test]
fn traversal_reference_is_rejected_before_destination_changes() {
let root = temp_root("traversal");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
let source = source_root.join("chair.fbx");
let mut bytes = committed_chair_bytes();
assert!(replace_equal_length(&mut bytes, b"textures/", b"../evil//") > 0);
fs::write(&source, bytes).unwrap();
fs::write(destination.join("chair.fbx"), b"original").unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("parent traversal"));
assert_eq!( assert_eq!(
fbm_sidecar_dir(Path::new("/tmp/Character.fbx")), fs::read(destination.join("chair.fbx")).unwrap(),
Some(Path::new("/tmp/Character.fbm").to_path_buf()) b"original"
); );
fs::remove_dir_all(root).unwrap();
}
#[test]
fn missing_bundle_preserves_existing_destination() {
let root = temp_root("missing");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
fs::write(destination.join("chair.fbx"), b"original").unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("missing 3 required texture(s)"));
assert_eq!(
fs::read(destination.join("chair.fbx")).unwrap(),
b"original"
);
fs::remove_dir_all(root).unwrap();
}
#[cfg(unix)]
#[test]
fn destination_symlink_escape_is_rejected_before_external_changes() {
use std::os::unix::fs::symlink;
let root = temp_root("destination-symlink");
let source_root = root.join("source");
let destination = root.join("destination");
let outside = root.join("outside");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
fs::create_dir_all(&outside).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
write_textures(&source_root, "textures");
symlink(&outside, destination.join("textures")).unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("symbolic link"));
assert!(!destination.join("chair.fbx").exists());
assert!(!outside.join("painted_wooden_chair_02_diff_2k.jpg").exists());
fs::remove_dir_all(root).unwrap();
} }
} }
+1
View File
@@ -3,6 +3,7 @@
pub mod animation; pub mod animation;
pub mod asset_db; pub mod asset_db;
mod catalog; mod catalog;
mod fingerprint;
mod import; mod import;
pub mod materials; pub mod materials;
pub mod operators; pub mod operators;
+3 -1
View File
@@ -228,7 +228,6 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: AnimationSourceFingerprint { fingerprint: AnimationSourceFingerprint {
byte_len: 1, byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(), content_hash: "fixture".into(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
@@ -265,6 +264,7 @@ mod tests {
path: model_path.clone(), path: model_path.clone(),
label: "Operator Fixture".into(), label: "Operator Fixture".into(),
kind_tag: "Model".into(), kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings { import_settings: ImportSettings {
animation_manifest_path: Some(path.to_string_lossy().into_owned()), animation_manifest_path: Some(path.to_string_lossy().into_owned()),
..Default::default() ..Default::default()
@@ -352,6 +352,7 @@ mod tests {
path: path.clone(), path: path.clone(),
label: "Impact".into(), label: "Impact".into(),
kind_tag: "AudioClip".into(), kind_tag: "AudioClip".into(),
source_fingerprint: None,
import_settings: Default::default(), import_settings: Default::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
}], }],
@@ -502,6 +503,7 @@ mod tests {
path: material_path.clone(), path: material_path.clone(),
label: "Concrete".into(), label: "Concrete".into(),
kind_tag: "Material".into(), kind_tag: "Material".into(),
source_fingerprint: None,
import_settings: Default::default(), import_settings: Default::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
}], }],
+109 -54
View File
@@ -2,12 +2,12 @@
use std::fs; use std::fs;
use std::path::Path; use std::path::Path;
use std::time::UNIX_EPOCH;
use bevy::gltf::GltfAssetLabel; use bevy::gltf::GltfAssetLabel;
use bevy::prelude::*; use bevy::prelude::*;
use bevy_ufbx::label::FbxAssetLabel; use bevy_ufbx::label::FbxAssetLabel;
use bevy_ufbx::mesh::group_faces_by_material; use bevy_ufbx::mesh::group_faces_by_material;
use bevy_ufbx::texture::external_texture_paths;
use bevy_ufbx::utils::convert_matrix; use bevy_ufbx::utils::convert_matrix;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@@ -15,11 +15,13 @@ use crate::asset_db::{
AssetRecord, ImportSettings, MaterialImportPolicy, ModelHierarchyMode, ModelPlacementMode, AssetRecord, ImportSettings, MaterialImportPolicy, ModelHierarchyMode, ModelPlacementMode,
}; };
use shared::{ use shared::{
ComponentInstanceId, EditorAssetRef, MaterialRef, RendererMaterialSet, RendererMaterialSlot, AssetSourceFingerprint, ComponentInstanceId, EditorAssetRef, MaterialRef, RendererMaterialSet,
StaticMeshRenderer, StaticMeshRendererEntry, RendererMaterialSlot, StaticMeshRenderer, StaticMeshRendererEntry,
}; };
pub const STATIC_MESH_MANIFEST_SCHEMA: u32 = 3; use crate::assets::fingerprint::{fingerprint_file, write_pretty_ron_if_changed};
pub const STATIC_MESH_MANIFEST_SCHEMA: u32 = 4;
pub const STATIC_MESH_ARTIFACT_DIR: &str = "assets/meshes/generated"; pub const STATIC_MESH_ARTIFACT_DIR: &str = "assets/meshes/generated";
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -42,11 +44,7 @@ pub struct StaticMeshSource {
pub dependencies: Vec<String>, pub dependencies: Vec<String>,
} }
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] pub type StaticMeshSourceFingerprint = AssetSourceFingerprint;
pub struct StaticMeshSourceFingerprint {
pub byte_len: u64,
pub modified_unix_secs: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshImportSnapshot { pub struct StaticMeshImportSnapshot {
@@ -134,16 +132,9 @@ pub fn refresh_static_mesh_artifact(
manifest.source.dependencies.dedup(); manifest.source.dependencies.dedup();
record.dependencies = manifest.source.dependencies.clone(); record.dependencies = manifest.source.dependencies.clone();
let text = ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()) if write_pretty_ron_if_changed(&path, &manifest)
.map_err(|err| format!("could not serialize static mesh manifest: {err}"))?; .map_err(|error| format!("could not publish static mesh manifest {path}: {error}"))?
if let Some(parent) = Path::new(&path).parent() { {
fs::create_dir_all(parent)
.map_err(|err| format!("could not create {}: {err}", parent.display()))?;
}
let should_write = fs::read_to_string(&path).ok().as_deref() != Some(text.as_str());
if should_write {
fs::write(&path, text)
.map_err(|err| format!("could not write static mesh manifest {path}: {err}"))?;
info!( info!(
"Static mesh manifest refreshed: source={} artifact={} parts={}", "Static mesh manifest refreshed: source={} artifact={} parts={}",
record.path, record.path,
@@ -287,7 +278,7 @@ fn part_effective_material_id(part: &StaticMeshPart) -> Option<String> {
fn build_static_mesh_manifest(record: &AssetRecord) -> Result<StaticMeshManifest, String> { fn build_static_mesh_manifest(record: &AssetRecord) -> Result<StaticMeshManifest, String> {
let format = source_format(&record.path)?; let format = source_format(&record.path)?;
let fingerprint = source_fingerprint(&record.path)?; let fingerprint = fingerprint_file(&record.path)?;
let import = StaticMeshImportSnapshot { let import = StaticMeshImportSnapshot {
scale: record.import_settings.scale, scale: record.import_settings.scale,
generate_collider: record.import_settings.generate_collider, generate_collider: record.import_settings.generate_collider,
@@ -494,6 +485,7 @@ fn build_fbx_manifest(
ufbx::LoadOpts { ufbx::LoadOpts {
target_unit_meters: 1.0, target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(), target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
filename: ufbx::StringOpt::Ref(&record.path),
..Default::default() ..Default::default()
}, },
) )
@@ -573,7 +565,7 @@ fn build_fbx_manifest(
path: record.path.clone(), path: record.path.clone(),
format, format,
fingerprint, fingerprint,
dependencies: fbx_dependencies(&record.path), dependencies: fbx_dependencies(&record.path, &scene)?,
}, },
import, import,
metadata: StaticMeshMetadata { metadata: StaticMeshMetadata {
@@ -602,25 +594,26 @@ fn fbx_material_label(scene: &ufbx::Scene, element_id: u32) -> Option<String> {
.map(|index| FbxAssetLabel::Material(index).to_string()) .map(|index| FbxAssetLabel::Material(index).to_string())
} }
fn fbx_dependencies(source_path: &str) -> Vec<String> { fn fbx_dependencies(source_path: &str, scene: &ufbx::Scene) -> Result<Vec<String>, String> {
let path = Path::new(source_path); let path = Path::new(source_path);
let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else { let parent = path.parent().unwrap_or_else(|| Path::new(""));
return Vec::new(); external_texture_paths(scene)
}; .map_err(|errors| {
let Some(parent) = path.parent() else { format!(
return Vec::new(); "unsafe FBX texture reference(s) in {source_path}: {}",
}; errors
let sidecar = parent.join(format!("{stem}.fbm")); .into_iter()
if !sidecar.is_dir() { .map(|error| error.to_string())
return Vec::new(); .collect::<Vec<_>>()
} .join("; ")
walkdir::WalkDir::new(sidecar) )
.follow_links(false) })
.into_iter() .map(|paths| {
.filter_map(Result::ok) paths
.filter(|entry| entry.file_type().is_file()) .into_iter()
.map(|entry| entry.path().to_string_lossy().replace('\\', "/")) .map(|relative| parent.join(relative).to_string_lossy().replace('\\', "/"))
.collect() .collect()
})
} }
fn source_format(path: &str) -> Result<String, String> { fn source_format(path: &str) -> Result<String, String> {
@@ -631,20 +624,6 @@ fn source_format(path: &str) -> Result<String, String> {
.ok_or_else(|| format!("asset path `{path}` has no extension")) .ok_or_else(|| format!("asset path `{path}` has no extension"))
} }
fn source_fingerprint(path: &str) -> Result<StaticMeshSourceFingerprint, String> {
let metadata = fs::metadata(path).map_err(|err| format!("could not stat {path}: {err}"))?;
let modified_unix_secs = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or_default();
Ok(StaticMeshSourceFingerprint {
byte_len: metadata.len(),
modified_unix_secs,
})
}
fn resolve_dependency(source_path: &str, uri: &str) -> String { fn resolve_dependency(source_path: &str, uri: &str) -> String {
if uri.starts_with("data:") || uri.contains("://") { if uri.starts_with("data:") || uri.contains("://") {
return uri.to_string(); return uri.to_string();
@@ -672,7 +651,7 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: StaticMeshSourceFingerprint { fingerprint: StaticMeshSourceFingerprint {
byte_len: 42, byte_len: 42,
modified_unix_secs: 10, content_hash: "a".repeat(64),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
}, },
@@ -741,6 +720,55 @@ mod tests {
); );
} }
#[test]
fn schema_v3_manifest_without_hash_migrates_to_content_fingerprint() {
let root = std::env::temp_dir().join(format!(
"blacksite-static-mesh-legacy-{}",
uuid::Uuid::new_v4()
));
fs::create_dir_all(&root).unwrap();
let path = root.join("legacy.static_mesh.ron");
let expected = test_manifest();
let canonical =
ron::ser::to_string_pretty(&expected, ron::ser::PrettyConfig::default()).unwrap();
let legacy = canonical
.replacen("schema_version: 4", "schema_version: 3", 1)
.lines()
.filter(|line| !line.contains("content_hash:"))
.collect::<Vec<_>>()
.join("\n");
fs::write(&path, legacy).unwrap();
assert!(write_pretty_ron_if_changed(&path, &expected).unwrap());
assert_eq!(
load_static_mesh_manifest(&path.to_string_lossy()).unwrap(),
expected
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn equivalent_static_manifest_preserves_existing_formatting_and_newline() {
let root = std::env::temp_dir().join(format!(
"blacksite-static-mesh-semantic-{}",
uuid::Uuid::new_v4()
));
fs::create_dir_all(&root).unwrap();
let path = root.join("stable.static_mesh.ron");
let manifest = test_manifest();
let exact = format!(
"{}\n\n",
ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()).unwrap()
);
fs::write(&path, &exact).unwrap();
assert!(!write_pretty_ron_if_changed(&path, &manifest).unwrap());
assert_eq!(fs::read_to_string(&path).unwrap(), exact);
fs::remove_dir_all(root).unwrap();
}
#[test] #[test]
fn renderer_from_manifest_can_ignore_source_materials() { fn renderer_from_manifest_can_ignore_source_materials() {
let manifest = test_manifest(); let manifest = test_manifest();
@@ -785,6 +813,7 @@ mod tests {
path, path,
label: "Robot Expressive".into(), label: "Robot Expressive".into(),
kind_tag: "Model".into(), kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings::default(), import_settings: ImportSettings::default(),
dependencies: Vec::new(), dependencies: Vec::new(),
}; };
@@ -797,4 +826,30 @@ mod tests {
assert!(manifest.parts.iter().any(|part| part.skinned)); assert!(manifest.parts.iter().any(|part| part.skinned));
assert!(renderer.slots.is_empty()); assert!(renderer.slots.is_empty());
} }
#[test]
fn committed_fbx_records_sibling_texture_dependencies() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx")
.to_string_lossy()
.into_owned();
let record = AssetRecord {
id: AssetId::new(),
path,
label: "Painted Chair".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
};
let manifest = build_static_mesh_manifest(&record).unwrap();
assert_eq!(manifest.source.dependencies.len(), 3);
assert!(manifest
.source
.dependencies
.iter()
.all(|path| path.contains("assets/models/textures/painted_wooden_chair_02_")));
}
} }
+113 -2
View File
@@ -1,7 +1,9 @@
//! Thumbnail cache for asset browser grid cells. //! Thumbnail cache for asset browser grid cells.
use std::collections::{HashMap, HashSet}; use std::collections::{HashMap, HashSet};
use std::path::Path;
use bevy::asset::LoadState;
use bevy::prelude::*; use bevy::prelude::*;
use bevy_egui::{egui, EguiPrimaryContextPass, EguiTextureHandle, EguiUserTextures}; use bevy_egui::{egui, EguiPrimaryContextPass, EguiTextureHandle, EguiUserTextures};
use egui_phosphor_icons::icons; use egui_phosphor_icons::icons;
@@ -79,6 +81,9 @@ impl AssetThumbnailCache {
if self.failed.contains_key(&key) { if self.failed.contains_key(&key) {
return; return;
} }
if !self.texture_source_ready(&key, &path) {
return;
}
let handle: Handle<Image> = asset_server.load(asset_server_path(&path)); let handle: Handle<Image> = asset_server.load(asset_server_path(&path));
self.pending.insert(key, handle); self.pending.insert(key, handle);
} }
@@ -161,7 +166,7 @@ impl AssetThumbnailCache {
{ {
return; return;
} }
if !self.model_source_ready(&key, &model_path) { if !self.source_material_ready(&key, &model_path) {
return; return;
} }
if studio.enqueue_source( if studio.enqueue_source(
@@ -224,6 +229,32 @@ impl AssetThumbnailCache {
true true
} }
fn texture_source_ready(&mut self, key: &str, texture_path: &str) -> bool {
if Path::new(texture_path).is_file() {
return true;
}
self.mark_studio_failed(key, &format!("missing texture: {texture_path}"), false);
false
}
fn source_material_ready(&mut self, key: &str, model_path: &str) -> bool {
if !self.model_source_ready(key, model_path) {
return false;
}
if model_path
.rsplit_once('.')
.is_some_and(|(_, extension)| extension.eq_ignore_ascii_case("fbx"))
{
if let Err(reason) =
crate::assets::import::validate_fbx_dependencies(std::path::Path::new(model_path))
{
self.mark_studio_failed(key, &reason, false);
return false;
}
}
true
}
pub(crate) fn complete_studio_thumbnail( pub(crate) fn complete_studio_thumbnail(
&mut self, &mut self,
key: &str, key: &str,
@@ -268,6 +299,11 @@ impl AssetThumbnailCache {
.cloned() .cloned()
.collect(), .collect(),
failed_keys: self.failed.keys().cloned().collect(), failed_keys: self.failed.keys().cloned().collect(),
failure_reasons: self
.failed
.iter()
.map(|(key, failure)| (key.clone(), failure.reason.clone()))
.collect(),
} }
} }
} }
@@ -277,6 +313,14 @@ fn register_loaded_thumbnails(
mut cache: ResMut<AssetThumbnailCache>, mut cache: ResMut<AssetThumbnailCache>,
mut textures: ResMut<EguiUserTextures>, mut textures: ResMut<EguiUserTextures>,
) { ) {
let failed: Vec<(String, String)> = cache
.pending
.iter()
.filter_map(|(key, handle)| match asset_server.load_state(handle.id()) {
LoadState::Failed(error) => Some((key.clone(), error.to_string())),
_ => None,
})
.collect();
let ready: Vec<(String, Handle<Image>)> = cache let ready: Vec<(String, Handle<Image>)> = cache
.pending .pending
.iter() .iter()
@@ -284,6 +328,10 @@ fn register_loaded_thumbnails(
.map(|(key, handle)| (key.clone(), handle.clone())) .map(|(key, handle)| (key.clone(), handle.clone()))
.collect(); .collect();
for (key, error) in failed {
cache.mark_studio_failed(&key, &format!("texture load failed: {error}"), false);
}
for (key, handle) in ready { for (key, handle) in ready {
cache.pending.remove(&key); cache.pending.remove(&key);
cache.failed.remove(&key); cache.failed.remove(&key);
@@ -397,7 +445,11 @@ pub fn draw_asset_cell_with(
}, },
); );
response if let Some(reason) = failed {
response.on_hover_text(reason)
} else {
response
}
} }
#[derive(Clone)] #[derive(Clone)]
@@ -405,6 +457,7 @@ pub struct ThumbnailCacheSnapshot {
pub texture_ids: HashMap<String, egui::TextureId>, pub texture_ids: HashMap<String, egui::TextureId>,
pub pending_keys: Vec<String>, pub pending_keys: Vec<String>,
pub failed_keys: Vec<String>, pub failed_keys: Vec<String>,
pub failure_reasons: HashMap<String, String>,
} }
impl ThumbnailCacheSnapshot { impl ThumbnailCacheSnapshot {
@@ -420,6 +473,10 @@ impl ThumbnailCacheSnapshot {
self.failed_keys.iter().any(|failed| failed == key) self.failed_keys.iter().any(|failed| failed == key)
} }
pub fn failure_reason_for_key(&self, key: &str) -> Option<&str> {
self.failure_reasons.get(key).map(String::as_str)
}
pub fn texture_for(&self, asset: &EditorAsset) -> Option<egui::TextureId> { pub fn texture_for(&self, asset: &EditorAsset) -> Option<egui::TextureId> {
self.texture_ids.get(&asset_cache_key(asset)).copied() self.texture_ids.get(&asset_cache_key(asset)).copied()
} }
@@ -435,6 +492,10 @@ impl ThumbnailCacheSnapshot {
.iter() .iter()
.any(|key| key == &asset_cache_key(asset)) .any(|key| key == &asset_cache_key(asset))
} }
pub fn failure_reason(&self, asset: &EditorAsset) -> Option<&str> {
self.failure_reason_for_key(&asset_cache_key(asset))
}
} }
pub fn prefetch_folder_thumbnails(world: &mut World, folder: &str) { pub fn prefetch_folder_thumbnails(world: &mut World, folder: &str) {
@@ -534,3 +595,53 @@ pub fn invalidate_on_catalog_refresh(world: &mut World) {
world.commands().entity(root).despawn(); world.commands().entity(root).despawn();
} }
} }
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn missing_fbx_material_dependencies_are_one_stable_non_retryable_state() {
let model_path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx")
.to_string_lossy()
.into_owned();
let mut cache = AssetThumbnailCache::default();
assert!(cache.model_source_ready("model", &model_path));
assert!(!cache.source_material_ready("material", &model_path));
let first = cache.state("material");
assert!(!cache.source_material_ready("material", &model_path));
assert_eq!(cache.state("material"), first);
let Some(ThumbnailState::Failed { reason, retryable }) = first else {
panic!("missing FBX textures should produce one stable failure");
};
assert!(!retryable);
assert!(reason.starts_with("missing 3 FBX source texture(s):"));
assert!(cache.studio_pending.is_empty());
}
#[test]
fn missing_texture_is_one_stable_non_retryable_state() {
let path = std::env::temp_dir().join(format!(
"blacksite-missing-thumbnail-{}-{}.png",
std::process::id(),
std::thread::current().name().unwrap_or("test")
));
let path = path.to_string_lossy().into_owned();
let mut cache = AssetThumbnailCache::default();
assert!(!cache.texture_source_ready("texture", &path));
let first = cache.state("texture");
assert!(!cache.texture_source_ready("texture", &path));
assert_eq!(cache.state("texture"), first);
let Some(ThumbnailState::Failed { reason, retryable }) = first else {
panic!("missing texture should produce one stable failure");
};
assert!(!retryable);
assert_eq!(reason, format!("missing texture: {path}"));
assert!(cache.pending.is_empty());
}
}
@@ -83,6 +83,72 @@ impl ThumbnailModelSource for FbxThumbnailSource {
} }
} }
pub(crate) fn spawn_fbx_mesh_subasset_preview(
commands: &mut Commands,
meshes: &mut Assets<Mesh>,
materials: &mut Assets<StandardMaterial>,
root: Entity,
catalog_path: &str,
mesh_label: &str,
) -> bool {
let Some(encoded_index) = mesh_label
.strip_prefix("Mesh")
.and_then(|index| index.parse::<usize>().ok())
else {
warn!("FBX thumbnail: unsupported mesh label {mesh_label}");
return false;
};
let node_index = encoded_index / 1000;
let material_index = encoded_index % 1000;
let Ok(bytes) = std::fs::read(catalog_path) else {
warn!("FBX thumbnail: could not read {catalog_path}");
return false;
};
let Ok(scene) = ufbx::load_memory(
&bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
..Default::default()
},
) else {
warn!("FBX thumbnail: failed to parse {catalog_path}");
return false;
};
let Some(node) = scene.nodes.as_ref().get(node_index) else {
warn!("FBX thumbnail: mesh label {mesh_label} has no source node");
return false;
};
let Some(mesh_ref) = node.mesh.as_ref() else {
warn!("FBX thumbnail: mesh label {mesh_label} has no source mesh");
return false;
};
let Some(indices) = group_faces_by_material(mesh_ref.as_ref()).remove(&material_index) else {
warn!("FBX thumbnail: mesh label {mesh_label} has no material group");
return false;
};
if indices.is_empty() {
return false;
}
let mesh = meshes.add(build_mesh(mesh_ref.as_ref(), &indices));
let material = materials.add(StandardMaterial {
base_color: Color::srgb(0.72, 0.72, 0.75),
perceptual_roughness: 0.65,
..default()
});
let transform = Transform::from_matrix(convert_matrix(&node.geometry_to_world));
commands.entity(root).with_children(|parent| {
parent.spawn((
RenderLayers::layer(THUMBNAIL_LAYER),
Mesh3d(mesh),
MeshMaterial3d(material),
transform,
));
});
true
}
fn build_mesh(ufbx_mesh: &ufbx::Mesh, indices: &[u32]) -> Mesh { fn build_mesh(ufbx_mesh: &ufbx::Mesh, indices: &[u32]) -> Mesh {
let mut mesh = Mesh::new( let mut mesh = Mesh::new(
PrimitiveTopology::TriangleList, PrimitiveTopology::TriangleList,
@@ -3,6 +3,7 @@
mod fbx; mod fbx;
pub(crate) mod gltf; pub(crate) mod gltf;
pub(crate) use fbx::spawn_fbx_mesh_subasset_preview;
pub use fbx::FbxThumbnailSource; pub use fbx::FbxThumbnailSource;
pub use gltf::{gltf_skinned_primitive_labels, GltfThumbnailSource}; pub use gltf::{gltf_skinned_primitive_labels, GltfThumbnailSource};
+52 -11
View File
@@ -15,7 +15,7 @@ use shared::{material_from_desc, standard_material_asset_path, ModelRef};
use super::cache::AssetThumbnailCache; use super::cache::AssetThumbnailCache;
use super::job::{ThumbnailJob, ThumbnailJobSource}; use super::job::{ThumbnailJob, ThumbnailJobSource};
use super::sources::{source_for_extension, uses_scene_root}; use super::sources::{source_for_extension, spawn_fbx_mesh_subasset_preview, uses_scene_root};
use crate::assets::asset_server_path; use crate::assets::asset_server_path;
use crate::infra::EditorOnly; use crate::infra::EditorOnly;
@@ -27,6 +27,7 @@ const SCENE_FRAME_PADDING: f32 = 1.35;
const MATERIAL_SPHERE_FRAME_PADDING: f32 = 1.28; const MATERIAL_SPHERE_FRAME_PADDING: f32 = 1.28;
const MESH_WARMUP_FRAMES: u8 = 12; const MESH_WARMUP_FRAMES: u8 = 12;
const POST_ATTACH_FRAMES: u8 = 8; const POST_ATTACH_FRAMES: u8 = 8;
const FIRST_RENDER_WARMUP_FRAMES: u8 = 120;
const RENDER_FRAMES: u8 = 3; const RENDER_FRAMES: u8 = 3;
const COOLDOWN_FRAMES: u8 = 2; const COOLDOWN_FRAMES: u8 = 2;
const LOAD_TIMEOUT_FRAMES: u32 = 240; const LOAD_TIMEOUT_FRAMES: u32 = 240;
@@ -51,6 +52,7 @@ pub struct ThumbnailStudio {
queue: VecDeque<ThumbnailJob>, queue: VecDeque<ThumbnailJob>,
active: Option<ActiveModelThumbnail>, active: Option<ActiveModelThumbnail>,
cooldown_frames: u8, cooldown_frames: u8,
render_pipeline_warmed: bool,
} }
struct ActiveModelThumbnail { struct ActiveModelThumbnail {
@@ -209,6 +211,7 @@ fn setup_thumbnail_studio(mut commands: Commands, mut images: ResMut<Assets<Imag
queue: VecDeque::new(), queue: VecDeque::new(),
active: None, active: None,
cooldown_frames: 0, cooldown_frames: 0,
render_pipeline_warmed: false,
}); });
} }
@@ -288,7 +291,7 @@ fn process_thumbnail_studio(
camera.is_active = true; camera.is_active = true;
} }
active.camera_active = true; active.camera_active = true;
active.frames_remaining = RENDER_FRAMES; active.frames_remaining = capture_frames(studio.render_pipeline_warmed);
} }
studio.active = Some(active); studio.active = Some(active);
return; return;
@@ -299,6 +302,7 @@ fn process_thumbnail_studio(
active.frames_remaining -= 1; active.frames_remaining -= 1;
studio.active = Some(active); studio.active = Some(active);
} else { } else {
studio.render_pipeline_warmed = true;
cache.complete_studio_thumbnail( cache.complete_studio_thumbnail(
&active.cache_key, &active.cache_key,
active.render_image.clone(), active.render_image.clone(),
@@ -426,12 +430,15 @@ fn spawn_thumbnail_job_content(
material_label, material_label,
} => spawn_mesh_subasset_preview( } => spawn_mesh_subasset_preview(
commands, commands,
mesh_storage,
materials, materials,
asset_server, asset_server,
root, root,
model_path, MeshSubassetPreviewSpec {
mesh_label, model_path,
material_label.as_deref(), mesh_label,
material_label: material_label.as_deref(),
},
), ),
ThumbnailJobSource::SourceMaterial { ThumbnailJobSource::SourceMaterial {
model_path, model_path,
@@ -452,18 +459,38 @@ fn spawn_thumbnail_job_content(
} }
} }
struct MeshSubassetPreviewSpec<'a> {
model_path: &'a str,
mesh_label: &'a str,
material_label: Option<&'a str>,
}
fn spawn_mesh_subasset_preview( fn spawn_mesh_subasset_preview(
commands: &mut Commands, commands: &mut Commands,
mesh_storage: &mut Assets<Mesh>,
materials: &mut Assets<StandardMaterial>, materials: &mut Assets<StandardMaterial>,
asset_server: &AssetServer, asset_server: &AssetServer,
root: Entity, root: Entity,
model_path: &str, preview: MeshSubassetPreviewSpec<'_>,
mesh_label: &str,
material_label: Option<&str>,
) -> bool { ) -> bool {
let source_path = asset_server_path(model_path); if preview
let mesh: Handle<Mesh> = asset_server.load(labeled_asset_path(&source_path, mesh_label)); .model_path
let material = if let Some(material_label) = material_label { .rsplit_once('.')
.is_some_and(|(_, extension)| extension.eq_ignore_ascii_case("fbx"))
{
return spawn_fbx_mesh_subasset_preview(
commands,
mesh_storage,
materials,
root,
preview.model_path,
preview.mesh_label,
);
}
let source_path = asset_server_path(preview.model_path);
let mesh: Handle<Mesh> =
asset_server.load(labeled_asset_path(&source_path, preview.mesh_label));
let material = if let Some(material_label) = preview.material_label {
asset_server.load(standard_material_asset_path(&source_path, material_label)) asset_server.load(standard_material_asset_path(&source_path, material_label))
} else { } else {
materials.add(StandardMaterial { materials.add(StandardMaterial {
@@ -509,6 +536,14 @@ fn studio_render_image() -> Image {
Image::new_target_texture(THUMB_SIZE, THUMB_SIZE, TextureFormat::Rgba16Float, None) Image::new_target_texture(THUMB_SIZE, THUMB_SIZE, TextureFormat::Rgba16Float, None)
} }
fn capture_frames(render_pipeline_warmed: bool) -> u8 {
if render_pipeline_warmed {
RENDER_FRAMES
} else {
FIRST_RENDER_WARMUP_FRAMES
}
}
fn finish_active_thumbnail( fn finish_active_thumbnail(
commands: &mut Commands, commands: &mut Commands,
studio: &mut ThumbnailStudio, studio: &mut ThumbnailStudio,
@@ -734,4 +769,10 @@ mod tests {
assert!(material_distance < scene_distance * 0.6); assert!(material_distance < scene_distance * 0.6);
assert!((0.75..0.82).contains(&projected_radius_fraction)); assert!((0.75..0.82).contains(&projected_radius_fraction));
} }
#[test]
fn first_capture_keeps_camera_active_for_render_pipeline_warmup() {
assert_eq!(capture_frames(true), RENDER_FRAMES);
assert!(capture_frames(false) > capture_frames(true));
}
} }
+6 -1
View File
@@ -78,7 +78,12 @@ impl EditorCommandRegistry {
} }
} }
/// Custom inspector body for level objects (game crates register via [`register_actor_inspector_section`]). /// Custom inspector body for level objects (game crates register via
/// [`register_actor_inspector_section`]). Synchronous [`Self::ui`] callbacks run while
/// [`UiState`] is scoped out of `World`; implementations must not request that resource. Keep
/// extension-owned transient state in independently registered resources, use
/// [`crate::ui::request_ui_selection`] and [`crate::ui::request_editor_tab`] for host UI changes,
/// or defer other cross-panel work through extension-owned commands or events.
pub trait ActorInspectorSection: Send + Sync { pub trait ActorInspectorSection: Send + Sync {
fn id(&self) -> &str; fn id(&self) -> &str;
fn title(&self) -> &str; fn title(&self) -> &str;
+27 -23
View File
@@ -19,7 +19,6 @@ use shared::{
use crate::operators::{ActiveOperator, OperatorPhase, OperatorStatus}; use crate::operators::{ActiveOperator, OperatorPhase, OperatorStatus};
use crate::scene_io::{SceneIo, SceneIoRequest}; use crate::scene_io::{SceneIo, SceneIoRequest};
use crate::selection::SelectedEntity;
use crate::state::scene_tools_active; use crate::state::scene_tools_active;
use crate::ui::hierarchy_ops::{ use crate::ui::hierarchy_ops::{
apply_sibling_change, apply_sibling_change_new, hierarchy_drop_violation, next_sibling_index, apply_sibling_change, apply_sibling_change_new, hierarchy_drop_violation, next_sibling_index,
@@ -1631,7 +1630,7 @@ pub fn apply_command_undo(world: &mut World) {
undo_command(world, &mut command); undo_command(world, &mut command);
world.resource_mut::<EditorHistory>().push_redo(command); world.resource_mut::<EditorHistory>().push_redo(command);
world.resource_mut::<EditorHistory>().set_redo_status(label); world.resource_mut::<EditorHistory>().set_redo_status(label);
mark_dirty(world); crate::scene_io::reconcile_active_dirty_with_checkpoint(world);
} }
pub fn apply_command_redo(world: &mut World) { pub fn apply_command_redo(world: &mut World) {
@@ -1652,7 +1651,7 @@ pub fn apply_command_redo(world: &mut World) {
redo_command(world, &mut command); redo_command(world, &mut command);
world.resource_mut::<EditorHistory>().push_undo(command); world.resource_mut::<EditorHistory>().push_undo(command);
world.resource_mut::<EditorHistory>().set_undo_status(label); world.resource_mut::<EditorHistory>().set_undo_status(label);
mark_dirty(world); crate::scene_io::reconcile_active_dirty_with_checkpoint(world);
} }
fn prepare_prefab_source_history( fn prepare_prefab_source_history(
@@ -2872,32 +2871,15 @@ fn despawn_entity(world: &mut World, entity: Option<Entity>) {
} }
fn select_one(world: &mut World, entity: Entity) { fn select_one(world: &mut World, entity: Entity) {
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() { crate::ui::request_ui_selection(world, &[entity]);
ui_state.selected_entities.clear();
ui_state.selected_entities.select_replace(entity);
}
world.resource_mut::<SelectedEntity>().0 = Some(entity);
} }
fn select_many(world: &mut World, entities: &[Entity]) { fn select_many(world: &mut World, entities: &[Entity]) {
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() { crate::ui::request_ui_selection(world, entities);
ui_state.selected_entities.clear();
for (index, entity) in entities.iter().enumerate() {
if index == 0 {
ui_state.selected_entities.select_replace(*entity);
} else {
ui_state.selected_entities.select_maybe_add(*entity, true);
}
}
}
world.resource_mut::<SelectedEntity>().0 = entities.first().copied();
} }
pub fn clear_selection(world: &mut World) { pub fn clear_selection(world: &mut World) {
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() { crate::ui::request_ui_selection(world, &[]);
ui_state.selected_entities.clear();
}
world.resource_mut::<SelectedEntity>().0 = None;
} }
pub fn is_level_object(world: &World, entity: Entity) -> bool { pub fn is_level_object(world: &World, entity: Entity) -> bool {
@@ -2939,6 +2921,28 @@ mod tests {
use super::*; use super::*;
use crate::operators::test_harness::{assert_undo_redo_round_trip, OperatorInvariantHarness}; use crate::operators::test_harness::{assert_undo_redo_round_trip, OperatorInvariantHarness};
use crate::operators::{ActiveOperator, OperatorPhase}; use crate::operators::{ActiveOperator, OperatorPhase};
use crate::selection::SelectedEntity;
use crate::ui::PendingUiSelection;
#[test]
fn history_select_many_queues_exact_selection_while_ui_state_is_scoped_out() {
let first = Entity::from_bits(1);
let second = Entity::from_bits(2);
let mut world = World::new();
world.init_resource::<SelectedEntity>();
world.init_resource::<PendingUiSelection>();
world.insert_resource(UiState::default_layout());
world.resource_scope::<UiState, _>(|world, _ui_state| {
assert!(!world.contains_resource::<UiState>());
select_many(world, &[first, second]);
assert_eq!(
world.resource::<PendingUiSelection>().0.as_deref(),
Some([first, second].as_slice())
);
assert_eq!(world.resource::<SelectedEntity>().0, Some(first));
});
}
#[derive(Component, Reflect, Default, Debug, Clone, PartialEq)] #[derive(Component, Reflect, Default, Debug, Clone, PartialEq)]
#[reflect(Component, Default)] #[reflect(Component, Default)]
+7 -1
View File
@@ -27,8 +27,10 @@ pub use project::diagnostics_bundle;
pub use project::launcher; pub use project::launcher;
pub use project::native_dialog; pub use project::native_dialog;
pub use project::project_io; pub use project::project_io;
pub use project::samples;
pub use project::session; pub use project::session;
pub use project::settings_ui; pub use project::settings_ui;
pub use project::shutdown;
pub use scene::scene_io; pub use scene::scene_io;
pub use scene::scene_schema; pub use scene::scene_schema;
pub use scene::scene_view; pub use scene::scene_view;
@@ -74,6 +76,8 @@ use play::audio_preview::AudioPreviewPlugin;
use play::PlaySessionPlugin; use play::PlaySessionPlugin;
use project::collaboration::CollaborationPlugin; use project::collaboration::CollaborationPlugin;
use project::native_dialog::NativeDialogPlugin; use project::native_dialog::NativeDialogPlugin;
use project::samples::SampleCatalogPlugin;
use project::shutdown::ShutdownPlugin;
use project_io::ProjectIoPlugin; use project_io::ProjectIoPlugin;
use render_view::RenderViewPlugin; use render_view::RenderViewPlugin;
use scene_io::SceneIoPlugin; use scene_io::SceneIoPlugin;
@@ -98,7 +102,9 @@ impl PluginGroup for EditorPluginGroup {
let group = PluginGroupBuilder::start::<Self>() let group = PluginGroupBuilder::start::<Self>()
.add(EditorInfraPlugin) .add(EditorInfraPlugin)
.add(ProjectIoPlugin) .add(ProjectIoPlugin)
.add(SampleCatalogPlugin)
.add(NativeDialogPlugin) .add(NativeDialogPlugin)
.add(ShutdownPlugin)
.add(scene_schema::SceneSchemaPlugin) .add(scene_schema::SceneSchemaPlugin)
.add(net_editor::NetEditorPlugin) .add(net_editor::NetEditorPlugin)
.add(AssetDbPlugin) .add(AssetDbPlugin)
@@ -140,7 +146,7 @@ impl PluginGroup for EditorPluginGroup {
/// Shared Bevy app wiring for the in-process editor (game sim + egui shell). /// Shared Bevy app wiring for the in-process editor (game sim + egui shell).
pub fn configure_editor_app(app: &mut App) { pub fn configure_editor_app(app: &mut App) {
app.add_plugins(launch::default_plugins("Bevy FPS Editor")) app.add_plugins(launch::editor_plugins("Bevy FPS Editor"))
.insert_resource(GameInputEnabled(false)) .insert_resource(GameInputEnabled(false))
.insert_resource(GameInputFocused(false)) .insert_resource(GameInputFocused(false))
.insert_resource(SimEnabled(false)) .insert_resource(SimEnabled(false))
+2
View File
@@ -5,5 +5,7 @@ pub mod diagnostics_bundle;
pub mod launcher; pub mod launcher;
pub mod native_dialog; pub mod native_dialog;
pub mod project_io; pub mod project_io;
pub mod samples;
pub mod session; pub mod session;
pub mod settings_ui; pub mod settings_ui;
pub mod shutdown;
+208
View File
@@ -0,0 +1,208 @@
//! Cached project sample catalog used by editor scene-opening UI.
use std::path::{Path, PathBuf};
use bevy::prelude::*;
use scene::sample_pack::{
validate_editor_sample_pack, EditorSampleEntry, EDITOR_SAMPLE_MANIFEST_PATH,
};
use super::project_io::ProjectWorkspace;
const VALIDATION_HINT: &str = "Run `cargo validate-samples --project .` for details.";
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SampleCatalogEntry {
pub id: String,
pub label: String,
pub scene_path: PathBuf,
pub project_relative_scene: String,
pub summary: String,
pub checks: Vec<String>,
}
impl SampleCatalogEntry {
pub fn hover_text(&self) -> String {
let mut lines = vec![self.summary.clone()];
if !self.checks.is_empty() {
lines.push(format!("Checks: {}", self.checks.join(", ")));
}
lines.push(self.project_relative_scene.clone());
lines.join("\n")
}
}
#[derive(Resource, Debug, Clone)]
pub struct SampleCatalog {
entries: Vec<SampleCatalogEntry>,
unavailable_reason: Option<String>,
}
impl Default for SampleCatalog {
fn default() -> Self {
Self::unavailable("Sample catalog is loading")
}
}
impl SampleCatalog {
pub fn entries(&self) -> &[SampleCatalogEntry] {
&self.entries
}
pub fn entry(&self, stable_id: &str) -> Option<&SampleCatalogEntry> {
self.unavailable_reason
.is_none()
.then(|| self.entries.iter().find(|entry| entry.id == stable_id))
.flatten()
}
pub fn unavailable_reason(&self) -> Option<&str> {
self.unavailable_reason.as_deref()
}
#[cfg(test)]
pub(crate) fn available_entries(entries: Vec<SampleCatalogEntry>) -> Self {
Self {
entries,
unavailable_reason: None,
}
}
fn available(samples: Vec<EditorSampleEntry>) -> Self {
Self {
entries: samples.into_iter().map(catalog_entry).collect(),
unavailable_reason: None,
}
}
fn unavailable(reason: impl Into<String>) -> Self {
Self {
entries: Vec::new(),
unavailable_reason: Some(reason.into()),
}
}
}
fn catalog_entry(entry: EditorSampleEntry) -> SampleCatalogEntry {
SampleCatalogEntry {
id: entry.id,
label: entry.label,
scene_path: PathBuf::from(&entry.scene),
project_relative_scene: entry.scene,
summary: entry.summary,
checks: entry.checks,
}
}
fn load_catalog(project_root: &Path) -> SampleCatalog {
let validation = validate_editor_sample_pack(project_root);
if !validation.is_release_ready() {
let first_error = validation
.report
.findings
.iter()
.find(|finding| finding.severity == scene::ValidationSeverity::Error)
.map(|finding| finding.message.as_str())
.unwrap_or("sample pack validation failed");
return SampleCatalog::unavailable(format!(
"Sample manifest `{EDITOR_SAMPLE_MANIFEST_PATH}` is invalid: {first_error}\n{VALIDATION_HINT}"
));
}
if validation.samples.is_empty() {
return SampleCatalog::unavailable(format!(
"Sample manifest contains no scenes.\n{VALIDATION_HINT}"
));
}
SampleCatalog::available(validation.samples)
}
fn load_sample_catalog(world: &mut World) {
let project_root = PathBuf::from(&world.resource::<ProjectWorkspace>().root);
world.insert_resource(load_catalog(&project_root));
}
pub struct SampleCatalogPlugin;
impl Plugin for SampleCatalogPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<SampleCatalog>()
.add_systems(Startup, load_sample_catalog);
}
}
#[cfg(test)]
mod tests {
use super::*;
use scene::sample_pack::EditorSampleArea;
fn sample(id: &str, label: &str, scene: &str) -> EditorSampleEntry {
EditorSampleEntry {
id: id.into(),
label: label.into(),
area: EditorSampleArea::Brush,
scene: scene.into(),
summary: format!("Summary for {label}"),
checks: vec!["selection".into(), "undo".into()],
}
}
#[test]
fn available_catalog_preserves_manifest_order_and_resolves_paths() {
let catalog = SampleCatalog::available(vec![
sample(
"terrain",
"Terrain",
"assets/levels/samples/terrain.scn.ron",
),
sample("brush", "Brush", "assets/levels/samples/brush.scn.ron"),
]);
assert_eq!(
catalog
.entries()
.iter()
.map(|entry| entry.id.as_str())
.collect::<Vec<_>>(),
vec!["terrain", "brush"]
);
assert_eq!(
catalog.entry("brush").unwrap().scene_path,
PathBuf::from("assets/levels/samples/brush.scn.ron")
);
let hover = catalog.entry("brush").unwrap().hover_text();
assert!(hover.contains("Summary for Brush"));
assert!(hover.contains("Checks: selection, undo"));
assert!(hover.contains("assets/levels/samples/brush.scn.ron"));
}
#[test]
fn unavailable_catalog_never_resolves_entries() {
let catalog = SampleCatalog {
entries: vec![catalog_entry(sample(
"brush",
"Brush",
"assets/levels/samples/brush.scn.ron",
))],
unavailable_reason: Some("manifest invalid".into()),
};
assert!(catalog.entry("brush").is_none());
assert_eq!(catalog.unavailable_reason(), Some("manifest invalid"));
}
#[test]
fn missing_manifest_reports_repair_command() {
let root = std::env::temp_dir().join(format!(
"blacksite-missing-sample-catalog-{}",
uuid::Uuid::new_v4()
));
std::fs::create_dir_all(&root).unwrap();
let catalog = load_catalog(&root);
let reason = catalog.unavailable_reason().unwrap();
assert!(reason.contains(EDITOR_SAMPLE_MANIFEST_PATH));
assert!(reason.contains("cargo validate-samples --project ."));
std::fs::remove_dir_all(root).unwrap();
}
}
+8 -2
View File
@@ -11,6 +11,7 @@ use crate::project_io::{ProjectWorkspace, UserPreferences};
use crate::scene::recovery::{atomic_write, default_state_root}; use crate::scene::recovery::{atomic_write, default_state_root};
use crate::scene_io::{SceneIo, SceneIoRequest}; use crate::scene_io::{SceneIo, SceneIoRequest};
use crate::settings_ui::ProjectSettingsPanel; use crate::settings_ui::ProjectSettingsPanel;
use crate::shutdown::ShutdownCoordinator;
use crate::ui::{BrushDiagnosticsPanel, DiagnosticsPanel}; use crate::ui::{BrushDiagnosticsPanel, DiagnosticsPanel};
use crate::viewport::rendering_diagnostics::RenderingDiagnosticsPanel; use crate::viewport::rendering_diagnostics::RenderingDiagnosticsPanel;
use crate::viewport::CameraBookmarks; use crate::viewport::CameraBookmarks;
@@ -109,8 +110,8 @@ impl Plugin for EditorSessionPlugin {
.add_systems(Startup, initialize_session) .add_systems(Startup, initialize_session)
.add_systems(Update, persist_running_session) .add_systems(Update, persist_running_session)
.add_systems( .add_systems(
Last, crate::shutdown::EditorShutdownFinalize,
persist_clean_session_on_exit.after(bevy::window::ExitSystems), persist_clean_session_on_exit.after(crate::shutdown::finalize_authorized_shutdown),
); );
} }
} }
@@ -311,6 +312,7 @@ fn persist_running_session(world: &mut World) {
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
fn persist_clean_session_on_exit( fn persist_clean_session_on_exit(
mut exits: MessageReader<AppExit>, mut exits: MessageReader<AppExit>,
shutdown: Option<Res<ShutdownCoordinator>>,
scene_io: Res<SceneIo>, scene_io: Res<SceneIo>,
workspace: Res<ProjectWorkspace>, workspace: Res<ProjectWorkspace>,
prefs: Res<UserPreferences>, prefs: Res<UserPreferences>,
@@ -323,6 +325,10 @@ fn persist_clean_session_on_exit(
if exits.read().next().is_none() { if exits.read().next().is_none() {
return; return;
} }
if !shutdown.is_some_and(|shutdown| shutdown.authorized_exit_sent()) {
warn!("Ignoring an unauthorized AppExit for clean-session persistence");
return;
}
let Some(path) = session_path() else { let Some(path) = session_path() else {
return; return;
}; };
+752
View File
@@ -0,0 +1,752 @@
//! Guarded editor shutdown and the handoff to scene persistence.
use bevy::app::{AppExit, MainScheduleOrder};
use bevy::ecs::schedule::ScheduleLabel;
use bevy::prelude::*;
use bevy::window::{PrimaryWindow, WindowCloseRequested};
use crate::native_dialog::NativeDialogBroker;
use crate::scene_io::SceneIo;
const SAVE_ALL_LABEL: &str = "Save All";
const DISCARD_LABEL: &str = "Discard";
const CANCEL_LABEL: &str = "Cancel";
/// The user or editor surface that initiated a guarded shutdown.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShutdownSource {
NativeWindow,
FileMenu,
Programmatic,
SwitchProject,
}
/// Observable state of the single editor shutdown flow.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ShutdownIntent {
#[default]
Idle,
WaitingForBroker {
source: ShutdownSource,
},
Confirming {
source: ShutdownSource,
},
Saving {
source: ShutdownSource,
},
Authorized {
source: ShutdownSource,
require_clean_scenes: bool,
},
ExitSent {
source: ShutdownSource,
},
}
impl ShutdownIntent {
pub fn source(self) -> Option<ShutdownSource> {
match self {
Self::Idle => None,
Self::WaitingForBroker { source }
| Self::Confirming { source }
| Self::Saving { source }
| Self::Authorized { source, .. }
| Self::ExitSent { source } => Some(source),
}
}
}
/// Coordinates all editor exit requests so only an authorized flow emits [`AppExit`].
#[derive(Resource, Debug, Default)]
pub struct ShutdownCoordinator {
intent: ShutdownIntent,
coalesced_requests: u32,
last_blocker: Option<String>,
}
impl ShutdownCoordinator {
pub fn intent(&self) -> ShutdownIntent {
self.intent
}
pub fn coalesced_requests(&self) -> u32 {
self.coalesced_requests
}
pub fn last_blocker(&self) -> Option<&str> {
self.last_blocker.as_deref()
}
pub fn authorized_exit_sent(&self) -> bool {
matches!(self.intent, ShutdownIntent::ExitSent { .. })
}
/// Queue a shutdown if no shutdown flow is already active.
///
/// Repeated window, menu, or programmatic requests are coalesced until the
/// current flow is cancelled, fails to save, or sends the authorized exit.
pub fn request(&mut self, source: ShutdownSource) -> bool {
if self.intent != ShutdownIntent::Idle {
self.coalesced_requests = self.coalesced_requests.saturating_add(1);
return false;
}
self.intent = ShutdownIntent::WaitingForBroker { source };
self.coalesced_requests = 0;
self.last_blocker = None;
true
}
#[cfg(test)]
pub(crate) fn set_intent_for_test(&mut self, intent: ShutdownIntent) {
self.intent = intent;
}
}
/// Emitted once when the guarded dialog chooses `Save All`.
///
/// Scene persistence owns the actual save sequence and must finish it with
/// [`complete_shutdown_save`].
#[derive(Message, Debug, Clone, Copy, PartialEq, Eq)]
pub struct ShutdownSaveAllRequested {
pub source: ShutdownSource,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ShutdownSaveOutcome {
Saved,
Cancelled,
Failed(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShutdownDecision {
SaveAll,
Discard,
Cancel,
}
/// Runs after Bevy's `Last` schedule so no editor authoring system can mutate
/// a document after the final dirty-state check in the same frame.
#[derive(ScheduleLabel, Debug, Clone, PartialEq, Eq, Hash)]
pub struct EditorShutdownFinalize;
/// Queue a guarded shutdown from an exclusive-world UI or workflow callback.
pub fn request_editor_shutdown(world: &mut World, source: ShutdownSource) -> bool {
world
.get_resource_mut::<ShutdownCoordinator>()
.is_some_and(|mut coordinator| coordinator.request(source))
}
/// Queue a project-browser handoff through the same dirty-document guard as editor exit.
pub fn request_project_switch(world: &mut World) -> bool {
request_editor_shutdown(world, ShutdownSource::SwitchProject)
}
/// Resolve the dirty-scene confirmation through the shared coordinator.
pub fn resolve_shutdown_decision(world: &mut World, decision: ShutdownDecision) -> bool {
let (save_request, status) = {
let Some(mut coordinator) = world.get_resource_mut::<ShutdownCoordinator>() else {
return false;
};
let ShutdownIntent::Confirming { source } = coordinator.intent else {
return false;
};
match decision {
ShutdownDecision::SaveAll => {
coordinator.intent = ShutdownIntent::Saving { source };
(
Some(source),
Some("Saving all modified scene tabs before shutdown"),
)
}
ShutdownDecision::Discard => {
coordinator.intent = ShutdownIntent::Authorized {
source,
require_clean_scenes: false,
};
(None, None)
}
ShutdownDecision::Cancel => {
coordinator.intent = ShutdownIntent::Idle;
(
None,
Some("Shutdown cancelled; unsaved scene tabs retained"),
)
}
}
};
if let Some(status) = status {
if let Some(mut scene_io) = world.get_resource_mut::<SceneIo>() {
scene_io.set_status(status);
}
}
if let Some(source) = save_request {
world.write_message(ShutdownSaveAllRequested { source });
}
true
}
/// Finish the save-all handoff. A reported success is authorized only after
/// every scene tab is observably clean.
pub fn complete_shutdown_save(world: &mut World, outcome: ShutdownSaveOutcome) -> bool {
let scenes_are_clean = !scene_has_unsaved_changes(world);
let Some(mut coordinator) = world.get_resource_mut::<ShutdownCoordinator>() else {
return false;
};
let ShutdownIntent::Saving { source } = coordinator.intent else {
return false;
};
match outcome {
ShutdownSaveOutcome::Saved if scenes_are_clean => {
coordinator.intent = ShutdownIntent::Authorized {
source,
require_clean_scenes: true,
};
coordinator.last_blocker = None;
true
}
ShutdownSaveOutcome::Saved => {
coordinator.intent = ShutdownIntent::Idle;
coordinator.last_blocker =
Some("Save All completed while unsaved scene tabs remain".into());
false
}
ShutdownSaveOutcome::Cancelled => {
coordinator.intent = ShutdownIntent::Idle;
coordinator.last_blocker = None;
false
}
ShutdownSaveOutcome::Failed(error) => {
coordinator.intent = ShutdownIntent::Idle;
coordinator.last_blocker = Some(error);
false
}
}
}
pub struct ShutdownPlugin;
impl Plugin for ShutdownPlugin {
fn build(&self, app: &mut App) {
app.init_schedule(EditorShutdownFinalize);
app.world_mut()
.resource_mut::<MainScheduleOrder>()
.insert_after(Last, EditorShutdownFinalize);
app.init_resource::<ShutdownCoordinator>()
.add_message::<ShutdownSaveAllRequested>()
.add_systems(
Update,
(capture_native_close_requests, drive_shutdown).chain(),
)
.add_systems(EditorShutdownFinalize, finalize_authorized_shutdown);
}
}
fn capture_native_close_requests(
mut commands: Commands,
mut close_requests: MessageReader<WindowCloseRequested>,
primary_window: Query<Entity, With<PrimaryWindow>>,
mut coordinator: ResMut<ShutdownCoordinator>,
) {
let Ok(primary_window) = primary_window.single() else {
return;
};
for request in close_requests.read() {
if request.window == primary_window {
coordinator.request(ShutdownSource::NativeWindow);
} else {
commands.entity(request.window).despawn();
}
}
}
fn drive_shutdown(world: &mut World) {
let intent = world.resource::<ShutdownCoordinator>().intent;
match intent {
ShutdownIntent::Idle
| ShutdownIntent::Confirming { .. }
| ShutdownIntent::Saving { .. }
| ShutdownIntent::ExitSent { .. } => {}
ShutdownIntent::WaitingForBroker { source } => {
let unsaved_count = unsaved_scene_count(world);
if unsaved_count == 0 {
world.resource_mut::<ShutdownCoordinator>().intent = ShutdownIntent::Authorized {
source,
require_clean_scenes: true,
};
return;
}
if world.resource::<NativeDialogBroker>().is_pending() {
return;
}
let action = if source == ShutdownSource::SwitchProject {
"switching projects"
} else {
"quitting"
};
let description = if unsaved_count == 1 {
format!("One scene tab has unsaved changes. Save it before {action}?")
} else {
format!(
"{unsaved_count} scene tabs have unsaved changes. Save all before {action}?"
)
};
let title = if source == ShutdownSource::SwitchProject {
"Switch Project"
} else {
"Quit Blacksite Editor"
};
let request = world.resource::<NativeDialogBroker>().request(
move || {
rfd::MessageDialog::new()
.set_title(title)
.set_description(description)
.set_level(rfd::MessageLevel::Warning)
.set_buttons(rfd::MessageButtons::YesNoCancelCustom(
SAVE_ALL_LABEL.into(),
DISCARD_LABEL.into(),
CANCEL_LABEL.into(),
))
.show()
},
|world, result| {
resolve_shutdown_decision(world, decision_from_dialog(result));
},
);
if request.is_ok() {
world.resource_mut::<ShutdownCoordinator>().intent =
ShutdownIntent::Confirming { source };
}
}
ShutdownIntent::Authorized { .. } => {}
}
}
/// Final dirty-state recheck after editor UI and authoring schedules have completed.
pub(crate) fn finalize_authorized_shutdown(world: &mut World) {
let (source, require_clean_scenes) = {
let coordinator = world.resource::<ShutdownCoordinator>();
let ShutdownIntent::Authorized {
source,
require_clean_scenes,
} = coordinator.intent
else {
return;
};
(source, require_clean_scenes)
};
if require_clean_scenes && scene_has_unsaved_changes(world) {
world.resource_mut::<ShutdownCoordinator>().intent =
ShutdownIntent::WaitingForBroker { source };
return;
}
if source == ShutdownSource::SwitchProject {
if let Err(error) = crate::launcher::spawn_project_launcher_process() {
let message = format!("Switch project failed: {error}");
{
let mut coordinator = world.resource_mut::<ShutdownCoordinator>();
coordinator.intent = ShutdownIntent::Idle;
coordinator.last_blocker = Some(message.clone());
}
if let Some(mut scene_io) = world.get_resource_mut::<SceneIo>() {
scene_io.set_status(message);
}
return;
}
}
world.resource_mut::<ShutdownCoordinator>().intent = ShutdownIntent::ExitSent { source };
debug!(?source, "Editor shutdown authorized");
world.write_message(AppExit::Success);
}
fn scene_has_unsaved_changes(world: &World) -> bool {
world
.get_resource::<SceneIo>()
.is_some_and(SceneIo::has_unsaved_tabs)
}
fn unsaved_scene_count(world: &World) -> usize {
let Some(scene_io) = world.get_resource::<SceneIo>() else {
return 0;
};
let tab_count = scene_io.tabs.iter().filter(|tab| tab.dirty).count();
if scene_io.dirty
&& scene_io
.tabs
.get(scene_io.active_tab)
.is_none_or(|tab| !tab.dirty)
{
tab_count + 1
} else {
tab_count
}
}
fn decision_from_dialog(result: rfd::MessageDialogResult) -> ShutdownDecision {
match result {
rfd::MessageDialogResult::Custom(label) if label == SAVE_ALL_LABEL => {
ShutdownDecision::SaveAll
}
rfd::MessageDialogResult::Custom(label) if label == DISCARD_LABEL => {
ShutdownDecision::Discard
}
rfd::MessageDialogResult::Yes => ShutdownDecision::SaveAll,
rfd::MessageDialogResult::No => ShutdownDecision::Discard,
_ => ShutdownDecision::Cancel,
}
}
#[cfg(test)]
mod tests {
use std::sync::mpsc;
use bevy::ecs::message::MessageCursor;
use super::*;
use crate::native_dialog::NativeDialogPlugin;
fn confirming_world() -> World {
let mut world = World::new();
world.init_resource::<Messages<ShutdownSaveAllRequested>>();
world.insert_resource(ShutdownCoordinator {
intent: ShutdownIntent::Confirming {
source: ShutdownSource::FileMenu,
},
..default()
});
world
}
#[test]
fn repeated_requests_are_coalesced_behind_the_first_source() {
let mut coordinator = ShutdownCoordinator::default();
assert!(coordinator.request(ShutdownSource::NativeWindow));
assert!(!coordinator.request(ShutdownSource::FileMenu));
assert_eq!(coordinator.coalesced_requests(), 1);
assert_eq!(
coordinator.intent(),
ShutdownIntent::WaitingForBroker {
source: ShutdownSource::NativeWindow
}
);
}
#[test]
fn cancel_returns_to_idle_and_discard_authorizes_exit() {
let mut cancel_world = confirming_world();
assert!(resolve_shutdown_decision(
&mut cancel_world,
ShutdownDecision::Cancel
));
assert_eq!(
cancel_world.resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::Idle
);
let mut discard_world = confirming_world();
assert!(resolve_shutdown_decision(
&mut discard_world,
ShutdownDecision::Discard
));
assert_eq!(
discard_world.resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::Authorized {
source: ShutdownSource::FileMenu,
require_clean_scenes: false,
}
);
}
#[test]
fn dirty_cancel_preserves_the_session_and_discard_emits_one_exit() {
let mut app = App::new();
app.add_message::<AppExit>()
.init_resource::<SceneIo>()
.init_resource::<ShutdownCoordinator>();
app.world_mut().resource_mut::<SceneIo>().mark_dirty();
app.world_mut()
.resource_mut::<ShutdownCoordinator>()
.set_intent_for_test(ShutdownIntent::Confirming {
source: ShutdownSource::Programmatic,
});
assert!(resolve_shutdown_decision(
app.world_mut(),
ShutdownDecision::Cancel
));
drive_shutdown(app.world_mut());
finalize_authorized_shutdown(app.world_mut());
assert_eq!(app.should_exit(), None);
assert!(app.world().resource::<SceneIo>().has_unsaved_tabs());
app.world_mut()
.resource_mut::<ShutdownCoordinator>()
.set_intent_for_test(ShutdownIntent::Confirming {
source: ShutdownSource::Programmatic,
});
assert!(resolve_shutdown_decision(
app.world_mut(),
ShutdownDecision::Discard
));
drive_shutdown(app.world_mut());
finalize_authorized_shutdown(app.world_mut());
assert_eq!(app.should_exit(), Some(AppExit::Success));
assert!(app.world().resource::<SceneIo>().has_unsaved_tabs());
assert!(app
.world()
.resource::<ShutdownCoordinator>()
.authorized_exit_sent());
}
#[test]
fn file_menu_and_programmatic_clean_exit_use_the_same_coordinator_path() {
for source in [ShutdownSource::FileMenu, ShutdownSource::Programmatic] {
let mut app = App::new();
app.add_message::<AppExit>()
.init_resource::<SceneIo>()
.init_resource::<ShutdownCoordinator>()
.init_resource::<NativeDialogBroker>();
assert!(request_editor_shutdown(app.world_mut(), source));
drive_shutdown(app.world_mut());
finalize_authorized_shutdown(app.world_mut());
assert_eq!(app.should_exit(), Some(AppExit::Success));
assert_eq!(
app.world().resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::ExitSent { source }
);
}
}
#[test]
fn save_all_emits_one_persistence_handoff() {
let mut world = confirming_world();
let mut cursor = MessageCursor::<ShutdownSaveAllRequested>::default();
assert!(resolve_shutdown_decision(
&mut world,
ShutdownDecision::SaveAll
));
assert!(!resolve_shutdown_decision(
&mut world,
ShutdownDecision::SaveAll
));
let messages = world.resource::<Messages<ShutdownSaveAllRequested>>();
let requests: Vec<_> = cursor.read(messages).copied().collect();
assert_eq!(
requests,
vec![ShutdownSaveAllRequested {
source: ShutdownSource::FileMenu
}]
);
}
#[test]
fn clean_native_close_emits_the_authorized_exit() {
let mut app = App::new();
app.add_message::<WindowCloseRequested>()
.add_plugins((NativeDialogPlugin, ShutdownPlugin))
.init_resource::<SceneIo>();
let window = app.world_mut().spawn(PrimaryWindow).id();
app.world_mut()
.write_message(WindowCloseRequested { window });
app.update();
assert_eq!(app.should_exit(), Some(AppExit::Success));
assert_eq!(
app.world().resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::ExitSent {
source: ShutdownSource::NativeWindow
}
);
}
#[test]
fn secondary_window_close_does_not_request_editor_shutdown() {
let mut app = App::new();
app.add_message::<WindowCloseRequested>()
.add_plugins((NativeDialogPlugin, ShutdownPlugin))
.init_resource::<SceneIo>();
app.world_mut().spawn(PrimaryWindow);
let secondary = app.world_mut().spawn_empty().id();
app.world_mut()
.write_message(WindowCloseRequested { window: secondary });
app.update();
assert_eq!(app.should_exit(), None);
assert_eq!(
app.world().resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::Idle
);
assert!(app.world().get_entity(secondary).is_err());
}
#[test]
fn occupied_dialog_broker_keeps_shutdown_waiting() {
let mut app = App::new();
app.add_message::<WindowCloseRequested>()
.add_plugins((NativeDialogPlugin, ShutdownPlugin))
.init_resource::<SceneIo>();
app.world_mut().resource_mut::<SceneIo>().mark_dirty();
let (release_sender, release_receiver) = mpsc::channel();
app.world()
.resource::<NativeDialogBroker>()
.request(
move || release_receiver.recv().expect("release sender dropped"),
|_, _: ()| {},
)
.unwrap();
assert!(request_editor_shutdown(
app.world_mut(),
ShutdownSource::Programmatic
));
app.update();
assert_eq!(
app.world().resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::WaitingForBroker {
source: ShutdownSource::Programmatic
}
);
release_sender.send(()).unwrap();
}
#[test]
fn successful_save_requires_every_scene_tab_to_be_clean() {
let mut world = World::new();
world.init_resource::<SceneIo>();
world.insert_resource(ShutdownCoordinator {
intent: ShutdownIntent::Saving {
source: ShutdownSource::Programmatic,
},
..default()
});
assert!(complete_shutdown_save(
&mut world,
ShutdownSaveOutcome::Saved
));
assert_eq!(
world.resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::Authorized {
source: ShutdownSource::Programmatic,
require_clean_scenes: true,
}
);
world.resource_mut::<SceneIo>().mark_dirty();
world.resource_mut::<ShutdownCoordinator>().intent = ShutdownIntent::Saving {
source: ShutdownSource::Programmatic,
};
assert!(!complete_shutdown_save(
&mut world,
ShutdownSaveOutcome::Saved
));
assert_eq!(
world.resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::Idle
);
assert!(world
.resource::<ShutdownCoordinator>()
.last_blocker()
.is_some());
}
#[test]
fn a_new_edit_after_save_reopens_the_guard_instead_of_exiting() {
let mut world = World::new();
world.init_resource::<Messages<AppExit>>();
world.init_resource::<SceneIo>();
world.insert_resource(ShutdownCoordinator {
intent: ShutdownIntent::Authorized {
source: ShutdownSource::Programmatic,
require_clean_scenes: true,
},
..default()
});
world.resource_mut::<SceneIo>().mark_dirty();
finalize_authorized_shutdown(&mut world);
assert_eq!(
world.resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::WaitingForBroker {
source: ShutdownSource::Programmatic
}
);
let messages = world.resource::<Messages<AppExit>>();
assert_eq!(
MessageCursor::<AppExit>::default().read(messages).count(),
0
);
}
#[test]
fn last_schedule_edit_is_seen_before_final_exit_authorization() {
let mut app = App::new();
app.add_message::<WindowCloseRequested>()
.add_plugins((NativeDialogPlugin, ShutdownPlugin))
.init_resource::<SceneIo>()
.add_systems(Last, |mut scene_io: ResMut<SceneIo>| {
scene_io.mark_dirty();
});
assert!(request_editor_shutdown(
app.world_mut(),
ShutdownSource::Programmatic
));
app.update();
assert_eq!(app.should_exit(), None);
assert!(app.world().resource::<SceneIo>().has_unsaved_tabs());
assert_eq!(
app.world().resource::<ShutdownCoordinator>().intent(),
ShutdownIntent::WaitingForBroker {
source: ShutdownSource::Programmatic
}
);
}
#[test]
fn custom_dialog_labels_map_to_shutdown_decisions() {
assert_eq!(
decision_from_dialog(rfd::MessageDialogResult::Custom(SAVE_ALL_LABEL.into())),
ShutdownDecision::SaveAll
);
assert_eq!(
decision_from_dialog(rfd::MessageDialogResult::Custom(DISCARD_LABEL.into())),
ShutdownDecision::Discard
);
assert_eq!(
decision_from_dialog(rfd::MessageDialogResult::Custom(CANCEL_LABEL.into())),
ShutdownDecision::Cancel
);
}
#[test]
fn only_the_final_coordinator_state_authorizes_clean_session_persistence() {
let mut coordinator = ShutdownCoordinator::default();
assert!(!coordinator.authorized_exit_sent());
coordinator.intent = ShutdownIntent::Authorized {
source: ShutdownSource::Programmatic,
require_clean_scenes: true,
};
assert!(!coordinator.authorized_exit_sent());
coordinator.intent = ShutdownIntent::ExitSent {
source: ShutdownSource::Programmatic,
};
assert!(coordinator.authorized_exit_sent());
}
}
File diff suppressed because it is too large. Load diff
@@ -884,7 +884,6 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: AnimationSourceFingerprint { fingerprint: AnimationSourceFingerprint {
byte_len: 42, byte_len: 42,
modified_unix_secs: 1,
content_hash: "hash".into(), content_hash: "hash".into(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
+83 -14
View File
@@ -49,7 +49,9 @@ use crate::assets::{
ThumbnailCacheSnapshot, ThumbnailStudio, ThumbnailCacheSnapshot, ThumbnailStudio,
}; };
use crate::ui::helpers::asset_label; use crate::ui::helpers::asset_label;
use crate::ui::theme::{panel_heading, ACCENT, BORDER, ELEVATED_BG, TEXT, TEXT_DIM, WIDGET_BG}; use crate::ui::theme::{
panel_heading, ACCENT, BORDER, ELEVATED_BG, ERROR, SUCCESS, TEXT, TEXT_DIM, WARNING, WIDGET_BG,
};
use crate::ui::widgets::{icon_button_small, tool_button}; use crate::ui::widgets::{icon_button_small, tool_button};
const FOOTER_HEIGHT: f32 = 64.0; const FOOTER_HEIGHT: f32 = 64.0;
@@ -375,6 +377,10 @@ fn embedded_assets_for_asset(world: &World, asset: &EditorAsset) -> Vec<Embedded
return Vec::new(); return Vec::new();
}; };
let mut embedded = Vec::new(); let mut embedded = Vec::new();
let use_source_materials = matches!(
record.import_settings.material_policy,
MaterialImportPolicy::SourceMaterials
);
let static_manifest = record let static_manifest = record
.import_settings .import_settings
.static_mesh_manifest_path .static_mesh_manifest_path
@@ -446,7 +452,11 @@ fn embedded_assets_for_asset(world: &World, asset: &EditorAsset) -> Vec<Embedded
}, },
label, label,
kind: AssetSubAssetKind::Material, kind: AssetSubAssetKind::Material,
detail: "Embedded source material".to_string(), detail: if use_source_materials {
"Embedded source material".to_string()
} else {
"Source material disabled by Authoring Override".to_string()
},
texture_path: None, texture_path: None,
thumbnail_key: subasset_thumbnail_key( thumbnail_key: subasset_thumbnail_key(
parent_path, parent_path,
@@ -1129,14 +1139,14 @@ fn draw_asset_grid_item(
let selection = &row.selection; let selection = &row.selection;
let asset = &row.asset; let asset = &row.asset;
let is_selected = selected.as_ref() == Some(selection); let is_selected = selected.as_ref() == Some(selection);
let failed = cache_snapshot.is_failed(asset); let failure = cache_snapshot.failure_reason(asset);
let has_children = has_embedded_assets(world, asset); let has_children = has_embedded_assets(world, asset);
let response = draw_asset_cell_with( let response = draw_asset_cell_with(
ui, ui,
asset, asset,
cache_snapshot.texture_for(asset), cache_snapshot.texture_for(asset),
cache_snapshot.is_pending(asset), cache_snapshot.is_pending(asset),
failed.then_some("failed"), failure,
is_selected, is_selected,
thumbnail_size, thumbnail_size,
); );
@@ -1190,7 +1200,7 @@ fn draw_asset_grid_item(
} }
} }
if failed && response.double_clicked() { if failure.is_some() && response.double_clicked() {
let key = crate::assets::asset_cache_key(asset); let key = crate::assets::asset_cache_key(asset);
world world
.resource_mut::<crate::assets::AssetThumbnailCache>() .resource_mut::<crate::assets::AssetThumbnailCache>()
@@ -1349,7 +1359,8 @@ fn draw_embedded_asset_cell(
.and_then(|path| thumbnail_for_path(world, cache_snapshot, path)) .and_then(|path| thumbnail_for_path(world, cache_snapshot, path))
}); });
let pending = cache_snapshot.is_pending_key(&embedded.thumbnail_key); let pending = cache_snapshot.is_pending_key(&embedded.thumbnail_key);
let failed = cache_snapshot.is_failed_key(&embedded.thumbnail_key); let failure = cache_snapshot.failure_reason_for_key(&embedded.thumbnail_key);
let failed = failure.is_some();
let thumb_size = thumbnail_size.clamp(44.0, 64.0); let thumb_size = thumbnail_size.clamp(44.0, 64.0);
let cell_size = egui::vec2(104.0, thumb_size + 50.0); let cell_size = egui::vec2(104.0, thumb_size + 50.0);
let (rect, response) = ui.allocate_exact_size(cell_size, egui::Sense::click_and_drag()); let (rect, response) = ui.allocate_exact_size(cell_size, egui::Sense::click_and_drag());
@@ -1360,6 +1371,11 @@ fn draw_embedded_asset_cell(
} else { } else {
response response
}; };
let response = if let Some(reason) = failure {
response.on_hover_text(reason)
} else {
response
};
let fill = if selected { let fill = if selected {
crate::ui::theme::SELECTION_BG_MUTED crate::ui::theme::SELECTION_BG_MUTED
} else if response.hovered() { } else if response.hovered() {
@@ -1883,9 +1899,53 @@ pub(crate) fn top_level_asset_details_panel(
} }
if !record.dependencies.is_empty() { if !record.dependencies.is_empty() {
ui.separator(); ui.separator();
ui.label(panel_heading("Dependencies")); let missing_count = record
.dependencies
.iter()
.filter(|dependency| !dependency_path(dependency).is_file())
.count();
ui.horizontal_wrapped(|ui| {
ui.label(panel_heading("Dependencies"));
if missing_count > 0 {
let optional = matches!(
record.import_settings.material_policy,
MaterialImportPolicy::AuthoringOverride
);
ui.small(
egui::RichText::new(if optional {
format!("{missing_count} missing | override")
} else {
format!("{missing_count} missing")
})
.color(if optional {
WARNING
} else {
ERROR
}),
);
}
});
for dep in &record.dependencies { for dep in &record.dependencies {
ui.add(egui::Label::new(dep).truncate()); let exists = dependency_path(dep).is_file();
ui.horizontal(|ui| {
ui.label(
egui::RichText::new(if exists {
icons::CHECK_CIRCLE.as_str()
} else {
icons::WARNING_CIRCLE.as_str()
})
.font(egui::FontId::new(
12.0,
egui::FontFamily::Name(PHOSPHOR.into()),
))
.color(if exists {
SUCCESS
} else {
WARNING
}),
);
ui.add(egui::Label::new(dep).truncate()).on_hover_text(dep);
});
} }
} }
} }
@@ -2032,12 +2092,12 @@ fn subasset_details_panel(
} }
} }
AssetSubAssetKind::Material => { AssetSubAssetKind::Material => {
ui.small( let status = if embedded.detail.contains("Authoring Override") {
egui::RichText::new( "Authoring Override is active; this source material is not assigned."
"Source materials are assigned through static mesh renderer slots.", } else {
) "Source material is assigned through static mesh renderer slots."
.color(TEXT_DIM), };
); ui.small(egui::RichText::new(status).color(TEXT_DIM));
} }
AssetSubAssetKind::Skeleton => { AssetSubAssetKind::Skeleton => {
ui.small( ui.small(
@@ -2072,6 +2132,15 @@ fn subasset_details_panel(
} }
} }
fn dependency_path(reference: &str) -> PathBuf {
let path = Path::new(reference);
if path.starts_with("assets") {
path.to_path_buf()
} else {
Path::new("assets").join(path)
}
}
fn asset_action_buttons( fn asset_action_buttons(
world: &mut World, world: &mut World,
ui: &mut egui::Ui, ui: &mut egui::Ui,
@@ -47,6 +47,11 @@ pub struct EditorComponentRegistry {
inspectors: HashMap<&'static str, ComponentInspectorFn>, inspectors: HashMap<&'static str, ComponentInspectorFn>,
} }
/// Synchronous inspector callbacks run while [`crate::ui::UiState`] is scoped out of `World`.
/// They must not request that resource. Keep extension-owned transient state in independently
/// registered resources, use [`crate::ui::request_ui_selection`] and
/// [`crate::ui::request_editor_tab`] for host UI changes, or defer other cross-panel work through
/// extension-owned commands or events.
pub type ComponentInspectorFn = fn(&mut World, &mut egui::Ui, Entity); pub type ComponentInspectorFn = fn(&mut World, &mut egui::Ui, Entity);
impl EditorComponentRegistry { impl EditorComponentRegistry {
+41 -17
View File
@@ -13,8 +13,6 @@ use crate::history::set_brush_with_history;
use crate::history::EditorHistory; use crate::history::EditorHistory;
use crate::project_io::ProjectWorkspace; use crate::project_io::ProjectWorkspace;
use crate::scene_io::{SceneIo, SceneIoEventSeverity}; use crate::scene_io::{SceneIo, SceneIoEventSeverity};
use crate::selection::SelectedEntity;
use crate::ui::UiState;
use crate::viewport::collider_diagnostics::{ use crate::viewport::collider_diagnostics::{
ColliderDiagnosticSeverity, ColliderDiagnosticsState, ColliderOverlayStatus, ColliderDiagnosticSeverity, ColliderDiagnosticsState, ColliderOverlayStatus,
}; };
@@ -123,11 +121,7 @@ pub fn diagnostics_ui(world: &mut World, ui: &mut egui::Ui) {
.iter(world) .iter(world)
.find_map(|(entity, id)| (id.0 == actor_id).then_some(entity)) .find_map(|(entity, id)| (id.0 == actor_id).then_some(entity))
{ {
world.resource_mut::<SelectedEntity>().0 = Some(entity); request_diagnostic_selection(world, entity);
world
.resource_mut::<UiState>()
.selected_entities
.select_replace(entity);
} }
} }
} }
@@ -250,11 +244,7 @@ fn collider_diagnostics_ui(world: &mut World, ui: &mut egui::Ui) {
ui.colored_label(color, row.shape_label); ui.colored_label(color, row.shape_label);
ui.label(&row.actor_name); ui.label(&row.actor_name);
if ui.small_button("Select").clicked() { if ui.small_button("Select").clicked() {
world.resource_mut::<SelectedEntity>().0 = Some(row.entity); request_diagnostic_selection(world, row.entity);
world
.resource_mut::<UiState>()
.selected_entities
.select_replace(row.entity);
} }
}); });
for diagnostic in &row.diagnostics { for diagnostic in &row.diagnostics {
@@ -304,11 +294,7 @@ fn brush_diagnostics_ui(world: &mut World, ui: &mut egui::Ui) {
ui.colored_label(color, row.status_label()); ui.colored_label(color, row.status_label());
ui.label(row.name.as_str()); ui.label(row.name.as_str());
if ui.button("Select").clicked() { if ui.button("Select").clicked() {
world.resource_mut::<SelectedEntity>().0 = Some(row.entity); request_diagnostic_selection(world, row.entity);
world
.resource_mut::<UiState>()
.selected_entities
.select_replace(row.entity);
} }
if ui if ui
.add_enabled(row.error_count > 0, egui::Button::new("Reset Cube")) .add_enabled(row.error_count > 0, egui::Button::new("Reset Cube"))
@@ -323,6 +309,10 @@ fn brush_diagnostics_ui(world: &mut World, ui: &mut egui::Ui) {
} }
} }
fn request_diagnostic_selection(world: &mut World, entity: Entity) {
crate::ui::request_ui_selection(world, &[entity]);
}
#[derive(Debug)] #[derive(Debug)]
struct BrushDiagnosticRow { struct BrushDiagnosticRow {
entity: Entity, entity: Entity,
@@ -397,3 +387,37 @@ pub fn diagnostics_window(world: &mut World, ctx: &egui::Context, open: &mut boo
diagnostics_ui(world, ui); diagnostics_ui(world, ui);
}); });
} }
#[cfg(test)]
mod tests {
use super::*;
use crate::selection::SelectedEntity;
use crate::ui::{PendingUiSelection, UiState};
#[test]
fn diagnostic_selection_reconciles_while_ui_state_is_scoped_out() {
let before = Entity::from_bits(1);
let requested = Entity::from_bits(2);
let mut world = World::new();
world.init_resource::<SelectedEntity>();
world.init_resource::<PendingUiSelection>();
world.resource_mut::<SelectedEntity>().0 = Some(before);
let mut ui_state = UiState::default_layout();
ui_state.selected_entities.select_replace(before);
world.insert_resource(ui_state);
world.resource_scope::<UiState, _>(|world, mut ui_state| {
assert!(!world.contains_resource::<UiState>());
request_diagnostic_selection(world, requested);
let pending = world.resource_mut::<PendingUiSelection>().0.take();
super::super::reconcile_operator_selection(
&mut ui_state.selected_entities,
&[before],
world.resource::<SelectedEntity>().0,
pending.as_deref(),
);
assert_eq!(ui_state.selected_entities.as_slice(), &[requested]);
});
}
}
+93 -42
View File
@@ -37,7 +37,6 @@ use crate::history::{
set_primitive_with_history, set_rigid_body_with_history, set_static_mesh_renderer_with_history, set_primitive_with_history, set_rigid_body_with_history, set_static_mesh_renderer_with_history,
EditorEntitySnapshot, EditorEntitySnapshot,
}; };
use crate::selection::SelectedEntity;
use crate::ui::theme::{ use crate::ui::theme::{
panel_heading, BORDER, ELEVATED_BG, PANEL_BG_DARK, SELECTION_BG_MUTED, TEXT_DIM, TEXT_MUTED, panel_heading, BORDER, ELEVATED_BG, PANEL_BG_DARK, SELECTION_BG_MUTED, TEXT_DIM, TEXT_MUTED,
WIDGET_BG, WIDGET_BG,
@@ -51,9 +50,8 @@ use crate::viewport::collider_diagnostics::{
use super::component_registry::{ use super::component_registry::{
EditorComponentCategory, EditorComponentDescriptor, EditorComponentRegistry, EditorComponentCategory, EditorComponentDescriptor, EditorComponentRegistry,
}; };
use super::dock_tabs::open_and_focus_tab;
use super::helpers::create_scene_sun_override_from_project_settings; use super::helpers::create_scene_sun_override_from_project_settings;
use super::{EditorTab, UiState}; use super::EditorTab;
use crate::assets::asset_db::{find_asset_by_path, AssetRegistry}; use crate::assets::asset_db::{find_asset_by_path, AssetRegistry};
use crate::assets::static_mesh::{ use crate::assets::static_mesh::{
load_static_mesh_manifest, material_id_from_label, part_id_from_label, load_static_mesh_manifest, material_id_from_label, part_id_from_label,
@@ -135,6 +133,7 @@ pub(crate) struct InspectorPanelState {
add_component_scroll_selected: bool, add_component_scroll_selected: bool,
add_component_selected_index: usize, add_component_selected_index: usize,
add_component_target: Option<Entity>, add_component_target: Option<Entity>,
collapsed_components: HashSet<String>,
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -276,13 +275,9 @@ pub(crate) fn component_card_context(
state_key, state_key,
); );
let collapsed = world let collapsed = world
.get_resource::<UiState>() .resource::<InspectorPanelState>()
.map(|state| { .collapsed_components
state .contains(&component_card_key(world, entity, options.type_name));
.inspector_collapsed_components
.contains(&component_card_key(world, entity, options.type_name))
})
.unwrap_or(false);
let pasteable = options.copyable let pasteable = options.copyable
&& world && world
.get_resource::<InspectorClipboard>() .get_resource::<InspectorClipboard>()
@@ -326,12 +321,11 @@ fn apply_component_card_response_for_type(
) { ) {
if let Some(collapsed) = response.collapsed { if let Some(collapsed) = response.collapsed {
let key = component_card_key(world, entity, type_name); let key = component_card_key(world, entity, type_name);
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() { let mut panel_state = world.resource_mut::<InspectorPanelState>();
if collapsed { if collapsed {
ui_state.inspector_collapsed_components.insert(key); panel_state.collapsed_components.insert(key);
} else { } else {
ui_state.inspector_collapsed_components.remove(&key); panel_state.collapsed_components.remove(&key);
}
} }
} }
@@ -2362,18 +2356,15 @@ fn locate_asset_ref(
return; return;
}; };
reveal_asset_in_browser(world, &candidate.folder_path, &candidate.selection);
}
fn reveal_asset_in_browser(world: &mut World, folder_path: &str, selection: &AssetSelection) {
if let Some(mut assets) = world.get_resource_mut::<EditorAssets>() { if let Some(mut assets) = world.get_resource_mut::<EditorAssets>() {
assets.current_folder = candidate.folder_path.clone(); assets.current_folder = folder_path.to_string();
assets.select(candidate.selection.clone()); assets.select(selection.clone());
}
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() {
let panel_nodes = ui_state.panel_nodes;
open_and_focus_tab(
&mut ui_state.dock_state,
EditorTab::AssetBrowser,
&panel_nodes,
);
} }
super::request_editor_tab(world, EditorTab::AssetBrowser);
} }
fn skinned_mesh_renderer_ui(world: &mut World, ui: &mut egui::Ui, entity: Entity) { fn skinned_mesh_renderer_ui(world: &mut World, ui: &mut egui::Ui, entity: Entity) {
@@ -4625,10 +4616,7 @@ pub fn project_sun_ui(world: &mut World, ui: &mut egui::Ui, entity: Entity) {
if create_override { if create_override {
let sun = create_scene_sun_override_from_project_settings(world); let sun = create_scene_sun_override_from_project_settings(world);
world.resource_mut::<SelectedEntity>().0 = Some(sun); crate::ui::request_ui_selection(world, &[sun]);
if let Some(mut ui_state) = world.get_resource_mut::<crate::ui::UiState>() {
ui_state.selected_entities.select_replace(sun);
}
} }
} }
@@ -4881,18 +4869,7 @@ fn locate_texture_asset(
return; return;
}; };
if let Some(mut assets) = world.get_resource_mut::<EditorAssets>() { reveal_asset_in_browser(world, &candidate.folder_path, &candidate.selection);
assets.current_folder = candidate.folder_path.clone();
assets.select(candidate.selection.clone());
}
if let Some(mut ui_state) = world.get_resource_mut::<UiState>() {
let panel_nodes = ui_state.panel_nodes;
open_and_focus_tab(
&mut ui_state.dock_state,
EditorTab::AssetBrowser,
&panel_nodes,
);
}
} }
fn option_string_ui(ui: &mut egui::Ui, label: &str, value: &mut Option<String>) -> bool { fn option_string_ui(ui: &mut egui::Ui, label: &str, value: &mut Option<String>) -> bool {
@@ -4924,6 +4901,80 @@ fn option_string_ui(ui: &mut egui::Ui, label: &str, value: &mut Option<String>)
mod collider_inspector_tests { mod collider_inspector_tests {
use super::*; use super::*;
use crate::history::{apply_command_undo, EditorHistory}; use crate::history::{apply_command_undo, EditorHistory};
use crate::ui::{DockTabRequest, UiState};
#[test]
fn component_collapse_persists_while_ui_state_is_scoped_out() {
let mut world = World::new();
world.init_resource::<EditorComponentRegistry>();
world.init_resource::<InspectorPanelState>();
let entity = world
.spawn((ActorId::new("collapsed-component"), Transform::IDENTITY))
.id();
world.insert_resource(UiState::default_layout());
world.resource_scope::<UiState, _>(|world, _ui_state| {
assert!(!world.contains_resource::<UiState>());
apply_component_card_response(
world,
entity,
ComponentCardResponse {
type_name: COMPONENT_TRANSFORM,
collapsed: Some(true),
..Default::default()
},
);
let context = component_card_context(
world,
entity,
ComponentCardOptions::fixed(COMPONENT_TRANSFORM, "Transform", icons::CUBE),
);
assert!(context.collapsed);
});
}
#[test]
fn locate_texture_requests_asset_browser_while_ui_state_is_scoped_out() {
let path = "assets/textures/scoped-locate.png";
let folder = "assets/textures";
let selection = AssetSelection::File(path.to_string());
let mut world = World::new();
world.insert_resource(EditorAssets {
folders: Vec::new(),
assets: vec![EditorAsset {
label: "Scoped Locate".into(),
path: Some(path.into()),
folder_path: folder.into(),
kind: EditorAssetKind::Texture,
}],
current_folder: crate::assets::ASSETS_ROOT.into(),
selected: None,
dragging: None,
status: String::new(),
});
world.init_resource::<DockTabRequest>();
world.insert_resource(UiState::default_layout());
let candidate = TextureAssetCandidate {
label: "Scoped Locate".into(),
path: path.into(),
folder_path: folder.into(),
selection: selection.clone(),
texture_id: None,
};
world.resource_scope::<UiState, _>(|world, _ui_state| {
assert!(!world.contains_resource::<UiState>());
locate_texture_asset(world, Some(path), &[candidate]);
});
let assets = world.resource::<EditorAssets>();
assert_eq!(assets.current_folder, folder);
assert_eq!(assets.selected.as_ref(), Some(&selection));
assert_eq!(
world.resource::<DockTabRequest>().0,
Some(EditorTab::AssetBrowser)
);
}
#[test] #[test]
fn shape_switch_preserves_dimensions_and_is_one_undoable_edit() { fn shape_switch_preserves_dimensions_and_is_one_undoable_edit() {
+88 -1
View File
@@ -6,8 +6,10 @@ use bevy_inspector_egui::bevy_inspector::hierarchy::SelectedEntities;
use egui_dock::DockState; use egui_dock::DockState;
use crate::history::{apply_command_redo, apply_command_undo, EditorHistory}; use crate::history::{apply_command_redo, apply_command_undo, EditorHistory};
use crate::project::samples::{SampleCatalog, SampleCatalogEntry};
use crate::scene_io::{SceneIo, SceneIoRequest}; use crate::scene_io::{SceneIo, SceneIoRequest};
use crate::settings_ui::{open_project_settings_panel, ProjectSettingsPanel}; use crate::settings_ui::{open_project_settings_panel, ProjectSettingsPanel};
use crate::shutdown::{request_editor_shutdown, ShutdownSource};
use crate::state::{EditorMode, PlayPaused}; use crate::state::{EditorMode, PlayPaused};
use super::diagnostics::{BrushDiagnosticsPanel, DiagnosticsPanel}; use super::diagnostics::{BrushDiagnosticsPanel, DiagnosticsPanel};
@@ -19,12 +21,26 @@ use super::layout::reset_and_save_layout;
use super::widgets::menu_item; use super::widgets::menu_item;
use super::EditorTab; use super::EditorTab;
#[derive(Debug, Clone, PartialEq, Eq)]
enum SampleMenuModel {
Available(Vec<SampleCatalogEntry>),
Unavailable(String),
}
fn sample_menu_model(catalog: &SampleCatalog) -> SampleMenuModel {
match catalog.unavailable_reason() {
Some(reason) => SampleMenuModel::Unavailable(reason.to_string()),
None => SampleMenuModel::Available(catalog.entries().to_vec()),
}
}
pub fn top_menu_bar( pub fn top_menu_bar(
world: &mut World, world: &mut World,
root_ui: &mut egui::Ui, root_ui: &mut egui::Ui,
selected: &SelectedEntities, selected: &SelectedEntities,
dock_state: &mut DockState<EditorTab>, dock_state: &mut DockState<EditorTab>,
panel_nodes: &mut PanelNodes, panel_nodes: &mut PanelNodes,
viewport_rect: egui::Rect,
) { ) {
egui::Panel::top("editor_menu_bar").show_inside(root_ui, |ui| { egui::Panel::top("editor_menu_bar").show_inside(root_ui, |ui| {
egui::MenuBar::new().ui(ui, |ui| { egui::MenuBar::new().ui(ui, |ui| {
@@ -37,6 +53,25 @@ pub fn top_menu_bar(
world.resource_mut::<SceneIo>().request = Some(SceneIoRequest::Open); world.resource_mut::<SceneIo>().request = Some(SceneIoRequest::Open);
ui.close(); ui.close();
} }
let sample_menu = sample_menu_model(world.resource::<SampleCatalog>());
ui.menu_button("Open Sample", |ui| match sample_menu {
SampleMenuModel::Available(entries) => {
for entry in entries {
if menu_item(ui, &entry.label, None, true)
.on_hover_text(entry.hover_text())
.clicked()
{
world.resource_mut::<SceneIo>().request =
Some(SceneIoRequest::OpenSample(entry.id));
ui.close();
}
}
}
SampleMenuModel::Unavailable(reason) => {
menu_item(ui, "Sample pack unavailable", None, false)
.on_disabled_hover_text(reason);
}
});
if menu_item(ui, "Save", Some("Ctrl+S"), true).clicked() { if menu_item(ui, "Save", Some("Ctrl+S"), true).clicked() {
world.resource_mut::<SceneIo>().request = Some(SceneIoRequest::Save); world.resource_mut::<SceneIo>().request = Some(SceneIoRequest::Save);
ui.close(); ui.close();
@@ -115,6 +150,11 @@ pub fn top_menu_bar(
} }
}); });
} }
ui.separator();
if menu_item(ui, "Quit", None, true).clicked() {
request_editor_shutdown(world, ShutdownSource::FileMenu);
ui.close();
}
}); });
ui.menu_button("Edit", |ui| { ui.menu_button("Edit", |ui| {
@@ -170,7 +210,7 @@ pub fn top_menu_bar(
("Create Link", NavigationActorType::Link), ("Create Link", NavigationActorType::Link),
] { ] {
if menu_item(ui, label, None, true).clicked() { if menu_item(ui, label, None, true).clicked() {
spawn_navigation_actor(world, actor_type); spawn_navigation_actor(world, actor_type, viewport_rect);
ui.close(); ui.close();
} }
} }
@@ -287,3 +327,50 @@ pub fn top_menu_bar(
}); });
}); });
} }
#[cfg(test)]
mod tests {
use std::path::PathBuf;
use super::*;
fn entry(id: &str, label: &str) -> SampleCatalogEntry {
SampleCatalogEntry {
id: id.into(),
label: label.into(),
scene_path: PathBuf::from(format!("assets/levels/samples/{id}.scn.ron")),
project_relative_scene: format!("assets/levels/samples/{id}.scn.ron"),
summary: format!("{label} summary"),
checks: vec![format!("{label} check")],
}
}
#[test]
fn sample_menu_preserves_catalog_order_and_hover_details() {
let catalog = SampleCatalog::available_entries(vec![
entry("material", "Material Lab"),
entry("terrain", "Terrain Sculpt"),
]);
let SampleMenuModel::Available(rows) = sample_menu_model(&catalog) else {
panic!("valid catalog must produce actionable menu rows");
};
assert_eq!(
rows.iter().map(|row| row.id.as_str()).collect::<Vec<_>>(),
vec!["material", "terrain"]
);
assert!(rows[0].hover_text().contains("Material Lab summary"));
assert!(rows[0].hover_text().contains("Material Lab check"));
}
#[test]
fn unavailable_catalog_produces_one_disabled_explanation() {
let catalog = SampleCatalog::default();
assert_eq!(
sample_menu_model(&catalog),
SampleMenuModel::Unavailable("Sample catalog is loading".into())
);
}
}
+131 -14
View File
@@ -26,8 +26,6 @@ mod toolbar;
mod viewport_chrome; mod viewport_chrome;
mod widgets; mod widgets;
use std::collections::HashSet;
use bevy::prelude::*; use bevy::prelude::*;
use bevy::window::{CursorGrabMode, CursorOptions, PrimaryWindow}; use bevy::window::{CursorGrabMode, CursorOptions, PrimaryWindow};
use bevy_egui::{egui, EguiContext, EguiPrimaryContextPass, PrimaryEguiContext}; use bevy_egui::{egui, EguiContext, EguiPrimaryContextPass, PrimaryEguiContext};
@@ -71,7 +69,6 @@ pub struct UiState {
pub selected_entities: SelectedEntities, pub selected_entities: SelectedEntities,
pub renaming_entity: Option<Entity>, pub renaming_entity: Option<Entity>,
pub rename_buffer: String, pub rename_buffer: String,
pub(crate) inspector_collapsed_components: HashSet<String>,
pub(crate) panel_nodes: PanelNodes, pub(crate) panel_nodes: PanelNodes,
last_mode_tab: Option<EditorMode>, last_mode_tab: Option<EditorMode>,
} }
@@ -79,6 +76,56 @@ pub struct UiState {
#[derive(Resource, Default)] #[derive(Resource, Default)]
struct DockTabRequest(Option<EditorTab>); struct DockTabRequest(Option<EditorTab>);
#[derive(Resource, Default, Debug)]
pub(crate) struct PendingUiSelection(pub(crate) Option<Vec<Entity>>);
fn replace_selected_entities(selected: &mut SelectedEntities, entities: &[Entity]) {
selected.clear();
for (index, entity) in entities.iter().enumerate() {
if index == 0 {
selected.select_replace(*entity);
} else {
selected.select_maybe_add(*entity, true);
}
}
}
/// Requests an editor selection change from synchronous UI or extension callbacks.
///
/// Returns `false` when the editor selection resources are not installed. A normally configured
/// editor provides them through [`crate::EditorPluginGroup`].
pub fn request_ui_selection(world: &mut World, entities: &[Entity]) -> bool {
{
let Some(mut selected) = world.get_resource_mut::<SelectedEntity>() else {
return false;
};
selected.0 = entities.first().copied();
}
if world.contains_resource::<UiState>() {
{
let mut ui_state = world.resource_mut::<UiState>();
replace_selected_entities(&mut ui_state.selected_entities, entities);
}
if let Some(mut pending) = world.get_resource_mut::<PendingUiSelection>() {
pending.0 = None;
}
} else if let Some(mut pending) = world.get_resource_mut::<PendingUiSelection>() {
pending.0 = Some(entities.to_vec());
}
true
}
/// Requests that an editor tab be opened and focused after the current synchronous UI pass.
///
/// Returns `false` when [`EditorUiPlugin`] is not installed.
pub fn request_editor_tab(world: &mut World, tab: EditorTab) -> bool {
let Some(mut request) = world.get_resource_mut::<DockTabRequest>() else {
return false;
};
request.0 = Some(tab);
true
}
pub fn egui_captures_keyboard(ctx: &egui::Context) -> bool { pub fn egui_captures_keyboard(ctx: &egui::Context) -> bool {
ctx.egui_wants_keyboard_input() ctx.egui_wants_keyboard_input()
} }
@@ -126,7 +173,6 @@ impl UiState {
selected_entities: SelectedEntities::default(), selected_entities: SelectedEntities::default(),
renaming_entity: None, renaming_entity: None,
rename_buffer: String::new(), rename_buffer: String::new(),
inspector_collapsed_components: HashSet::new(),
panel_nodes, panel_nodes,
last_mode_tab: None, last_mode_tab: None,
} }
@@ -138,7 +184,7 @@ impl UiState {
)] )]
fn ui(&mut self, world: &mut World, ctx: &mut egui::Context, dt: f32) { fn ui(&mut self, world: &mut World, ctx: &mut egui::Context, dt: f32) {
apply_editor_theme(ctx); apply_editor_theme(ctx);
let selected_before_ui = world.resource::<SelectedEntity>().0; let selected_before_ui: Vec<Entity> = self.selected_entities.iter().collect();
let mode = *world.resource::<State<EditorMode>>().get(); let mode = *world.resource::<State<EditorMode>>().get();
if self.last_mode_tab != Some(mode) { if self.last_mode_tab != Some(mode) {
@@ -169,9 +215,15 @@ impl UiState {
&self.selected_entities, &self.selected_entities,
&mut self.dock_state, &mut self.dock_state,
&mut self.panel_nodes, &mut self.panel_nodes,
self.viewport_rect,
); );
editor_toolbar_panel(world, root_ui, &mut self.selected_entities); editor_toolbar_panel(
world,
root_ui,
&mut self.selected_entities,
self.viewport_rect,
);
status_bar_ui(world, root_ui, &self.selected_entities, mode); status_bar_ui(world, root_ui, &self.selected_entities, mode);
let mut viewer = TabViewer { let mut viewer = TabViewer {
@@ -233,11 +285,13 @@ impl UiState {
world.resource_mut::<ViewportUiState>().shortcuts_open = true; world.resource_mut::<ViewportUiState>().shortcuts_open = true;
} }
let pending_selection = world.resource_mut::<PendingUiSelection>().0.take();
let requested_selection = world.resource::<SelectedEntity>().0; let requested_selection = world.resource::<SelectedEntity>().0;
reconcile_operator_selection( reconcile_operator_selection(
&mut self.selected_entities, &mut self.selected_entities,
selected_before_ui, &selected_before_ui,
requested_selection, requested_selection,
pending_selection.as_deref(),
); );
let selected = self.selected_entities.as_slice().first().copied(); let selected = self.selected_entities.as_slice().first().copied();
world.resource_mut::<SelectedEntity>().0 = selected; world.resource_mut::<SelectedEntity>().0 = selected;
@@ -246,16 +300,24 @@ impl UiState {
fn reconcile_operator_selection( fn reconcile_operator_selection(
selected_entities: &mut SelectedEntities, selected_entities: &mut SelectedEntities,
selected_before_ui: Option<Entity>, selected_before_ui: &[Entity],
requested_selection: Option<Entity>, requested_selection: Option<Entity>,
pending_selection: Option<&[Entity]>,
) { ) {
let selected_after_ui = selected_entities.as_slice().first().copied(); if selected_entities.as_slice() != selected_before_ui {
if requested_selection == selected_before_ui || selected_after_ui != selected_before_ui { return;
}
if let Some(entities) = pending_selection {
replace_selected_entities(selected_entities, entities);
return;
}
if requested_selection == selected_before_ui.first().copied() {
return; return;
} }
selected_entities.clear();
if let Some(entity) = requested_selection { if let Some(entity) = requested_selection {
selected_entities.select_replace(entity); replace_selected_entities(selected_entities, &[entity]);
} else {
selected_entities.clear();
} }
} }
@@ -310,6 +372,7 @@ impl Plugin for EditorUiPlugin {
.init_resource::<material_library::MaterialLibraryState>() .init_resource::<material_library::MaterialLibraryState>()
.init_resource::<material_library::MaterialLibraryCatalog>() .init_resource::<material_library::MaterialLibraryCatalog>()
.init_resource::<DockTabRequest>() .init_resource::<DockTabRequest>()
.init_resource::<PendingUiSelection>()
.init_resource::<inspector::InspectorClipboard>() .init_resource::<inspector::InspectorClipboard>()
.init_resource::<inspector::InspectorPanelState>() .init_resource::<inspector::InspectorPanelState>()
.init_resource::<animation_inspector::AnimationInspectorState>() .init_resource::<animation_inspector::AnimationInspectorState>()
@@ -476,7 +539,7 @@ mod tests {
let mut selected = SelectedEntities::default(); let mut selected = SelectedEntities::default();
selected.select_replace(before); selected.select_replace(before);
reconcile_operator_selection(&mut selected, Some(before), Some(spawned)); reconcile_operator_selection(&mut selected, &[before], Some(spawned), None);
assert_eq!(selected.as_slice(), &[spawned]); assert_eq!(selected.as_slice(), &[spawned]);
} }
@@ -489,8 +552,62 @@ mod tests {
let mut selected = SelectedEntities::default(); let mut selected = SelectedEntities::default();
selected.select_replace(clicked); selected.select_replace(clicked);
reconcile_operator_selection(&mut selected, Some(before), Some(requested)); reconcile_operator_selection(
&mut selected,
&[before],
Some(requested),
Some(&[requested, Entity::from_bits(4)]),
);
assert_eq!(selected.as_slice(), &[clicked]); assert_eq!(selected.as_slice(), &[clicked]);
} }
#[test]
fn direct_ui_secondary_selection_change_beats_pending_operator_selection() {
let a = Entity::from_bits(1);
let b = Entity::from_bits(2);
let c = Entity::from_bits(3);
let d = Entity::from_bits(4);
let e = Entity::from_bits(5);
let mut selected = SelectedEntities::default();
selected.select_replace(a);
selected.select_maybe_add(c, true);
reconcile_operator_selection(&mut selected, &[a, b], Some(d), Some(&[d, e]));
assert_eq!(selected.as_slice(), &[a, c]);
}
#[test]
fn menu_scope_multi_selection_request_preserves_all_entities() {
let before = Entity::from_bits(1);
let first_duplicate = Entity::from_bits(2);
let second_duplicate = Entity::from_bits(3);
let mut world = World::new();
world.init_resource::<SelectedEntity>();
world.init_resource::<PendingUiSelection>();
world.resource_mut::<SelectedEntity>().0 = Some(before);
let mut ui_state = UiState::default_layout();
ui_state.selected_entities.select_replace(before);
world.insert_resource(ui_state);
world.resource_scope::<UiState, _>(|world, mut ui_state| {
assert!(!world.contains_resource::<UiState>());
request_ui_selection(world, &[first_duplicate, second_duplicate]);
let pending = world.resource_mut::<PendingUiSelection>().0.take();
reconcile_operator_selection(
&mut ui_state.selected_entities,
&[before],
world.resource::<SelectedEntity>().0,
pending.as_deref(),
);
assert_eq!(
ui_state.selected_entities.as_slice(),
&[first_duplicate, second_duplicate]
);
});
}
} }
+50 -3
View File
@@ -858,10 +858,16 @@ pub enum NavigationActorType {
Link, Link,
} }
pub fn spawn_navigation_actor(world: &mut World, actor_type: NavigationActorType) -> Entity { pub fn spawn_navigation_actor(
let rect = world.resource::<crate::ui::UiState>().viewport_rect; world: &mut World,
actor_type: NavigationActorType,
viewport_rect: egui::Rect,
) -> Entity {
let settings = world.resource::<ViewportSettings>().clone(); let settings = world.resource::<ViewportSettings>().clone();
let translation = snap_translation(editor_spawn_ground_position(world, rect), &settings); let translation = snap_translation(
editor_spawn_ground_position(world, viewport_rect),
&settings,
);
let (name, bounds, obstacle, area, link) = match actor_type { let (name, bounds, obstacle, area, link) = match actor_type {
NavigationActorType::Bounds => ( NavigationActorType::Bounds => (
"Navigation Bounds", "Navigation Bounds",
@@ -1019,8 +1025,49 @@ pub fn sync_navigation_state(world: &mut World) {
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::*;
use crate::history::EditorHistory;
use crate::scene_io::SceneIo;
use crate::selection::SelectedEntity; use crate::selection::SelectedEntity;
use crate::ui::{PendingUiSelection, UiState};
use scene::navigation::NavigationGeometryInput; use scene::navigation::NavigationGeometryInput;
use shared::{ActorKind, LevelObject};
#[test]
fn navigation_spawn_works_while_ui_state_is_scoped_out_of_world() {
let mut world = World::new();
world.init_resource::<EditorHistory>();
world.init_resource::<SceneIo>();
world.init_resource::<SelectedEntity>();
world.init_resource::<PendingUiSelection>();
world.init_resource::<ViewportSettings>();
let mut ui_state = UiState::default_layout();
ui_state.viewport_rect =
egui::Rect::from_min_size(egui::pos2(100.0, 80.0), egui::vec2(1280.0, 720.0));
world.insert_resource(ui_state);
let entity = world.resource_scope::<UiState, _>(|world, mut ui_state| {
assert!(!world.contains_resource::<UiState>());
let entity =
spawn_navigation_actor(world, NavigationActorType::Bounds, ui_state.viewport_rect);
let pending = world.resource_mut::<PendingUiSelection>().0.take();
super::super::reconcile_operator_selection(
&mut ui_state.selected_entities,
&[],
world.resource::<SelectedEntity>().0,
pending.as_deref(),
);
assert_eq!(ui_state.selected_entities.as_slice(), &[entity]);
entity
});
assert!(world.contains_resource::<UiState>());
assert!(world.get::<LevelObject>(entity).is_some());
assert!(world.get::<NavigationBounds>(entity).is_some());
assert_eq!(world.get::<ActorKind>(entity), Some(&ActorKind::Navigation));
assert_eq!(world.resource::<SelectedEntity>().0, Some(entity));
assert_eq!(world.resource::<EditorHistory>().undo_depth(), 1);
}
#[test] #[test]
fn world_affine_uses_current_authored_parent_chain() { fn world_affine_uses_current_authored_parent_chain() {
+75 -15
View File
@@ -8,7 +8,6 @@ use egui_phosphor_icons::icons;
use crate::history::spawn_with_history; use crate::history::spawn_with_history;
use crate::scene_io::{SceneIo, SceneIoRequest}; use crate::scene_io::{SceneIo, SceneIoRequest};
use crate::state::{EditorMode, PlayPaused, PlayPossession}; use crate::state::{EditorMode, PlayPaused, PlayPossession};
use crate::ui::UiState;
use crate::viewport::brush_tool::start_draw_brush_tool; use crate::viewport::brush_tool::start_draw_brush_tool;
use crate::viewport::{editor_spawn_ground_position, snap_translation, ViewportSettings}; use crate::viewport::{editor_spawn_ground_position, snap_translation, ViewportSettings};
use shared::PrimitiveShape; use shared::PrimitiveShape;
@@ -30,15 +29,21 @@ pub fn editor_toolbar_panel(
world: &mut World, world: &mut World,
root_ui: &mut egui::Ui, root_ui: &mut egui::Ui,
selected: &mut SelectedEntities, selected: &mut SelectedEntities,
viewport_rect: egui::Rect,
) { ) {
egui::Panel::top("editor_toolbar") egui::Panel::top("editor_toolbar")
.exact_size(TOOLBAR_HEIGHT) .exact_size(TOOLBAR_HEIGHT)
.show_inside(root_ui, |ui| { .show_inside(root_ui, |ui| {
toolbar_ui(world, ui, selected); toolbar_ui(world, ui, selected, viewport_rect);
}); });
} }
pub fn toolbar_ui(world: &mut World, ui: &mut egui::Ui, selected: &mut SelectedEntities) { pub fn toolbar_ui(
world: &mut World,
ui: &mut egui::Ui,
selected: &mut SelectedEntities,
viewport_rect: egui::Rect,
) {
let (toolbar_rect, _) = ui.allocate_exact_size( let (toolbar_rect, _) = ui.allocate_exact_size(
egui::vec2(ui.available_width(), TOOLBAR_HEIGHT - 2.0), egui::vec2(ui.available_width(), TOOLBAR_HEIGHT - 2.0),
egui::Sense::hover(), egui::Sense::hover(),
@@ -65,7 +70,7 @@ pub fn toolbar_ui(world: &mut World, ui: &mut egui::Ui, selected: &mut SelectedE
.layout(egui::Layout::left_to_right(egui::Align::Center)), .layout(egui::Layout::left_to_right(egui::Align::Center)),
); );
left_ui.spacing_mut().item_spacing.x = 6.0; left_ui.spacing_mut().item_spacing.x = 6.0;
left_toolbar(world, &mut left_ui); left_toolbar(world, &mut left_ui, viewport_rect);
let mut transport_ui = ui.new_child( let mut transport_ui = ui.new_child(
egui::UiBuilder::new() egui::UiBuilder::new()
@@ -100,7 +105,7 @@ pub fn toolbar_ui(world: &mut World, ui: &mut egui::Ui, selected: &mut SelectedE
); );
} }
fn left_toolbar(world: &mut World, ui: &mut egui::Ui) { fn left_toolbar(world: &mut World, ui: &mut egui::Ui, viewport_rect: egui::Rect) {
brand_mark_frame().show(ui, |ui| { brand_mark_frame().show(ui, |ui| {
ui.set_min_width(118.0); ui.set_min_width(118.0);
ui.set_min_height(30.0); ui.set_min_height(30.0);
@@ -126,16 +131,16 @@ fn left_toolbar(world: &mut World, ui: &mut egui::Ui) {
toolbar_group_frame().show(ui, |ui| { toolbar_group_frame().show(ui, |ui| {
panel_toolbar_row(ui, |ui| { panel_toolbar_row(ui, |ui| {
if icon_button(ui, icons::CUBE, "Spawn cube").clicked() { if icon_button(ui, icons::CUBE, "Spawn cube").clicked() {
spawn_primitive_at_camera(world, PrimitiveShape::Box, "Cube"); spawn_primitive_at_camera(world, PrimitiveShape::Box, "Cube", viewport_rect);
} }
if icon_button(ui, icons::MOUNTAINS, "Spawn ramp").clicked() { if icon_button(ui, icons::MOUNTAINS, "Spawn ramp").clicked() {
spawn_primitive_at_camera(world, PrimitiveShape::Ramp, "Ramp"); spawn_primitive_at_camera(world, PrimitiveShape::Ramp, "Ramp", viewport_rect);
} }
if icon_button(ui, icons::SPHERE, "Spawn sphere").clicked() { if icon_button(ui, icons::SPHERE, "Spawn sphere").clicked() {
spawn_primitive_at_camera(world, PrimitiveShape::Sphere, "Sphere"); spawn_primitive_at_camera(world, PrimitiveShape::Sphere, "Sphere", viewport_rect);
} }
if icon_button(ui, icons::LIGHTBULB, "Spawn point light").clicked() { if icon_button(ui, icons::LIGHTBULB, "Spawn point light").clicked() {
let pos = camera_ground_spawn(world); let pos = camera_ground_spawn(world, viewport_rect);
spawn_with_history(world, light_snapshot("Point Light", pos)); spawn_with_history(world, light_snapshot("Point Light", pos));
} }
if icon_button(ui, icons::PENCIL_SIMPLE_LINE, "Draw brush (B)").clicked() { if icon_button(ui, icons::PENCIL_SIMPLE_LINE, "Draw brush (B)").clicked() {
@@ -157,6 +162,7 @@ fn left_toolbar(world: &mut World, ui: &mut egui::Ui) {
super::navigation_inspector::spawn_navigation_actor( super::navigation_inspector::spawn_navigation_actor(
world, world,
super::navigation_inspector::NavigationActorType::Bounds, super::navigation_inspector::NavigationActorType::Bounds,
viewport_rect,
); );
} }
} }
@@ -232,14 +238,68 @@ fn transport_controls(world: &mut World, ui: &mut egui::Ui) {
} }
} }
fn camera_ground_spawn(world: &mut World) -> Vec3 { fn camera_ground_spawn(world: &mut World, viewport_rect: egui::Rect) -> Vec3 {
let rect = world.resource::<UiState>().viewport_rect;
let settings = world.resource::<ViewportSettings>().clone(); let settings = world.resource::<ViewportSettings>().clone();
let pos = editor_spawn_ground_position(world, rect); let pos = editor_spawn_ground_position(world, viewport_rect);
snap_translation(pos, &settings) snap_translation(pos, &settings)
} }
fn spawn_primitive_at_camera(world: &mut World, shape: PrimitiveShape, name: &str) { fn spawn_primitive_at_camera(
let pos = camera_ground_spawn(world); world: &mut World,
spawn_with_history(world, primitive_snapshot(name, shape, pos)); shape: PrimitiveShape,
name: &str,
viewport_rect: egui::Rect,
) -> Entity {
let pos = camera_ground_spawn(world, viewport_rect);
spawn_with_history(world, primitive_snapshot(name, shape, pos))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::history::EditorHistory;
use crate::scene_io::SceneIo;
use crate::selection::SelectedEntity;
use crate::ui::{PendingUiSelection, UiState};
use shared::{LevelObject, Primitive};
#[test]
fn primitive_spawn_works_while_ui_state_is_scoped_out_of_world() {
let mut world = World::new();
world.init_resource::<EditorHistory>();
world.init_resource::<SceneIo>();
world.init_resource::<SelectedEntity>();
world.init_resource::<PendingUiSelection>();
world.init_resource::<ViewportSettings>();
let mut ui_state = UiState::default_layout();
ui_state.viewport_rect =
egui::Rect::from_min_size(egui::pos2(100.0, 80.0), egui::vec2(1280.0, 720.0));
world.insert_resource(ui_state);
let entity = world.resource_scope::<UiState, _>(|world, mut ui_state| {
assert!(!world.contains_resource::<UiState>());
let entity = spawn_primitive_at_camera(
world,
PrimitiveShape::Box,
"Cube",
ui_state.viewport_rect,
);
let pending = world.resource_mut::<PendingUiSelection>().0.take();
super::super::reconcile_operator_selection(
&mut ui_state.selected_entities,
&[],
world.resource::<SelectedEntity>().0,
pending.as_deref(),
);
assert_eq!(ui_state.selected_entities.as_slice(), &[entity]);
entity
});
assert!(world.contains_resource::<UiState>());
assert!(world.get::<LevelObject>(entity).is_some());
assert!(world.get::<Primitive>(entity).is_some());
assert_eq!(world.resource::<SelectedEntity>().0, Some(entity));
assert_eq!(world.resource::<EditorHistory>().undo_depth(), 1);
}
} }
-1
View File
@@ -1267,7 +1267,6 @@ mod tests {
format: "glb".into(), format: "glb".into(),
fingerprint: AnimationSourceFingerprint { fingerprint: AnimationSourceFingerprint {
byte_len: 1, byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(), content_hash: "fixture".into(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
+33 -7
View File
@@ -6,7 +6,7 @@ use bevy::app::PluginGroupBuilder;
use bevy::asset::AssetPlugin; use bevy::asset::AssetPlugin;
use bevy::log::{LogPlugin, DEFAULT_FILTER}; use bevy::log::{LogPlugin, DEFAULT_FILTER};
use bevy::prelude::*; use bevy::prelude::*;
use bevy::window::{CompositeAlphaMode, PresentMode, WindowMode, WindowPlugin}; use bevy::window::{CompositeAlphaMode, ExitCondition, PresentMode, WindowMode, WindowPlugin};
/// Runtime switch for the HDR camera pass. /// Runtime switch for the HDR camera pass.
/// ///
@@ -40,6 +40,27 @@ fn find_assets_directory(start: Option<PathBuf>) -> Option<String> {
} }
pub fn default_plugins(title: impl Into<String>) -> PluginGroupBuilder { pub fn default_plugins(title: impl Into<String>) -> PluginGroupBuilder {
configured_plugins(WindowPlugin {
primary_window: Some(primary_window(title)),
..default()
})
}
/// Default plugins for the editor, whose shutdown coordinator owns window-close handling.
pub fn editor_plugins(title: impl Into<String>) -> PluginGroupBuilder {
configured_plugins(editor_window_plugin(title))
}
fn editor_window_plugin(title: impl Into<String>) -> WindowPlugin {
WindowPlugin {
primary_window: Some(primary_window(title)),
exit_condition: ExitCondition::DontExit,
close_when_requested: false,
..default()
}
}
fn configured_plugins(window_plugin: WindowPlugin) -> PluginGroupBuilder {
DefaultPlugins DefaultPlugins
.set(LogPlugin { .set(LogPlugin {
// Blacksite intentionally replaces Bevy's `.scn.ron` loader with a // Blacksite intentionally replaces Bevy's `.scn.ron` loader with a
@@ -48,10 +69,7 @@ pub fn default_plugins(title: impl Into<String>) -> PluginGroupBuilder {
filter: format!("{DEFAULT_FILTER}bevy_asset::server::loaders=error"), filter: format!("{DEFAULT_FILTER}bevy_asset::server::loaders=error"),
..default() ..default()
}) })
.set(WindowPlugin { .set(window_plugin)
primary_window: Some(primary_window(title)),
..default()
})
.set(AssetPlugin { .set(AssetPlugin {
file_path: resolve_assets_directory(), file_path: resolve_assets_directory(),
..default() ..default()
@@ -86,8 +104,8 @@ pub fn hdr_enabled_from_env() -> bool {
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::{primary_window, resolve_assets_directory}; use super::{editor_window_plugin, primary_window, resolve_assets_directory};
use bevy::window::CompositeAlphaMode; use bevy::window::{CompositeAlphaMode, ExitCondition};
#[test] #[test]
fn primary_window_is_opaque() { fn primary_window_is_opaque() {
@@ -97,6 +115,14 @@ mod tests {
assert_eq!(window.composite_alpha_mode, CompositeAlphaMode::Opaque); assert_eq!(window.composite_alpha_mode, CompositeAlphaMode::Opaque);
} }
#[test]
fn editor_window_defers_close_and_exit_to_the_editor() {
let plugin = editor_window_plugin("test");
assert!(!plugin.close_when_requested);
assert!(matches!(plugin.exit_condition, ExitCondition::DontExit));
}
#[test] #[test]
fn resolve_assets_directory_finds_workspace_assets() { fn resolve_assets_directory_finds_workspace_assets() {
let cwd = std::env::current_dir().expect("cwd"); let cwd = std::env::current_dir().expect("cwd");
+1
View File
@@ -9,6 +9,7 @@ mod migrate;
pub mod navigation; pub mod navigation;
mod prefab; mod prefab;
mod project_validation; mod project_validation;
pub mod sample_pack;
mod upgrade; mod upgrade;
use std::path::Path; use std::path::Path;
+681 -37
View File
@@ -9,12 +9,13 @@ use shared::{
animation_clip_source_index, animation_clip_sub_asset_id, animation_skeleton_source_index, animation_clip_source_index, animation_clip_sub_asset_id, animation_skeleton_source_index,
animation_skeleton_sub_asset_id, animation_skeleton_sub_asset_id,
brush_math::{validate_brush, BrushDiagnosticSeverity}, brush_math::{validate_brush, BrushDiagnosticSeverity},
AnimationControllerDesc, AnimationDiagnosticSeverity, AnimationManifest, AudioListenerDesc, AnimationControllerDesc, AnimationDiagnosticSeverity, AnimationManifest,
AudioSourceDesc, BrushDesc, ColliderDesc, ColliderShapeDesc, EditorAssetRef, MaterialAsset, AssetSourceFingerprint, AudioListenerDesc, AudioSourceDesc, BrushDesc, ColliderDesc,
MaterialDesc, MaterialInstanceAsset, MaterialOverride, ModelRef, PostProcessEffectAsset, ColliderShapeDesc, EditorAssetRef, MaterialAsset, MaterialDesc, MaterialInstanceAsset,
PostProcessVolumeDesc, PrefabInstance, PrefabRef, RendererMaterialSet, ShaderSchemaAsset, MaterialOverride, ModelRef, PostProcessEffectAsset, PostProcessVolumeDesc, PrefabInstance,
SkinnedMeshRenderer, StaticMeshRenderer, ANIMATION_MANIFEST_SCHEMA_VERSION, PrefabRef, RendererMaterialSet, ShaderSchemaAsset, SkinnedMeshRenderer, StaticMeshRenderer,
AUDIO_CLIP_SUB_ASSET_ID, COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_SKINNED_MESH_RENDERER, TerrainDesc, ANIMATION_MANIFEST_SCHEMA_VERSION, AUDIO_CLIP_SUB_ASSET_ID,
COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_SKINNED_MESH_RENDERER,
NAVIGATION_GENERATED_ARTIFACT_DIRECTORY, NAVIGATION_GENERATED_ARTIFACT_DIRECTORY,
}; };
@@ -25,6 +26,7 @@ const MATERIAL_DESC: &str = "shared::components::MaterialDesc";
const MATERIAL_OVERRIDE: &str = "shared::components::MaterialOverride"; const MATERIAL_OVERRIDE: &str = "shared::components::MaterialOverride";
const STATIC_MESH_RENDERER: &str = "shared::components::StaticMeshRenderer"; const STATIC_MESH_RENDERER: &str = "shared::components::StaticMeshRenderer";
const BRUSH_DESC: &str = "shared::components::BrushDesc"; const BRUSH_DESC: &str = "shared::components::BrushDesc";
const TERRAIN_DESC: &str = "shared::components::TerrainDesc";
const COLLIDER_DESC: &str = "shared::components::ColliderDesc"; const COLLIDER_DESC: &str = "shared::components::ColliderDesc";
const POST_PROCESS_VOLUME: &str = "shared::components::PostProcessVolumeDesc"; const POST_PROCESS_VOLUME: &str = "shared::components::PostProcessVolumeDesc";
const PREFAB_INSTANCE: &str = "shared::components::PrefabInstance"; const PREFAB_INSTANCE: &str = "shared::components::PrefabInstance";
@@ -321,6 +323,8 @@ struct RegistryAssetRecord {
path: String, path: String,
kind_tag: String, kind_tag: String,
#[serde(default)] #[serde(default)]
source_fingerprint: Option<AssetSourceFingerprint>,
#[serde(default)]
import_settings: RegistryImportSettings, import_settings: RegistryImportSettings,
#[serde(default)] #[serde(default)]
dependencies: Vec<String>, dependencies: Vec<String>,
@@ -406,15 +410,19 @@ fn validate_asset_registry(
&format!("registry_{}", record.kind_tag.to_lowercase()), &format!("registry_{}", record.kind_tag.to_lowercase()),
&record.path, &record.path,
); );
for dependency in &record.dependencies { let generated_static_manifest_owns_dependencies = record.kind_tag == "Model"
add_reference( && record.import_settings.static_mesh_manifest_path.is_some();
project_root, if !generated_static_manifest_owns_dependencies {
report, for dependency in &record.dependencies {
&record.path, add_reference(
None, project_root,
"import_dependency", report,
dependency, &record.path,
); None,
"import_dependency",
dependency,
);
}
} }
if let Some(manifest) = record.import_settings.static_mesh_manifest_path.as_deref() { if let Some(manifest) = record.import_settings.static_mesh_manifest_path.as_deref() {
add_reference( add_reference(
@@ -481,10 +489,96 @@ fn validate_asset_registry(
repair: "Convert the clip to Ogg Vorbis, WAV, MP3, or FLAC and reimport it.".into(), repair: "Convert the clip to Ogg Vorbis, WAV, MP3, or FLAC and reimport it.".into(),
}); });
} }
if matches!(record.kind_tag.as_str(), "Model" | "Texture" | "AudioClip") {
validate_content_fingerprint(
project_root,
report,
"assets/.index/registry.ron",
&record.path,
record.source_fingerprint.as_ref(),
"registry.source_fingerprint_missing",
"registry.source_fingerprint_stale",
"registered imported source",
);
}
} }
animation_catalog animation_catalog
} }
#[allow(clippy::too_many_arguments)]
fn validate_content_fingerprint(
project_root: &Path,
report: &mut ProjectValidationReport,
owner_path: &str,
source_path: &str,
fingerprint: Option<&AssetSourceFingerprint>,
missing_code: &str,
stale_code: &str,
source_label: &str,
) {
let Some(fingerprint) = fingerprint.filter(|fingerprint| fingerprint.is_complete()) else {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: missing_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!("{source_label} has no complete BLAKE3 content fingerprint"),
repair: "Refresh the asset registry or reimport the source with this editor version."
.into(),
});
return;
};
let Some(path) = resolve_reference(project_root, source_path) else {
return;
};
let Ok(metadata) = std::fs::metadata(&path) else {
return;
};
if metadata.len() != fingerprint.byte_len {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!(
"{source_label} size changed from {} to {} bytes",
fingerprint.byte_len,
metadata.len()
),
repair: "Refresh or reimport the changed source before validation or packaging.".into(),
});
return;
}
match blake3_file_hash(&path) {
Ok(content_hash) if content_hash != fingerprint.content_hash => {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!(
"{source_label} content changed even though its byte length is unchanged"
),
repair: "Refresh or reimport the changed source before validation or packaging."
.into(),
});
}
Ok(_) => {}
Err(error) => report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!("could not hash {source_label}: {error}"),
repair: "Restore readable source content and rerun validation.".into(),
}),
}
}
fn reference_is_runtime_package_asset(reference: &str) -> bool { fn reference_is_runtime_package_asset(reference: &str) -> bool {
let relative = Path::new(reference.split('#').next().unwrap_or(reference)); let relative = Path::new(reference.split('#').next().unwrap_or(reference));
if relative.is_absolute() if relative.is_absolute()
@@ -701,6 +795,8 @@ struct StaticMeshManifestView {
asset_id: String, asset_id: String,
source: StaticMeshSourceView, source: StaticMeshSourceView,
#[serde(default)] #[serde(default)]
import: StaticMeshImportView,
#[serde(default)]
warnings: Vec<String>, warnings: Vec<String>,
} }
@@ -708,10 +804,27 @@ struct StaticMeshManifestView {
struct StaticMeshSourceView { struct StaticMeshSourceView {
path: String, path: String,
#[serde(default)] #[serde(default)]
format: String,
#[serde(default)]
fingerprint: AssetSourceFingerprint,
#[serde(default)]
dependencies: Vec<String>, dependencies: Vec<String>,
} }
const STATIC_MESH_MANIFEST_SCHEMA_VERSION: u32 = 3; #[derive(Default, Deserialize)]
struct StaticMeshImportView {
#[serde(default)]
material_policy: StaticMeshMaterialPolicyView,
}
#[derive(Default, Deserialize, PartialEq, Eq)]
enum StaticMeshMaterialPolicyView {
#[default]
SourceMaterials,
AuthoringOverride,
}
const STATIC_MESH_MANIFEST_SCHEMA_VERSION: u32 = 4;
fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValidationReport) { fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValidationReport) {
for path in ron_files( for path in ron_files(
@@ -753,16 +866,25 @@ fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValid
"model", "model",
&manifest.source.path, &manifest.source.path,
); );
for dependency in manifest.source.dependencies { validate_content_fingerprint(
add_reference( project_root,
project_root, report,
report, &source,
&source, &manifest.source.path,
None, Some(&manifest.source.fingerprint),
"import_dependency", "static_mesh.manifest_fingerprint_missing",
&dependency, "static_mesh.manifest_stale",
); "static mesh source",
} );
let optional_source_textures = manifest.source.format.eq_ignore_ascii_case("fbx")
&& manifest.import.material_policy == StaticMeshMaterialPolicyView::AuthoringOverride;
add_import_dependencies(
project_root,
report,
&source,
&manifest.source.dependencies,
optional_source_textures,
);
for warning in manifest.warnings { for warning in manifest.warnings {
report.findings.push(ProjectValidationFinding { report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Warning, severity: ValidationSeverity::Warning,
@@ -779,6 +901,79 @@ fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValid
} }
} }
fn add_import_dependencies(
project_root: &Path,
report: &mut ProjectValidationReport,
owner_path: &str,
dependencies: &[String],
optional_source_textures: bool,
) {
let mut missing = Vec::new();
for dependency in dependencies {
match resolve_reference(project_root, dependency) {
Some(path) if path.is_file() => add_reference(
project_root,
report,
owner_path,
None,
"import_dependency",
dependency,
),
Some(_) => {
report.dependencies.push(ProjectDependency {
owner_path: owner_path.to_string(),
owner_actor_id: None,
kind: "import_dependency".into(),
reference: dependency.clone(),
});
missing.push(dependency.clone());
}
None => add_reference(
project_root,
report,
owner_path,
None,
"import_dependency",
dependency,
),
}
}
if missing.is_empty() {
return;
}
missing.sort();
missing.dedup();
report.findings.push(ProjectValidationFinding {
severity: if optional_source_textures {
ValidationSeverity::Info
} else {
ValidationSeverity::Error
},
code: "import.external_texture_missing".into(),
source_path: owner_path.to_string(),
owner_actor_id: None,
reference: Some(missing.join(", ")),
message: if optional_source_textures {
format!(
"{} FBX source texture(s) are unavailable and intentionally ignored by Authoring Override",
missing.len()
)
} else {
format!(
"{} required imported texture dependency file(s) do not exist",
missing.len()
)
},
repair: if optional_source_textures {
"No action is required while Authoring Override remains active; restore the texture bundle before selecting Source Materials."
.into()
} else {
"Restore the referenced texture bundle and reimport, or select Authoring Override for a deliberately untextured asset."
.into()
},
});
}
fn validate_animation_manifests( fn validate_animation_manifests(
project_root: &Path, project_root: &Path,
report: &mut ProjectValidationReport, report: &mut ProjectValidationReport,
@@ -974,12 +1169,7 @@ fn validate_animation_manifest_contract(
} }
let fingerprint = &manifest.source.fingerprint; let fingerprint = &manifest.source.fingerprint;
let hash_is_present = fingerprint.content_hash.len() == 64 if fingerprint.byte_len == 0 || !fingerprint.is_complete() {
&& fingerprint
.content_hash
.bytes()
.all(|byte| byte.is_ascii_hexdigit());
if fingerprint.byte_len == 0 || fingerprint.modified_unix_secs == 0 || !hash_is_present {
report.findings.push(ProjectValidationFinding { report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error, severity: ValidationSeverity::Error,
code: "animation.manifest_fingerprint_missing".into(), code: "animation.manifest_fingerprint_missing".into(),
@@ -1905,6 +2095,53 @@ fn collect_component_references(
} }
} }
} }
TERRAIN_DESC => match ron::from_str::<TerrainDesc>(&component.ron) {
Ok(terrain) => {
if let Err(error) = terrain.validate() {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "terrain.invalid".into(),
source_path: source_path.to_string(),
owner_actor_id: actor_id.map(str::to_string),
reference: None,
message: error,
repair: "Repair the terrain dimensions, samples, layers, and chunk settings in the Inspector."
.into(),
});
}
if let Some(material) = &terrain.base_material {
collect_terrain_material_ref(
project_root,
report,
source_path,
actor_id,
"TerrainDesc.base_material",
material,
);
}
for (index, layer) in terrain.material_layers.iter().enumerate() {
if let Some(material) = &layer.material {
collect_terrain_material_ref(
project_root,
report,
source_path,
actor_id,
&format!("TerrainDesc.material_layers[{index}].material"),
material,
);
}
}
}
Err(error) => report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "terrain.malformed".into(),
source_path: source_path.to_string(),
owner_actor_id: actor_id.map(str::to_string),
reference: None,
message: format!("could not parse TerrainDesc: {error}"),
repair: "Remove and recreate the Terrain component with the current editor.".into(),
}),
},
COLLIDER_DESC => validate_collider( COLLIDER_DESC => validate_collider(
project_root, project_root,
report, report,
@@ -2736,6 +2973,64 @@ fn collect_material(
} }
} }
fn collect_terrain_material_ref(
project_root: &Path,
report: &mut ProjectValidationReport,
source_path: &str,
actor_id: Option<&str>,
property: &str,
reference: &EditorAssetRef,
) {
let Some(path) = reference
.source_path
.as_deref()
.filter(|path| !path.trim().is_empty())
else {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "terrain.material_ref_unresolved".into(),
source_path: source_path.to_string(),
owner_actor_id: actor_id.map(str::to_string),
reference: Some(property.to_string()),
message: format!("{property} has no loadable project source path"),
repair:
"Assign an existing project Material or Material Instance in the Terrain inspector."
.into(),
});
return;
};
let path_value = Path::new(path);
if path_value.is_absolute()
|| path_value == Path::new("assets")
|| !path_value.starts_with("assets")
|| !path_value
.components()
.all(|component| matches!(component, Component::Normal(_)))
{
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "terrain.material_ref_invalid".into(),
source_path: source_path.to_string(),
owner_actor_id: actor_id.map(str::to_string),
reference: Some(path.to_string()),
message: format!(
"{property} source path must be a normalized project-relative path below assets/"
),
repair: "Reassign the terrain layer from a project Material or Material Instance."
.into(),
});
return;
}
add_reference(
project_root,
report,
source_path,
actor_id,
"terrain_material",
path,
);
}
fn collect_asset_ref( fn collect_asset_ref(
project_root: &Path, project_root: &Path,
report: &mut ProjectValidationReport, report: &mut ProjectValidationReport,
@@ -2965,7 +3260,7 @@ mod tests {
} }
#[test] #[test]
fn static_mesh_manifest_schema_v3_is_current() { fn static_mesh_manifest_schema_v4_is_current() {
let root = fixture_root(); let root = fixture_root();
let source_path = "assets/models/static.glb"; let source_path = "assets/models/static.glb";
std::fs::create_dir_all(root.join("assets/models")).unwrap(); std::fs::create_dir_all(root.join("assets/models")).unwrap();
@@ -2975,7 +3270,8 @@ mod tests {
std::fs::write( std::fs::write(
artifact_dir.join("static-id.static_mesh.ron"), artifact_dir.join("static-id.static_mesh.ron"),
format!( format!(
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",dependencies:[]),warnings:[])" "(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",fingerprint:(byte_len:5,content_hash:\"{}\"),dependencies:[]),warnings:[])",
blake3::hash(b"model").to_hex()
), ),
) )
.unwrap(); .unwrap();
@@ -2989,6 +3285,182 @@ mod tests {
std::fs::remove_dir_all(root).unwrap(); std::fs::remove_dir_all(root).unwrap();
} }
fn write_fbx_dependency_fixture(
root: &Path,
material_policy: &str,
dependencies: &[&str],
) -> PathBuf {
let source_path = "assets/models/chair.fbx";
std::fs::create_dir_all(root.join("assets/models")).unwrap();
std::fs::write(root.join(source_path), b"model").unwrap();
std::fs::write(
root.join("assets/levels/main.scn.ron"),
"(schema_version:4,resources:{},entities:{})",
)
.unwrap();
let artifact = root.join("assets/meshes/generated/chair.static_mesh.ron");
std::fs::create_dir_all(artifact.parent().unwrap()).unwrap();
let dependencies = dependencies
.iter()
.map(|path| format!("{path:?}"))
.collect::<Vec<_>>()
.join(",");
std::fs::write(
&artifact,
format!(
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"chair\",source:(path:\"{source_path}\",format:\"fbx\",fingerprint:(byte_len:5,content_hash:\"{}\"),dependencies:[{dependencies}]),import:(material_policy:{material_policy}),warnings:[])\n",
blake3::hash(b"model").to_hex()
),
)
.unwrap();
artifact
}
#[test]
fn source_materials_consolidate_missing_fbx_textures_as_one_blocker() {
let root = fixture_root();
write_fbx_dependency_fixture(
&root,
"SourceMaterials",
&[
"assets/models/textures/chair_diff.jpg",
"assets/models/textures/chair_normal.exr",
"assets/models/textures/chair_rough.exr",
],
);
let report = validate_project(&root);
let findings = report
.findings
.iter()
.filter(|finding| finding.code == "import.external_texture_missing")
.collect::<Vec<_>>();
assert_eq!(findings.len(), 1, "{:?}", report.findings);
assert_eq!(findings[0].severity, ValidationSeverity::Error);
assert!(findings[0].message.starts_with("3 required"));
assert_eq!(
report
.dependencies
.iter()
.filter(|dependency| dependency.kind == "import_dependency")
.count(),
3
);
assert!(!report.is_release_ready());
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn authoring_override_reports_missing_fbx_textures_without_blocking_or_writing() {
let root = fixture_root();
let artifact = write_fbx_dependency_fixture(
&root,
"AuthoringOverride",
&[
"assets/models/textures/chair_diff.jpg",
"assets/models/textures/chair_normal.exr",
"assets/models/textures/chair_rough.exr",
],
);
let before = std::fs::read(&artifact).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "import.external_texture_missing")
.expect("Authoring Override should retain one actionable dependency state");
assert_eq!(finding.severity, ValidationSeverity::Info);
assert!(finding.message.contains("Authoring Override"));
assert!(report.is_release_ready(), "{:?}", report.findings);
assert_eq!(std::fs::read(&artifact).unwrap(), before);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn authoring_override_does_not_downgrade_unsafe_fbx_texture_paths() {
let root = fixture_root();
write_fbx_dependency_fixture(
&root,
"AuthoringOverride",
&["assets/models/../outside/chair.jpg"],
);
let report = validate_project(&root);
assert!(report.findings.iter().any(|finding| {
finding.code == "asset.unsafe_path" && finding.severity == ValidationSeverity::Error
}));
assert!(!report.is_release_ready());
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn same_size_static_mesh_source_change_invalidates_content_hash() {
let root = fixture_root();
let source_path = "assets/models/static.glb";
std::fs::create_dir_all(root.join("assets/models")).unwrap();
std::fs::write(root.join(source_path), b"model").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
let artifact = root.join("assets/meshes/generated/static-id.static_mesh.ron");
std::fs::create_dir_all(artifact.parent().unwrap()).unwrap();
std::fs::write(
&artifact,
format!(
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",fingerprint:(byte_len:{},content_hash:\"{}\"),dependencies:[]),warnings:[])",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
std::fs::write(root.join(source_path), b"modem").unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "static_mesh.manifest_stale")
.expect("same-size model edit must stale the static mesh manifest");
assert!(finding.message.contains("byte length is unchanged"));
assert!(finding.repair.contains("Refresh") || finding.repair.contains("reimport"));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn registry_detects_same_size_changes_for_all_imported_source_kinds() {
for (kind, relative) in [
("Model", "assets/models/source.glb"),
("Texture", "assets/textures/source.png"),
("AudioClip", "assets/audio/source.ogg"),
] {
let root = fixture_root();
let path = root.join(relative);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, b"source-a").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"source-a");
std::fs::write(
root.join("assets/.index/registry.ron"),
format!(
"[(id:(\"00000000-0000-0000-0000-000000000001\"),path:\"{relative}\",kind_tag:\"{kind}\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
std::fs::write(&path, b"source-b").unwrap();
let report = validate_project(&root);
assert!(report.findings.iter().any(|finding| {
finding.code == "registry.source_fingerprint_stale"
&& finding.reference.as_deref() == Some(relative)
&& finding.message.contains("byte length is unchanged")
}));
std::fs::remove_dir_all(root).unwrap();
}
}
fn write_manifest(root: &Path, version: u32) { fn write_manifest(root: &Path, version: u32) {
std::fs::write( std::fs::write(
root.join("assets/project.ron"), root.join("assets/project.ron"),
@@ -3022,7 +3494,6 @@ mod tests {
format: source_format.into(), format: source_format.into(),
fingerprint: AnimationSourceFingerprint { fingerprint: AnimationSourceFingerprint {
byte_len: 5, byte_len: 5,
modified_unix_secs: 1,
content_hash: blake3::hash(b"model").to_hex().to_string(), content_hash: blake3::hash(b"model").to_hex().to_string(),
}, },
dependencies: Vec::new(), dependencies: Vec::new(),
@@ -3082,10 +3553,12 @@ mod tests {
let manifest = animation_manifest_path let manifest = animation_manifest_path
.map(|path| format!("Some({path:?})")) .map(|path| format!("Some({path:?})"))
.unwrap_or_else(|| "None".into()); .unwrap_or_else(|| "None".into());
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
std::fs::write( std::fs::write(
root.join("assets/.index/registry.ron"), root.join("assets/.index/registry.ron"),
format!( format!(
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",import_settings:(static_mesh_manifest_path:None,animation_manifest_path:{manifest}),dependencies:[])]" "[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),import_settings:(static_mesh_manifest_path:None,animation_manifest_path:{manifest}),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
), ),
) )
.unwrap(); .unwrap();
@@ -3099,10 +3572,12 @@ mod tests {
let source = root.join(source_path); let source = root.join(source_path);
std::fs::create_dir_all(source.parent().unwrap()).unwrap(); std::fs::create_dir_all(source.parent().unwrap()).unwrap();
std::fs::write(source, b"model").unwrap(); std::fs::write(source, b"model").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
std::fs::write( std::fs::write(
root.join("assets/.index/registry.ron"), root.join("assets/.index/registry.ron"),
format!( format!(
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",import_settings:(static_mesh_manifest_path:None,animation_manifest_path:Some(\"{ANIMATION_MANIFEST_PATH}\"),default_animation_clip_id:Some(\"{default_clip_id}\")),dependencies:[])]" "[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),import_settings:(static_mesh_manifest_path:None,animation_manifest_path:Some(\"{ANIMATION_MANIFEST_PATH}\"),default_animation_clip_id:Some(\"{default_clip_id}\")),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
), ),
) )
.unwrap(); .unwrap();
@@ -3526,6 +4001,49 @@ mod tests {
std::fs::remove_dir_all(root).unwrap(); std::fs::remove_dir_all(root).unwrap();
} }
#[test]
fn project_validation_preserves_registry_and_generated_artifact_bytes() {
let root = fixture_root();
let source_path = "assets/models/hero.glb";
let manifest = animation_fixture_manifest(source_path, "glb", "rig-signature", true);
write_animation_source_and_registry(&root, source_path, Some(ANIMATION_MANIFEST_PATH));
write_animation_manifest(&root, &manifest);
write_animation_scene(&root, &animation_fixture_controller(&manifest));
let static_path = root.join("assets/meshes/generated/model-id.static_mesh.ron");
std::fs::create_dir_all(static_path.parent().unwrap()).unwrap();
std::fs::write(
&static_path,
format!(
"( schema_version: {STATIC_MESH_MANIFEST_SCHEMA_VERSION}, asset_id: \"model-id\", source: ( path: \"{source_path}\", fingerprint: ( byte_len: {}, content_hash: \"{}\", ), dependencies: [], ), warnings: [], )\n\n",
manifest.source.fingerprint.byte_len,
manifest.source.fingerprint.content_hash
),
)
.unwrap();
let paths = [
root.join("assets/.index/registry.ron"),
root.join(ANIMATION_MANIFEST_PATH),
static_path,
];
let before = paths
.iter()
.map(std::fs::read)
.collect::<Result<Vec<_>, _>>()
.unwrap();
let _ = validate_project(&root);
let _ = validate_project(&root);
let after = paths
.iter()
.map(std::fs::read)
.collect::<Result<Vec<_>, _>>()
.unwrap();
assert_eq!(after, before);
std::fs::remove_dir_all(root).unwrap();
}
#[test] #[test]
fn missing_animation_manifest_is_reported_globally_and_on_the_actor_property() { fn missing_animation_manifest_is_reported_globally_and_on_the_actor_property() {
let root = fixture_root(); let root = fixture_root();
@@ -3888,6 +4406,132 @@ mod tests {
std::fs::remove_dir_all(root).unwrap(); std::fs::remove_dir_all(root).unwrap();
} }
fn write_terrain_scene(root: &Path, terrain: &TerrainDesc) {
let terrain = ron::to_string(terrain).unwrap();
std::fs::write(
root.join("assets/levels/main.scn.ron"),
format!(
"(schema_version:4,resources:{{}},entities:{{1:(components:{{\"shared::components::ActorId\":(\"terrain-owner\"),\"{TERRAIN_DESC}\":{terrain},}})}})"
),
)
.unwrap();
}
#[test]
fn terrain_material_references_are_actor_owned_dependencies() {
let root = fixture_root();
let mut terrain = TerrainDesc::flat(3);
terrain.base_material = Some(
EditorAssetRef::new("base-id", "material:instance", "Base")
.with_source_path("assets/materials/base.ron"),
);
terrain.material_layers = vec![shared::TerrainMaterialLayer {
material: Some(
EditorAssetRef::new("layer-id", "material:source", "Layer")
.with_source_path("assets/materials/layer.ron"),
),
uv_scale: 4.0,
}];
write_terrain_scene(&root, &terrain);
let report = validate_project(&root);
let dependencies = report
.dependencies
.iter()
.filter(|dependency| dependency.kind == "terrain_material")
.collect::<Vec<_>>();
assert_eq!(dependencies.len(), 2, "{:?}", report.dependencies);
assert!(dependencies
.iter()
.all(|dependency| dependency.owner_actor_id.as_deref() == Some("terrain-owner")));
assert_eq!(
report
.findings
.iter()
.filter(|finding| finding.code == "asset.missing")
.count(),
2
);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn terrain_material_references_require_runtime_source_paths() {
let root = fixture_root();
let mut terrain = TerrainDesc::flat(3);
terrain.base_material = Some(
EditorAssetRef::new("empty-path-id", "material:source", "Empty")
.with_source_path(" "),
);
terrain.material_layers = vec![
shared::TerrainMaterialLayer {
material: Some(EditorAssetRef::new(
"source-less-id",
"material:source",
"Source-less",
)),
uv_scale: 4.0,
},
shared::TerrainMaterialLayer {
material: Some(
EditorAssetRef::new("missing-id", "material:source", "Missing")
.with_source_path("assets/materials/missing.ron"),
),
uv_scale: 8.0,
},
];
write_terrain_scene(&root, &terrain);
let report = validate_project(&root);
let unresolved = report
.findings
.iter()
.filter(|finding| finding.code == "terrain.material_ref_unresolved")
.collect::<Vec<_>>();
assert_eq!(unresolved.len(), 2, "{:?}", report.findings);
assert!(unresolved
.iter()
.all(|finding| finding.owner_actor_id.as_deref() == Some("terrain-owner")));
assert!(report.findings.iter().any(|finding| {
finding.code == "asset.missing"
&& finding.owner_actor_id.as_deref() == Some("terrain-owner")
&& finding.reference.as_deref() == Some("assets/materials/missing.ron")
}));
assert!(report.dependencies.iter().any(|dependency| {
dependency.kind == "terrain_material"
&& dependency.reference == "assets/materials/missing.ron"
}));
assert!(!report.dependencies.iter().any(|dependency| {
dependency.kind == "generated_manifest"
&& (dependency.reference.contains("empty-path-id")
|| dependency.reference.contains("source-less-id"))
}));
assert!(!report.is_release_ready());
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn invalid_terrain_descriptor_blocks_project_validation() {
let root = fixture_root();
let mut terrain = TerrainDesc::flat(3);
terrain.heights.pop();
write_terrain_scene(&root, &terrain);
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "terrain.invalid")
.expect("invalid terrain should block release validation");
assert_eq!(finding.owner_actor_id.as_deref(), Some("terrain-owner"));
assert!(finding.message.contains("requires 9 height samples"));
assert!(!report.is_release_ready());
std::fs::remove_dir_all(root).unwrap();
}
#[test] #[test]
fn project_default_level_must_be_in_the_audited_levels_tree() { fn project_default_level_must_be_in_the_audited_levels_tree() {
let root = fixture_root(); let root = fixture_root();
File diff suppressed because it is too large. Load diff
+2 -7
View File
@@ -266,13 +266,8 @@ pub struct AnimationManifestSource {
pub dependencies: Vec<String>, pub dependencies: Vec<String>,
} }
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] /// Backward-compatible name for the shared imported-source fingerprint contract.
pub struct AnimationSourceFingerprint { pub type AnimationSourceFingerprint = crate::AssetSourceFingerprint;
pub byte_len: u64,
pub modified_unix_secs: u64,
/// BLAKE3 hash of the source file bytes.
pub content_hash: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AnimationSkeletonRecord { pub struct AnimationSkeletonRecord {
+50
View File
@@ -0,0 +1,50 @@
use serde::{Deserialize, Serialize};
/// Stable identity for the exact bytes of an imported project source.
///
/// Filesystem timestamps are deliberately excluded: Git and LFS do not preserve checkout mtimes,
/// so they cannot participate in a portable authored-data contract.
#[derive(Debug, Clone, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct AssetSourceFingerprint {
pub byte_len: u64,
#[serde(default)]
pub content_hash: String,
}
impl AssetSourceFingerprint {
pub fn from_bytes(bytes: &[u8]) -> Self {
Self {
byte_len: bytes.len() as u64,
content_hash: blake3::hash(bytes).to_hex().to_string(),
}
}
pub fn is_complete(&self) -> bool {
self.content_hash.len() == 64
&& self
.content_hash
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn exact_bytes_define_source_identity() {
let first = AssetSourceFingerprint::from_bytes(b"asset-a");
let same = AssetSourceFingerprint::from_bytes(b"asset-a");
let same_size_change = AssetSourceFingerprint::from_bytes(b"asset-b");
assert_eq!(first, same);
assert_ne!(first, same_size_change);
assert_eq!(first.byte_len, same_size_change.byte_len);
assert!(first.is_complete());
let mut noncanonical = first;
noncanonical.content_hash.make_ascii_uppercase();
assert!(!noncanonical.is_complete());
}
}
+8 -30
View File
@@ -40,16 +40,17 @@ use static_meshes::{
}; };
pub use terrain::HydratedTerrainChunk; pub use terrain::HydratedTerrainChunk;
use terrain::{cleanup_removed_terrain, hydrate_terrain}; use terrain::{cleanup_removed_terrain, hydrate_terrain};
pub use visibility::initialize_level_object_visibility_hierarchy;
use visibility::{ use visibility::{
ensure_level_object_visibility_hierarchy, init_editor_visibility_on_spawn, ensure_level_object_visibility_hierarchy, init_editor_visibility_on_spawn,
sync_editor_visibility, visibility_from_editor, sync_editor_visibility,
}; };
use crate::{ use crate::{
authoring_component_active, AuthoringComponentStates, BrushDesc, ColliderDesc, authoring_component_active, AuthoringComponentStates, BrushDesc, ColliderDesc, InspectorOrder,
EditorVisibility, InspectorOrder, LevelObject, MaterialDesc, MaterialOverride, Primitive, LevelObject, MaterialDesc, MaterialOverride, Primitive, StaticMeshRenderer,
StaticMeshRenderer, COMPONENT_BRUSH_DESC, COMPONENT_COLLIDER_DESC, COMPONENT_LIGHT_DESC, COMPONENT_BRUSH_DESC, COMPONENT_COLLIDER_DESC, COMPONENT_LIGHT_DESC, COMPONENT_MATERIAL_DESC,
COMPONENT_MATERIAL_DESC, COMPONENT_PRIMITIVE, COMPONENT_STATIC_MESH_RENDERER, COMPONENT_PRIMITIVE, COMPONENT_STATIC_MESH_RENDERER,
}; };
/// Registers hydration systems in deterministic order. /// Registers hydration systems in deterministic order.
@@ -115,6 +116,8 @@ pub fn flush_level_object_hydration(world: &mut World) {
world.insert_resource(StaticMeshArtifactCache::default()); world.insert_resource(StaticMeshArtifactCache::default());
} }
initialize_level_object_visibility_hierarchy(world);
let primitives: Vec<(Entity, Primitive)> = world let primitives: Vec<(Entity, Primitive)> = world
.query_filtered::<( .query_filtered::<(
Entity, Entity,
@@ -250,12 +253,6 @@ pub fn flush_level_object_hydration(world: &mut World) {
} }
} }
let visibility_targets: Vec<(Entity, EditorVisibility)> = world
.query_filtered::<(Entity, &EditorVisibility), With<LevelObject>>()
.iter(world)
.map(|(entity, vis)| (entity, *vis))
.collect();
let rendering = world let rendering = world
.get_resource::<settings::ProjectSettings>() .get_resource::<settings::ProjectSettings>()
.map(|s| s.rendering.clone()) .map(|s| s.rendering.clone())
@@ -348,25 +345,6 @@ pub fn flush_level_object_hydration(world: &mut World) {
} }
state.apply(world); state.apply(world);
for (entity, editor) in visibility_targets {
let visibility = visibility_from_editor(editor);
if let Some(mut vis) = world.get_mut::<Visibility>(entity) {
*vis = visibility;
} else if let Ok(mut entity_mut) = world.get_entity_mut(entity) {
entity_mut.insert(visibility);
}
if world.get::<InheritedVisibility>(entity).is_none() {
if let Ok(mut entity_mut) = world.get_entity_mut(entity) {
entity_mut.insert(InheritedVisibility::default());
}
}
if world.get::<ViewVisibility>(entity).is_none() {
if let Ok(mut entity_mut) = world.get_entity_mut(entity) {
entity_mut.insert(ViewVisibility::default());
}
}
}
} }
#[cfg(test)] #[cfg(test)]
+51 -1
View File
@@ -3,6 +3,24 @@
use crate::{EditorVisibility, LevelObject}; use crate::{EditorVisibility, LevelObject};
use bevy::prelude::*; use bevy::prelude::*;
/// Establishes the runtime visibility hierarchy synchronously for all authored actors.
///
/// Scene loading can occur between scheduled hydration sets, so callers that materialize a scene
/// must run this before generated render children can be attached in the same frame.
pub fn initialize_level_object_visibility_hierarchy(world: &mut World) {
let targets: Vec<(Entity, EditorVisibility)> = world
.query_filtered::<(Entity, Option<&EditorVisibility>), With<LevelObject>>()
.iter(world)
.map(|(entity, visibility)| (entity, visibility.copied().unwrap_or_default()))
.collect();
for (entity, editor_visibility) in targets {
if let Ok(mut entity_mut) = world.get_entity_mut(entity) {
entity_mut.insert((editor_visibility, visibility_from_editor(editor_visibility)));
}
}
}
#[expect( #[expect(
clippy::type_complexity, clippy::type_complexity,
reason = "the query mirrors Bevy's three visibility hierarchy components" reason = "the query mirrors Bevy's three visibility hierarchy components"
@@ -81,7 +99,9 @@ pub fn visibility_from_editor(editor: EditorVisibility) -> Visibility {
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::ensure_level_object_visibility_hierarchy; use super::{
ensure_level_object_visibility_hierarchy, initialize_level_object_visibility_hierarchy,
};
use crate::{EditorVisibility, LevelObject}; use crate::{EditorVisibility, LevelObject};
use bevy::prelude::*; use bevy::prelude::*;
@@ -102,4 +122,34 @@ mod tests {
assert!(world.get::<InheritedVisibility>(entity).is_some()); assert!(world.get::<InheritedVisibility>(entity).is_some());
assert!(world.get::<ViewVisibility>(entity).is_some()); assert!(world.get::<ViewVisibility>(entity).is_some());
} }
#[test]
fn immediate_initializer_establishes_hierarchy_before_scheduled_hydration() {
let mut world = World::new();
let entity = world
.spawn((LevelObject, EditorVisibility { visible: false }))
.id();
initialize_level_object_visibility_hierarchy(&mut world);
assert_eq!(world.get::<Visibility>(entity), Some(&Visibility::Hidden));
assert!(world.get::<InheritedVisibility>(entity).is_some());
assert!(world.get::<ViewVisibility>(entity).is_some());
}
#[test]
fn immediate_initializer_migrates_missing_authored_visibility() {
let mut world = World::new();
let entity = world.spawn(LevelObject).id();
initialize_level_object_visibility_hierarchy(&mut world);
assert_eq!(
world.get::<EditorVisibility>(entity),
Some(&EditorVisibility::default())
);
assert_eq!(world.get::<Visibility>(entity), Some(&Visibility::Visible));
assert!(world.get::<InheritedVisibility>(entity).is_some());
assert!(world.get::<ViewVisibility>(entity).is_some());
}
} }
+6 -4
View File
@@ -6,6 +6,7 @@
mod actor; mod actor;
mod animation; mod animation;
mod asset_fingerprint;
pub mod brush_math; pub mod brush_math;
mod components; mod components;
mod hydration; mod hydration;
@@ -18,12 +19,13 @@ mod rendering_profile_asset;
pub use actor::{infer_actor_kind, validate_actor, ActorValidationError}; pub use actor::{infer_actor_kind, validate_actor, ActorValidationError};
pub use animation::*; pub use animation::*;
pub use asset_fingerprint::AssetSourceFingerprint;
pub use components::*; pub use components::*;
pub use hydration::{ pub use hydration::{
cascade_config_from_rendering, flush_level_object_hydration, material_from_desc, cascade_config_from_rendering, flush_level_object_hydration,
strip_hydrated, strip_hydrated_entity, HydratedModelRoot, HydratedPrefabMember, initialize_level_object_visibility_hierarchy, material_from_desc, strip_hydrated,
HydratedPrefabReady, HydratedSkinnedMeshRoot, HydratedTerrainChunk, HydrationPlugin, strip_hydrated_entity, HydratedModelRoot, HydratedPrefabMember, HydratedPrefabReady,
PrefabHydrationBlocked, HydratedSkinnedMeshRoot, HydratedTerrainChunk, HydrationPlugin, PrefabHydrationBlocked,
}; };
pub use material_asset::{ pub use material_asset::{
load_resolved_material_from_path, MaterialAlphaMode, MaterialAsset, MaterialInstanceAsset, load_resolved_material_from_path, MaterialAlphaMode, MaterialAsset, MaterialInstanceAsset,
+12
View File
@@ -56,6 +56,9 @@ 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 | | [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 | | [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 | | [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 |
| [0043](adr/0043-content-addressed-import-fingerprints.md) | Content-addressed imported-source identity and byte-preserving artifact publication |
| [0044](adr/0044-sandboxed-fbx-external-texture-dependencies.md) | Sandboxed FBX texture bundles, validation policy, and deduplicated loading |
## Editor framework ## Editor framework
@@ -85,6 +88,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries | | [editor/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
| [editor/physics-placement.md](editor/physics-placement.md) | Transactional gravity placement, diagnostics, isolation, and undo workflow | | [editor/physics-placement.md](editor/physics-placement.md) | Transactional gravity placement, diagnostics, isolation, and undo workflow |
| [editor/collider-authoring.md](editor/collider-authoring.md) | Collider shape authoring, hydration diagnostics, semantic overlays, and placement prerequisites | | [editor/collider-authoring.md](editor/collider-authoring.md) | Collider shape authoring, hydration diagnostics, semantic overlays, and placement prerequisites |
| [editor/sample-regression-pack.md](editor/sample-regression-pack.md) | Five-area sample catalog, editor workflow, validation gates, and visual QA contract |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation | | [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
| [editor/evaluations/terrain-sculpt-tools/](editor/evaluations/terrain-sculpt-tools/) | Live screenshot and acceptance results for modal terrain sculpt tools | | [editor/evaluations/terrain-sculpt-tools/](editor/evaluations/terrain-sculpt-tools/) | Live screenshot and acceptance results for modal terrain sculpt tools |
| [editor/evaluations/terrain-material-layers/](editor/evaluations/terrain-material-layers/) | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history | | [editor/evaluations/terrain-material-layers/](editor/evaluations/terrain-material-layers/) | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history |
@@ -92,6 +96,11 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/evaluations/collider-diagnostics/](editor/evaluations/collider-diagnostics/) | Live screenshot and acceptance results for collider overlays, diagnostics, shape history, and placement preflight | | [editor/evaluations/collider-diagnostics/](editor/evaluations/collider-diagnostics/) | Live screenshot and acceptance results for collider overlays, diagnostics, shape history, and placement preflight |
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity | | [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
| [editor/evaluations/operator-invariants/](editor/evaluations/operator-invariants/) | Source acceptance results for production operator lifecycle, rollback, cleanup, and undo/redo invariants | | [editor/evaluations/operator-invariants/](editor/evaluations/operator-invariants/) | Source acceptance results for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
| [editor/evaluations/sample-regression-pack/](editor/evaluations/sample-regression-pack/) | Exact-implementation source and native acceptance evidence for the editor sample regression pack |
| [editor/evaluations/guarded-shutdown-savepoints/](editor/evaluations/guarded-shutdown-savepoints/) | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints |
| [editor/evaluations/scoped-ui-actions/](editor/evaluations/scoped-ui-actions/) | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering |
| [editor/evaluations/deterministic-asset-fingerprints/](editor/evaluations/deterministic-asset-fingerprints/) | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints |
| [editor/evaluations/fbx-external-texture-dependencies/](editor/evaluations/fbx-external-texture-dependencies/) | Source, validation, and native acceptance evidence for sandboxed FBX texture dependencies and override states |
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements | | [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
## Working plans (not canonical long-term) ## Working plans (not canonical long-term)
@@ -116,6 +125,9 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history | | `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
| `terrain_material_layers_*.plan.md` | Terrain shared-material layers, normalized weights, blended hydration, and modal painting | | `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 | | `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 |
| `fbx_external_texture_dependencies_*.plan.md` | Sandboxed FBX sidecar discovery, import transactions, validation, loader behavior, and Asset Browser states |
## Crate responsibilities (quick reference) ## Crate responsibilities (quick reference)
@@ -13,7 +13,12 @@ retaining explicit, separate paths for skinned geometry and generic full-scene d
## Decision ## Decision
Model imports now generate deterministic project artifacts under `assets/meshes/generated/*.static_mesh.ron`. The artifact records stable part IDs, source path, format, source fingerprint, import settings, mesh/material subasset labels, source node/material metadata, dependency paths, and warnings for metadata that is not played by the static mesh path. Model imports now generate deterministic project artifacts under
`assets/meshes/generated/*.static_mesh.ron`. The artifact records stable part IDs, source path,
format, the content-addressed source fingerprint owned by
[ADR 0043](0043-content-addressed-import-fingerprints.md), import settings, mesh/material subasset
labels, source node/material metadata, dependency paths, and warnings for metadata that is not
played by the static mesh path.
The saved scene authoring component is `StaticMeshRenderer`. Its slots reference imported mesh/material assets by `EditorAssetRef` (`asset_id` + `sub_asset_id`) rather than source file paths. Hydration resolves those refs through the generated artifact, spawns runtime child `Mesh3d` parts, and strips/regenerates them like other hydrated ECS. Built-in primitives remain `Primitive`, and explicit full-scene placement remains `ImportedModel + ModelRef`. The saved scene authoring component is `StaticMeshRenderer`. Its slots reference imported mesh/material assets by `EditorAssetRef` (`asset_id` + `sub_asset_id`) rather than source file paths. Hydration resolves those refs through the generated artifact, spawns runtime child `Mesh3d` parts, and strips/regenerates them like other hydrated ECS. Built-in primitives remain `Primitive`, and explicit full-scene placement remains `ImportedModel + ModelRef`.
@@ -35,4 +40,6 @@ Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts int
- Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector. - Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector.
- Skinned parts are marked in artifact schema v2 and excluded from static renderer construction and - Skinned parts are marked in artifact schema v2 and excluded from static renderer construction and
hydration. Animation playback uses the dedicated contract in ADRs 0031 and 0033. hydration. Animation playback uses the dedicated contract in ADRs 0031 and 0033.
- Static-mesh schema v4 uses byte length plus BLAKE3 rather than checkout mtime, so a source touch is
a no-op while a same-size byte edit is detected.
- Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs. - Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs.
@@ -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 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. 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 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 ## Consequences
- Interrupted manual writes retain the previous complete destination on filesystems with atomic - Interrupted manual writes retain the previous complete destination on filesystems with atomic
same-directory rename semantics. same-directory rename semantics.
- Recovery is machine-local and does not pollute builds or source control. - 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 - Autosave still performs authored serialization and hydration rebuild work. Performance
instrumentation and background snapshotting remain follow-up work under the production roadmap. 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 - 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 - 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 text, hierarchy expansion paths, non-destructive panel visibility, and finite camera bookmark
transforms. transforms.
- Write the session transactionally. Startup immediately writes `clean_shutdown: false`; normal - Write the session transactionally. Startup immediately writes `clean_shutdown: false`; only an
`AppExit` writes the final document with `clean_shutdown: true`. 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. - 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 An abnormal prior session starts from the normal safe scene and requires explicit confirmation
before opening the prior scene. before opening the prior scene.
@@ -23,6 +23,14 @@ Both the editor Diagnostics window and the `cargo validate-levels` headless comm
entry point. The command supports `--project <path>` and `--json`; the editor can select the live entry point. The command supports `--project <path>` and `--json`; the editor can select the live
owning actor for an attributed finding. Blocking errors produce a nonzero headless exit status. owning actor for an attributed finding. Blocking errors produce a nonzero headless exit status.
The optional editor regression pack has one conventional manifest at
`assets/samples/editor_samples.ron`. Schema v1 contains exactly one Brush, Material, Terrain,
Physics Placement, and Rendering sample with stable metadata, project-relative scene paths, and
explicit manual checks. `cargo validate-samples` validates that catalog and combines its findings
with the authoritative project report. Projects without the manifest remain valid ordinary
projects; Blacksite CI invokes the sample command to make the complete pack mandatory for this
repository.
Project validation covers the project manifest and asset roots, registry IDs/sources/dependencies, Project validation covers the project manifest and asset roots, registry IDs/sources/dependencies,
generated static mesh manifests, material and shader documents, post effects, scene and prefab generated static mesh manifests, material and shader documents, post effects, scene and prefab
graphs, authored model/material/texture/brush/collider references, rendering profiles, and graphs, authored model/material/texture/brush/collider references, rendering profiles, and
@@ -34,6 +42,16 @@ startup entrypoint. Unknown newer scene schemas are rejected rather than down-st
requirements are explicit findings; for example, Solari projects record the required forward-path requirements are explicit findings; for example, Solari projects record the required forward-path
fallback QA when ray tracing is unavailable. fallback QA when ray tracing is unavailable.
Imported model, texture, and audio registry records, animation manifests, and static-mesh manifests
share the content-addressed fingerprint contract in
[ADR 0043](0043-content-addressed-import-fingerprints.md). Validation hashes source bytes and catches
same-size changes without consulting mtimes. The validation entry point is read-only; CI asserts that
running both level and sample validation leaves the checkout unchanged.
Terrain descriptors participate in the same actor-owned dependency pass. Their authored dimensions,
height and weight grids, chunk settings, base material, and material layers are validated before
hydration so a sample or shipping scene cannot hide an invalid or unresolved terrain reference.
## Consequences ## Consequences
- Headless and editor validation share result semantics and finding ownership. - Headless and editor validation share result semantics and finding ownership.
@@ -42,3 +60,9 @@ fallback QA when ray tracing is unavailable.
Gitea #44 acceptance verifies the shared gate against real development output. Gitea #44 acceptance verifies the shared gate against real development output.
- Asset formats added later must register their dependencies with this validator and extend the - Asset formats added later must register their dependencies with this validator and extend the
valid, missing, cyclic, and incompatible project-fixture matrix. valid, missing, cyclic, and incompatible project-fixture matrix.
- The sample manifest is discovery and regression metadata, not a second project-settings schema;
editor UI and headless tooling consume the same scene ordering and validation result.
- CI must hydrate Git LFS before validation because a pointer file is intentionally treated as
missing runtime content.
- Validators report stale or incomplete import fingerprints with repair guidance but never rewrite
the registry or generated artifacts.
@@ -22,7 +22,8 @@ weights through `Mesh::ATTRIBUTE_COLOR`.
`blacksite_surface` owns the terrain-specific `ExtendedMaterial` and blends each resolved layer's `blacksite_surface` owns the terrain-specific `ExtendedMaterial` and blends each resolved layer's
albedo, tangent-space normal, metallic, and roughness inputs. Invalid or unavailable references leave albedo, tangent-space normal, metallic, and roughness inputs. Invalid or unavailable references leave
the existing visible terrain fallback in place and emit diagnostics. Terrain remains excluded from the existing visible terrain fallback in place and emit diagnostics. Terrain remains excluded from
Solari geometry until a matching ray-tracing evaluator exists. Solari geometry until a matching ray-tracing evaluator exists, and its opaque material is therefore
forced through Bevy's forward raster path even when the project default is deferred.
Editor paint strokes materialize the implicit default map only when needed. Each pointer stroke is a Editor paint strokes materialize the implicit default map only when needed. Each pointer stroke is a
single reflected `TerrainDesc` transaction; cancel restores the exact original descriptor. single reflected `TerrainDesc` transaction; cancel restores the exact original descriptor.
@@ -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.
@@ -0,0 +1,57 @@
# ADR 0043: Content-Addressed Import Fingerprints
## Status
Accepted
## Context
Generated model artifacts and the project asset registry must be stable across contributors, CI,
Git worktrees, and LFS checkouts. Git does not preserve source-file modification times. Persisting a
checkout mtime as source identity therefore caused the editor to rewrite otherwise equivalent
animation and static-mesh manifests during startup. Static-mesh manifests also used only byte length
and mtime, so a same-size source edit could evade the persisted identity contract.
Formatting-only publication was a second source of noise. Re-serializing an equivalent RON
document could normalize its final newline or layout even when import semantics had not changed.
That made clean-checkout release evidence unreliable and obscured intentional asset edits.
## Decision
`shared::AssetSourceFingerprint` is the persisted imported-source identity. It contains the exact
source byte length and lowercase BLAKE3 digest. Filesystem timestamps are not serialized or compared
as semantic identity; an importer may use them only as an in-memory scan hint before confirming
content.
The asset registry stores this fingerprint for every imported model, texture, and audio source.
Content identity also drives unique move reconciliation, so metadata-only drift cannot replace a
stable registry UUID. Ambiguous copies still receive a new identity.
Animation and static-mesh manifests use the same fingerprint. Animation schema v3 already contained
a content hash, so its schema remains v3 and legacy `modified_unix_secs` fields are accepted as
ignored unknown metadata. Static-mesh schema v4 replaces its length-plus-mtime record with length
plus BLAKE3. Existing schema-v3 static artifacts are regenerated once; unrelated assets are not
reimported.
Registry and generated-manifest writers parse the existing RON and compare the semantic value before
publication. Equivalent documents preserve their exact existing bytes, including layout and final
newlines. Changed documents publish canonical pretty RON. Registry records are ordered by normalized
project path before comparison, so filesystem enumeration order cannot change their serialized
sequence on a fresh checkout.
Authoritative project validation remains read-only. It validates registry, animation, and
static-mesh fingerprints by length and digest, including same-size source edits. CI runs both
headless validators and then asserts that tracked and untracked checkout state is unchanged.
## Consequences
- A source touch or fresh checkout mtime cannot dirty the project.
- Same-size source edits invalidate the affected registry/manifests deterministically.
- Model, texture, and audio IDs survive uniquely identifiable moves by content.
- Initial migration adds fingerprints to imported registry records and upgrades static manifests to
schema v4. Legacy animation files can remain byte-identical indefinitely because their timestamp
field is ignored.
- Startup hashing reads imported source bytes. Future scan caches may use metadata to avoid work,
but they must verify content before persisting a changed identity.
- External glTF/FBX dependency paths remain explicit manifest dependencies; extending fingerprints
to a dependency graph requires a separate versioned contract.
@@ -0,0 +1,68 @@
# ADR 0044: Sandboxed FBX External Texture Dependencies
## Status
Accepted
## Context
FBX texture references may use sibling folders such as `textures/`, exporter-created `.fbm/`
folders, absolute workstation paths, Windows separators, or repeated ufbx texture elements that
resolve to the same file. Blacksite previously discovered only files already present in a sibling
`{model}.fbm/` directory. The committed painted-chair FBX instead declares three files under
`textures/`; none were committed, so source-material thumbnails queued the same missing Bevy image
paths more than once.
Import, manifest generation, project validation, editor previews, and the runtime loader must agree
on one dependency graph. That graph also crosses a security boundary: an imported source must not
read or copy a parent-traversing path or an arbitrary absolute path outside its bundle. A missing
source texture is required when Source Materials is active, but it can be an intentional authoring
condition when an asset explicitly uses Authoring Override.
## Decision
The local `bevy_ufbx` compatibility crate owns FBX external-texture path discovery and
normalization. It converts separators to `/`, preserves safe sibling and `.fbm/` layouts,
deduplicates normalized paths, and rejects parent traversal, asset-path syntax, and absolute paths.
An absolute exporter path may be portably rebased only when it contains a `.fbm/` suffix; only that
sidecar-relative suffix is retained.
The FBX loader performs a discovery parse, drops the non-`Send` ufbx scene, reads every unique safe
dependency through Bevy's `LoadContext`, and then performs normal synchronous scene processing.
External images become FBX labeled assets from those bytes. Repeated texture elements share one
image handle. Missing, rejected, or undecodable references are skipped with one consolidated
loader warning instead of deferred asset-server requests.
Static-mesh manifests are the authoritative model import dependency graph. Their existing
`source.dependencies` list records every parsed FBX external texture, including unavailable files.
Project validation checks that list without loading native assets. Missing FBX textures are a
blocking consolidated finding under Source Materials and an informational consolidated finding
under Authoring Override. Unsafe paths remain blocking under either policy. Model registry records
mirror the list for editor details, but validation does not duplicate it when a generated static
manifest exists.
File -> Import Assets treats an FBX plus its referenced textures as one bundle. The importer
preflights every source path and canonical containment before touching the project, rejects
destination paths with symlinked ancestors, stages only the referenced files, preserves their
normalized relative layout, backs up overwritten destinations, and rolls back a partial publish.
Unreferenced `.fbm` contents are not copied.
The Asset Browser renders FBX model and mesh thumbnails through the neutral direct mesh path.
Source-material thumbnails preflight the authoritative dependency resolver first and cache one
non-retryable actionable failure when required textures are unavailable. Dependency rows expose
present/missing state. The committed painted-chair fixture uses Authoring Override deliberately and
remains untextured; its three source paths stay visible in manifests, validation, and asset details.
## Consequences
- FBX sibling `textures/` and `.fbm/` bundles import and validate with identical normalized paths.
- Missing texture files are visible before native loading and cannot create repeated Bevy
asset-server errors.
- Source Materials fails release validation when its FBX textures are absent. Authoring Override
remains release-valid but retains an informational dependency finding.
- Absolute exporter paths, traversal attempts, and destination symlink redirects cannot read or
copy arbitrary host files.
- FBX files with external textures are parsed twice during loading so no non-`Send` ufbx scene
crosses an async read. Files without external textures retain a single parse.
- External images are labeled children of the FBX and reload the owning FBX through loader
dependency tracking. Per-image import metadata is not yet exposed.
+15 -2
View File
@@ -28,6 +28,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [terrain.md](terrain.md) | Inline height-grid terrain, chunk hydration, collision, inspector workflow, and fixtures | | [terrain.md](terrain.md) | Inline height-grid terrain, chunk hydration, collision, inspector workflow, and fixtures |
| [physics-placement.md](physics-placement.md) | Transactional gravity placement, prerequisites, isolation, commit/cancel, and undo | | [physics-placement.md](physics-placement.md) | Transactional gravity placement, prerequisites, isolation, commit/cancel, and undo |
| [collider-authoring.md](collider-authoring.md) | Collider shape editing, shared health diagnostics, overlays, hydration status, and placement reuse | | [collider-authoring.md](collider-authoring.md) | Collider shape editing, shared health diagnostics, overlays, hydration status, and placement reuse |
| [sample-regression-pack.md](sample-regression-pack.md) | Five-area sample manifest, native workflow, visual composition, validation, and maintenance contract |
| [evaluations/](evaluations/) | Acceptance evidence records and native Gitea attachment publishing policy | | [evaluations/](evaluations/) | Acceptance evidence records and native Gitea attachment publishing policy |
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation | | [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
| [evaluations/material-library-targeted-drop/](evaluations/material-library-targeted-drop/) | Live screenshot and verification record for the docked Material Library and exact reversible surface drops | | [evaluations/material-library-targeted-drop/](evaluations/material-library-targeted-drop/) | Live screenshot and verification record for the docked Material Library and exact reversible surface drops |
@@ -40,6 +41,11 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [evaluations/collider-diagnostics/](evaluations/collider-diagnostics/) | Live screenshot and verification record for semantic collider overlays, health linking, shape switching, and placement reuse | | [evaluations/collider-diagnostics/](evaluations/collider-diagnostics/) | Live screenshot and verification record for semantic collider overlays, health linking, shape switching, and placement reuse |
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity | | [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
| [evaluations/operator-invariants/](evaluations/operator-invariants/) | Source acceptance record for production operator lifecycle, rollback, cleanup, and undo/redo invariants | | [evaluations/operator-invariants/](evaluations/operator-invariants/) | Source acceptance record for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
| [evaluations/sample-regression-pack/](evaluations/sample-regression-pack/) | Exact-implementation source and native acceptance evidence for the five-area editor regression pack |
| [evaluations/guarded-shutdown-savepoints/](evaluations/guarded-shutdown-savepoints/) | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints |
| [evaluations/scoped-ui-actions/](evaluations/scoped-ui-actions/) | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering |
| [evaluations/deterministic-asset-fingerprints/](evaluations/deterministic-asset-fingerprints/) | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints |
| [evaluations/fbx-external-texture-dependencies/](evaluations/fbx-external-texture-dependencies/) | Source, validation, and native acceptance evidence for sandboxed FBX sidecar dependencies and override states |
| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence | | [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence |
## Subsystems (code → doc) ## Subsystems (code → doc)
@@ -59,7 +65,8 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| `ui/navigation_inspector.rs` / `scene::navigation` / `game::navigation` | Navigation authoring, deterministic bake artifacts, viewport preview, and runtime path queries | navigation-authoring.md, ADR 0032 | | `ui/navigation_inspector.rs` / `scene::navigation` / `game::navigation` | Navigation authoring, deterministic bake artifacts, viewport preview, and runtime path queries | navigation-authoring.md, ADR 0032 |
| `assets/materials.rs` / `ui/material_library.rs` / `viewport/material_drop.rs` / `shared::renderer_material` | Shared material discovery, docked catalog/usage UI, exact reversible surface drops, stable renderer slots, and draw binding | material-system.md, ADR 0035 | | `assets/materials.rs` / `ui/material_library.rs` / `viewport/material_drop.rs` / `shared::renderer_material` | Shared material discovery, docked catalog/usage UI, exact reversible surface drops, stable renderer slots, and draw binding | material-system.md, ADR 0035 |
| `blacksite_surface` / `game_hot::rendering::solari` / `third_party/bevy_solari` | Surface ABI packing, raster composition, Solari evaluator dispatch, and deformation eligibility | material-system.md, rendering.md, ADR 0036 | | `blacksite_surface` / `game_hot::rendering::solari` / `third_party/bevy_solari` | Surface ABI packing, raster composition, Solari evaluator dispatch, and deformation eligibility | material-system.md, rendering.md, ADR 0036 |
| `assets/` | Catalog, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027 | | `assets/fingerprint.rs` / `shared::AssetSourceFingerprint` | Content-addressed imported-source identity and byte-preserving registry/manifest publication | ADR 0043, evaluations/deterministic-asset-fingerprints/ |
| `assets/` | Catalog, transactional import bundles, asset DB, static mesh artifacts, `thumbnails/`, `materials.rs`, prefab overrides v2 | this file (below), prefab-authoring.md, ADR 0017, ADR 0027, ADR 0044 |
| `shared::prefab_overrides` | Versioned stable override schema and editor-independent runtime application | prefab-authoring.md, 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/` | 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/collaboration.rs` | Guarded authored writes, asynchronous Git status, and optional ownership providers | collaborative-file-safety.md, ADR 0037 |
@@ -67,6 +74,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| `project/session.rs` | Versioned XDG session document, clean marker, and safe resume | session-recovery.md, ADR 0024 | | `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/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 | | `project/launcher.rs` | Strict project inspection, CLI activation, recent filtering, and sandbox scaffolding | project-launcher.md, ADR 0025 |
| `project/samples.rs` / `scene::sample_pack` / `xtask/src/validate_samples.rs` | Cached editor sample catalog, canonical pack contract, and deterministic headless release gate | sample-regression-pack.md, ADR 0028 |
| `ext/` | Command palette, BRP, game panel adapters | ADR 0007 | | `ext/` | Command palette, BRP, game panel adapters | ADR 0007 |
| `ui/mod.rs` | Dock layout, unified viewport, menus | README controls | | `ui/mod.rs` | Dock layout, unified viewport, menus | README controls |
| `ui/scene_tabs.rs` | Main-toolbar scene tabs and composition controls | multi-scene-composition.md, ADR 0026 | | `ui/scene_tabs.rs` | Main-toolbar scene tabs and composition controls | multi-scene-composition.md, ADR 0026 |
@@ -85,7 +93,8 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
- **Dedicated egui `Camera2d`** at full window — never attach `PrimaryEguiContext` to a viewport-cropped 3D camera (NaN layout panic). - **Dedicated egui `Camera2d`** at full window — never attach `PrimaryEguiContext` to a viewport-cropped 3D camera (NaN layout panic).
- **Unified viewport** uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping. - **Unified viewport** uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping.
- **PIE:** F8 possess/eject while sim runs; **F6** pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera. - **PIE:** F8 possess/eject while sim runs; **F6** pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera.
- **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture/model/material thumbnails, a details pane, and context-aware row/menu actions; narrow docks prioritize content, keep the root panel fixed, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree, asset content, and details panels scroll. **Built-ins** holds spawnable primitives and lights. **Materials** folder scans `assets/materials/*.ron`, renders material thumbnails on a sphere using `MaterialDesc`, and exposes shader-schema-driven parameters/textures in the details editor; **Shaders** holds shader schema RON files. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips under `assets/audio/`, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references that retain a runtime source path. glTF/GLB/FBX rows can expand into a shelf of normalized embedded mesh, material, and texture subassets with independent generated thumbnails. Mesh subassets can be selected, dragged into the viewport, or placed from details/context menus; material subassets render source-material spheres; texture subassets can be applied to the selected actor. Model import settings are staged with **Apply** / **Revert**, asset context menus can regenerate thumbnails, material asset details edit shared `MaterialAsset` fields, and file asset deletion moves sources/generated artifacts into `assets/.trash/`. Before thumbnail loading, glTF sources preflight local external buffers/images and show a stable non-retryable failure state when a dependency is missing instead of repeatedly invoking the asset loader. - **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture/model/material thumbnails, a details pane, and context-aware row/menu actions; narrow docks prioritize content, keep the root panel fixed, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree, asset content, and details panels scroll. **Built-ins** holds spawnable primitives and lights. **Materials** folder scans `assets/materials/*.ron`, renders material thumbnails on a sphere using `MaterialDesc`, and exposes shader-schema-driven parameters/textures in the details editor; **Shaders** holds shader schema RON files. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips under `assets/audio/`, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references that retain a runtime source path. glTF/GLB/FBX rows can expand into a shelf of normalized embedded mesh, material, and texture subassets with independent generated thumbnails. Mesh subassets can be selected, dragged into the viewport, or placed from details/context menus; material subassets render source-material spheres; texture subassets can be applied to the selected actor. Model import settings are staged with **Apply** / **Revert**, asset context menus can regenerate thumbnails, material asset details edit shared `MaterialAsset` fields, and file asset deletion moves sources/generated artifacts into `assets/.trash/`. Before thumbnail loading, glTF sources preflight local external buffers/images. FBX source-material previews use the same sandboxed resolver as import and validation, expose one cached hover-visible dependency failure, and never enqueue known-missing texture paths; neutral model/mesh previews remain available. Asset details mark present/missing dependencies and identify missing textures intentionally ignored by Authoring Override. FBX bundle import preserves referenced sibling or `.fbm/` layout transactionally. See [ADR 0044](../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
- **Imported-source fingerprints** use exact byte length plus lowercase BLAKE3 for model, texture, and audio registry records and for generated static-mesh/animation manifests. Filesystem timestamps are scan hints only; equivalent refresh preserves the exact committed RON bytes and registry publication order is normalized by project path. See [ADR 0043](../adr/0043-content-addressed-import-fingerprints.md) and the [acceptance record](evaluations/deterministic-asset-fingerprints/).
- **Material Library** is a dockable bottom-panel catalog for cross-folder Material and direct-base Material Instance authoring. It provides search, type and scene-usage filters, grid/list thumbnails, dependency health, usage counts, creation, guarded details editing, and first-class drag sources. Viewport drops resolve an exact renderer slot, primitive, or brush face under the pointer, preview transiently, reject incompatible/read-only targets explicitly, restore on target change/cancel, and commit one typed undo step on release. - **Material Library** is a dockable bottom-panel catalog for cross-folder Material and direct-base Material Instance authoring. It provides search, type and scene-usage filters, grid/list thumbnails, dependency health, usage counts, creation, guarded details editing, and first-class drag sources. Viewport drops resolve an exact renderer slot, primitive, or brush face under the pointer, preview transiently, reject incompatible/read-only targets explicitly, restore on target change/cancel, and commit one typed undo step on release.
- **Static/skinned renderer split** — model drag/drop uses normalized artifacts under `assets/meshes/generated/`. Unrigged, non-animated sources create `ActorKind::StaticMesh + StaticMeshRenderer`; skin-bound or animated sources create `ActorKind::SkinnedMesh + SkinnedMeshRenderer` and preserve the imported hierarchy. Static slots never contain marked skinned primitives or geometry from animated sources. `SceneInstance` placement keeps `ImportedModel + ModelRef` for generic full-source scenes. See [ADR 0033](../adr/0033-dedicated-skinned-mesh-renderer.md). - **Static/skinned renderer split** — model drag/drop uses normalized artifacts under `assets/meshes/generated/`. Unrigged, non-animated sources create `ActorKind::StaticMesh + StaticMeshRenderer`; skin-bound or animated sources create `ActorKind::SkinnedMesh + SkinnedMeshRenderer` and preserve the imported hierarchy. Static slots never contain marked skinned primitives or geometry from animated sources. `SceneInstance` placement keeps `ImportedModel + ModelRef` for generic full-source scenes. See [ADR 0033](../adr/0033-dedicated-skinned-mesh-renderer.md).
- **Animation authoring** — glTF/GLB imports generate UUID-keyed rig/clip manifests and expandable skeleton/clip shelves. Clip drag creates a skinned actor or adds one exact-signature-compatible state to a selected skinned actor through typed history. `AnimationControllerDesc` exposes named states, ranges, loop/speed, default/crossfade, and non-dirty runtime-backed preview; project validation resolves the same stable refs and blocks animated/skinned FBX with conversion guidance. Production acceptance completed in Gitea #46. See [animation-authoring.md](animation-authoring.md) and [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md). - **Animation authoring** — glTF/GLB imports generate UUID-keyed rig/clip manifests and expandable skeleton/clip shelves. Clip drag creates a skinned actor or adds one exact-signature-compatible state to a selected skinned actor through typed history. `AnimationControllerDesc` exposes named states, ranges, loop/speed, default/crossfade, and non-dirty runtime-backed preview; project validation resolves the same stable refs and blocks animated/skinned FBX with conversion guidance. Production acceptance completed in Gitea #46. See [animation-authoring.md](animation-authoring.md) and [ADR 0031](../adr/0031-animation-authoring-runtime-contract.md).
@@ -108,6 +117,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 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. 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). - **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). - **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. - **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. - **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.
+11 -4
View File
@@ -68,10 +68,11 @@ serialize into authored scenes.
`SkinnedMeshRenderer`, skeleton references, and clip references carry the model registry UUID. Generated `SkinnedMeshRenderer`, skeleton references, and clip references carry the model registry UUID. Generated
artifacts are keyed by that UUID; source paths are cached resolution and repair hints. When one artifacts are keyed by that UUID; source paths are cached resolution and repair hints. When one
model is moved or renamed on disk, catalog refresh reconciles it by its animation-manifest content model is moved or renamed on disk, catalog refresh reconciles it by the registry's shared
hash, preserves the UUID, and regenerates both manifests with the new source path. An identical copy content-addressed source fingerprint, preserves the UUID, and regenerates both manifests with the
is not treated as a move while the original still exists. Ambiguous content matches intentionally new source path. The same registry policy covers textures and audio clips. An identical copy is not
receive a new identity rather than silently binding the wrong asset. treated as a move while the original still exists. Ambiguous content matches intentionally receive
a new identity rather than silently binding the wrong asset.
Scene schema v3 migrates legacy animated actors that paired `ModelRef` with Scene schema v3 migrates legacy animated actors that paired `ModelRef` with
`AnimationControllerDesc` to the dedicated skinned renderer. Generic `ImportedModel + ModelRef` `AnimationControllerDesc` to the dedicated skinned renderer. Generic `ImportedModel + ModelRef`
@@ -83,6 +84,12 @@ used as identity. Animation-manifest schema v1 artifacts must be reimported to g
signatures; schema v3 adds the explicit default-clip ID. Schema v2 deserializes as Imported rest signatures; schema v3 adds the explicit default-clip ID. Schema v2 deserializes as Imported rest
pose and never receives an inferred default. pose and never receives an inferred default.
Source identity uses exact byte length plus BLAKE3 and never checkout mtime. Existing animation
schema-v3 files may retain a legacy `modified_unix_secs` field in their exact bytes; the current
reader ignores it, and an equivalent refresh preserves the whole file unchanged. Static-mesh schema
v4 uses the same content fingerprint. See
[ADR 0043](../adr/0043-content-addressed-import-fingerprints.md).
## Validation And Format Boundary ## Validation And Format Boundary
Interactive diagnostics and `cargo validate-levels` resolve registry UUIDs, generated manifests, Interactive diagnostics and `cargo validate-levels` resolve registry UUIDs, generated manifests,
+33 -7
View File
@@ -87,11 +87,20 @@ or Cancel. Generated artifacts remain under their subsystem-owned regeneration p
[collaborative-file-safety.md](collaborative-file-safety.md) and [collaborative-file-safety.md](collaborative-file-safety.md) and
[ADR 0037](../adr/0037-collaborative-authored-file-safety.md). [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 `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 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 bookmarks, writes a running marker at startup, and records clean state only for a coordinator-
not auto-open the prior scene; the explicit safe-resume prompt is the only path back. See authorized `AppExit`. Abnormal sessions do not auto-open the prior scene; the explicit safe-resume
[ADR 0024](../adr/0024-versioned-editor-session-state.md). 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 `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 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`. 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. 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. 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 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 dedicated skinned-model hierarchies at runtime. Level-object roots are initialized with Bevy
visibility hierarchy components before generated children are attached, so authoring visibility hierarchy components before generated children are attached, so authoring
@@ -211,18 +220,35 @@ the Edit-to-Play boundary restore the complete runtime snapshot. See
## Model import (glTF + FBX) ## Model import (glTF + FBX)
- **Import:** File → Import Assets copies glTF/GLB/FBX into `assets/models/`. FBX imports also copy a sibling `{name}.fbm/` folder when present (embedded textures). - **Import:** File -> Import Assets copies glTF/GLB/FBX into `assets/models/`. An FBX import
parses every safe external texture reference, including sibling `textures/` and `.fbm/` layouts,
then stages and publishes the complete referenced bundle transactionally. Absolute non-sidecar
paths, parent traversal, and dependencies that canonically escape the source folder are rejected
before project files change; unreferenced sidecar contents are not copied.
- **Processing:** the asset registry generates normalized model manifests under - **Processing:** the asset registry generates normalized model manifests under
`assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset `assets/meshes/generated/`. The manifests store stable part IDs, glTF/FBX mesh/material subasset
labels, whether each part is skin-bound, source metadata, dependencies, and import settings. labels, whether each part is skin-bound, source metadata, dependencies, and import settings.
These artifacts are hidden from the Asset Browser catalog. Model, texture, and audio registry records use byte length plus BLAKE3 source identity; model
manifests use the same policy. Semantic RON comparison preserves exact existing bytes for an
equivalent refresh, so checkout mtimes and formatting do not dirty project content. See
[ADR 0043](../adr/0043-content-addressed-import-fingerprints.md). These artifacts are hidden from
the Asset Browser catalog.
- **FBX dependencies:** the local `bevy_ufbx` resolver owns separator normalization, safe `.fbm/`
rebasing, deduplication, and sandbox rejection. Static-mesh manifests record every declared
external texture even when it is absent. Project validation reports one blocking finding for
missing Source Materials textures, or one informational finding when Authoring Override
deliberately leaves the model untextured. The runtime loader reads unique dependencies through
`LoadContext` and creates labeled images directly, so missing paths cannot fan out into repeated
asset-server errors. See [ADR 0044](../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
- **Browser subassets:** model rows can expand into a content shelf backed by the generated - **Browser subassets:** model rows can expand into a content shelf backed by the generated
manifest. Unrigged mesh subassets place as independent `StaticMeshRenderer` actors. A skinned manifest. Unrigged mesh subassets place as independent `StaticMeshRenderer` actors. A skinned
subasset places its owning source through `SkinnedMeshRenderer`, retaining joints and inverse bind subasset places its owning source through `SkinnedMeshRenderer`, retaining joints and inverse bind
poses. Material subassets expose source defaults, and texture dependencies can be applied to poses. Material subassets expose source defaults, and texture dependencies can be applied to
selected actors. The thumbnail studio renders each generated model/subasset/material preview into selected actors. The thumbnail studio renders each generated model/subasset/material preview into
its own render target before registering it in the cache so later thumbnails cannot overwrite its own render target before registering it in the cache so later thumbnails cannot overwrite
earlier cache entries. earlier cache entries. FBX model and mesh previews use neutral direct geometry; source-material
previews preflight external textures and retain one stable hover-visible failure reason instead
of enqueueing a known-missing path.
- **Default placement:** **Renderable Asset (Auto)** creates - **Default placement:** **Renderable Asset (Auto)** creates
`ActorKind::StaticMesh + StaticMeshRenderer` for unrigged, non-animated models and `ActorKind::StaticMesh + StaticMeshRenderer` for unrigged, non-animated models and
`ActorKind::SkinnedMesh + SkinnedMeshRenderer` when any part is skin-bound or the source contains `ActorKind::SkinnedMesh + SkinnedMeshRenderer` when any part is skin-bound or the source contains
+5
View File
@@ -11,6 +11,10 @@ Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-
| Optional / inferred `ActorKind` as long-term save path | Done | Schema v2 + migration; save validates | | Optional / inferred `ActorKind` as long-term save path | Done | Schema v2 + migration; save validates |
| Hydrated components in committed `.scn.ron` | CI | `scene::validate_scene_authoring_only` + `repo_editor_scene_has_no_hydrated_components` | | Hydrated components in committed `.scn.ron` | CI | `scene::validate_scene_authoring_only` + `repo_editor_scene_has_no_hydrated_components` |
| Production mutation without commit/cancel/failure/undo invariants | Done | Shared operator harness plus typed history projections cover palette, asset, brush, terrain, physics, grouping, lighting, material-drop, and transform paths; see [evaluation](evaluations/operator-invariants/) | | Production mutation without commit/cancel/failure/undo invariants | Done | Shared operator harness plus typed history projections cover palette, asset, brush, terrain, physics, grouping, lighting, material-drop, and transform paths; see [evaluation](evaluations/operator-invariants/) |
| Representative editor coverage can silently disappear | Done | Versioned five-area manifest, typed scene gate, `validate-samples`, and native protocol; see [sample pack](sample-regression-pack.md) |
| Dirty editor exit can bypass an explicit decision, or transient entity IDs define document cleanliness | Done | Guarded shutdown and canonical authored-content checkpoints pass source validation and all seven native workflows at source implementation `4b33f32`, including dirty untitled Save All through Save As. See the [evaluation](evaluations/guarded-shutdown-savepoints/). |
| Scoped UI callbacks depend on temporarily unavailable host state or lose direct selection precedence | Done | Explicit selection/tab requests, panel-owned state, captured viewport data, and full-slice reconciliation pass six scoped regressions, independent re-review, and native toolbar/Inspector/diagnostics acceptance at `9e23ae7`; see the [evaluation](evaluations/scoped-ui-actions/). |
| Checkout metadata or filesystem enumeration can rewrite imported-asset artifacts | Done | Shared content fingerprints, semantic byte-preserving publication, normalized registry order, clean-checkout validators, and live mtime-only drift pass at `cbd380a`; see the [evaluation](evaluations/deterministic-asset-fingerprints/). |
| Dual FBX thumbnail ad-hoc path (parallel to unified pipeline) | Partial | Phase 5 `assets/thumbnails/` refactor | | Dual FBX thumbnail ad-hoc path (parallel to unified pipeline) | Partial | Phase 5 `assets/thumbnails/` refactor |
| `failed_keys` thumbnail cache without retry API | Partial | `asset_thumbnails.rs`; Phase 5 `ThumbnailState` | | `failed_keys` thumbnail cache without retry API | Partial | `asset_thumbnails.rs`; Phase 5 `ThumbnailState` |
@@ -31,3 +35,4 @@ Living checklist for the production editor program ([ADR 0012](../adr/0012-zero-
- [ ] Save/load roundtrip: hierarchy, lights, materials unchanged - [ ] Save/load roundtrip: hierarchy, lights, materials unchanged
- [ ] PIE 60s stop: project lighting profile unchanged unless scene overrides edited - [ ] PIE 60s stop: project lighting profile unchanged unless scene overrides edited
- [ ] Rerun the [operator invariant matrix](operator-regression-testing.md) from the nominated release-candidate commit - [ ] Rerun the [operator invariant matrix](operator-regression-testing.md) from the nominated release-candidate commit
- [ ] Open all five [sample regression pack](sample-regression-pack.md) entries through the native File menu and record exact-candidate results
+8 -6
View File
@@ -1,15 +1,17 @@
# Editor Evaluation Evidence # Editor Evaluation Evidence
Each subdirectory keeps the canonical, versioned acceptance record for an editor feature. Screenshots Each subdirectory keeps the canonical, versioned acceptance record for an editor feature. Record
remain in the repository beside that record and are intentionally stored through Git LFS. visual evidence with its attachment ID, dimensions, and checksum. A repository image copy is
optional; the committed Markdown record, not a raw image URL, is the source of truth.
## Publishing To Gitea ## Publishing To Gitea
Do not embed a repository `/raw/branch/...` or `/raw/commit/...` PNG URL in an issue or pull-request Do not embed a repository `/raw/branch/...` or `/raw/commit/...` PNG URL in an issue or pull-request
comment. Gitea can serve the LFS pointer document at that URL, which renders as text instead of an comment. Gitea can serve the LFS pointer document at that URL, which renders as text instead of an
image. Upload the PNG to the relevant issue as a native attachment and use the returned image. Upload the PNG to the relevant issue as a native attachment and use the returned
`/attachments/<uuid>` URL for the Markdown image. Keep the repository evaluation link next to the `/attachments/<uuid>` URL for the Markdown image. Keep the committed evaluation link next to the
attachment so the evidence remains traceable to its committed source. attachment so the evidence remains traceable to its tested source and exact commit.
Native attachments are presentation copies. The committed evaluation directory remains the source of Native attachments are the presentation copies used by issues and pull requests. Do not commit a
truth and should retain the original image and verification notes. duplicate image solely to publish it; retain verification notes and attachment metadata in the
evaluation record.
@@ -0,0 +1,100 @@
# Deterministic Imported-Asset Fingerprints Evaluation
**Date:** 2026-07-13
**Issue:** [Gitea #56](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/56)
**Content-addressed implementation:** `e1b2f86a495496da83947777d332d00a15a1779d`
**Stable publication ordering:** `cbd380a9413411667a83f74b66c5a2feda5e1af7`
**Release-candidate commit:** Not nominated
**Source validation:** **Pass**
**Fresh-checkout acceptance:** **Pass**
**Native acceptance:** **Pass**
This record covers imported model, texture, and audio source identity plus the animation, static-mesh,
and registry documents derived from those sources. The permanent contract is owned by
[ADR 0043](../../../adr/0043-content-addressed-import-fingerprints.md).
## Automated Verification
| Command or suite | Result | Evidence |
|------------------|--------|----------|
| `cargo fmt --all -- --check` | Pass | Formatting completed without changes. |
| `git diff --check` | Pass | No whitespace errors. |
| `cargo clippy --workspace --all-targets -- -D warnings` | Pass | Workspace and all targets completed with warnings denied. |
| `cargo test --workspace --all-targets --no-fail-fast` | Pass | All workspace targets passed; editor reported 300 passing tests, scene reported 100 passing and one ignored manual-migration test, and shared reported 99 passing tests. |
| Fingerprint regressions | Pass | Exact-byte BLAKE3 identity, same-size byte changes, mtime-only drift, legacy timestamp tolerance, stable move recovery, imported-source coverage, semantic RON equality, and read-only validation are covered. |
| `cargo validate-levels --project .` | Pass | 81 dependencies, five known nonblocking import/platform findings, zero blocking errors. |
| `cargo validate-samples --project .` | Pass | Five samples, 86 dependencies, the same five nonblocking findings, zero blocking errors. |
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed. |
## Fresh Checkout
The first exact-commit run at `e1b2f86` exposed one remaining nondeterministic path: native startup
discovered catalog entries in filesystem order and rewrote `assets/.index/registry.ron`. That run
failed the clean-checkout gate. Commit `cbd380a` sorts records by normalized project path before
semantic comparison and adds a discovery-order regression test.
A new detached, LFS-hydrated worktree at `cbd380a` then completed native startup, asset scan,
`validate-levels`, and `validate-samples` with an empty `git status --short`. Touching
`assets/models/RobotExpressive.glb` while the editor was live also left the worktree clean. Its
original nanosecond timestamp was restored after the test.
The following SHA-256 values were identical before startup, after startup, after the mtime-only
change, and after both validators:
| Artifact | SHA-256 |
|----------|---------|
| `assets/.index/registry.ron` | `5beb11fb708729fb024e2e671596876bcf31b3c3fd2cea51da777db1d343644e` |
| `113f74df...static_mesh.ron` | `8d93e4d49c4f1d00ea8c482e8e1981f18d7a71224847c2b9f05f153982c5e80e` |
| `3f63f359...static_mesh.ron` | `e47099d59ec4ce9dc977ba6a08ddee36f1d99c0f13d9278998f21cba72571585` |
| `b98ef565...static_mesh.ron` | `edc77d61284c1010c8811d40bd7cedebfcbd6a3d88145e54d5c1ef7dc3a0a864` |
| `113f74df...animation.ron` | `0e678584aca470b36afd14b75a950d84a87d445438ba9b0a1e3416e863dda92a` |
| `3f63f359...animation.ron` | `45d3f9e9dcc64137f40a339c84512b6aba47102f7593aa6a9344891de68c0c07` |
| `b98ef565...animation.ron` | `691eb70ff05b2a4d03f51766f4c682a4171f7c76721f453c434f8de6fd936408` |
## Native Acceptance
| Workflow | Result | Evidence |
|----------|--------|----------|
| Main checkout startup | Pass | The exact debug editor at `e1b2f86` loaded the committed scene with populated hierarchy, viewport, Inspector, and Asset Browser, then exited with code 0. |
| Imported model browser | Pass | Opening `assets/models` rendered all three model rows and thumbnails; selecting the FBX exposed its registry-backed details without destabilizing the editor. |
| Fixed fresh checkout | Pass | The exact `cbd380a` editor launched from the detached worktree, rendered the complete editor frame, preserved every artifact byte, and exited with code 0. |
| Metadata-only drift | Pass | A live source `touch` produced no registry or manifest change and no Git diff. |
## Native Evidence
![Fresh LFS checkout running the complete editor without rewriting imported artifacts](https://git.spacetrainclubhouse.com/attachments/df761c85-0b82-4a25-9d33-9cf8189539f0)
- Gitea attachment asset 39: `blacksite-issue56-fresh-fixed-cbd380a.png`, 3426x1384 sRGB PNG,
1,787,700 bytes.
- SHA-256: `2748ae3de31ff97933c9793b90475ffd38d54d7e9dd5d65937b699f81c73c9bc`.
![Imported model thumbnails and registry-backed FBX details in the live editor](https://git.spacetrainclubhouse.com/attachments/93da7803-de47-43fb-bb8c-f759970a2b5f)
- Gitea attachment asset 40: `blacksite-issue56-models-e1b2f86.png`, 3426x1384 sRGB PNG,
1,940,210 bytes.
- SHA-256: `064c0634ebac47b52516412b022247ba8aa6f155014db8f8d3cca86850509da7`.
Both images are ordinary Gitea issue attachments. This record does not use repository raw or Git LFS
pointer URLs.
## Separate Finding
Selecting the painted-chair FBX exposed missing external texture dependencies in the committed
fixture: `painted_wooden_chair_02_diff_2k.jpg`, `painted_wooden_chair_02_nor_gl_2k.exr`, and
`painted_wooden_chair_02_rough_2k.exr`. The asset server reported six load errors because the paths
were requested more than once. This is an FBX dependency/import-fixture defect, not a deterministic
fingerprint failure, and is tracked separately in
[Gitea #58](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/58).
## Release Use
The #56 source, fresh-checkout, and native feature-level acceptance record is complete. A future
production candidate must rerun the clean-checkout protocol from the exact nominated commit. This
record does not nominate a candidate or establish production readiness.
@@ -0,0 +1,71 @@
# FBX External Texture Dependency Evaluation
**Date:** 2026-07-13
**Issue:** [Gitea #58](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/58)
**Implementation commit:** `3e30c61c71fc942c33635aae3d922b70401fe7c7`
**Release-candidate commit:** Not nominated
**Source validation:** **Pass**
**Native acceptance:** **Pass**
This record covers path-safe FBX texture discovery, transactional bundle import, labeled runtime
images, static-mesh dependency publication, read-only project validation, and stable Asset Browser
states. The permanent contract is owned by
[ADR 0044](../../../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
## Automated Verification
| Command or suite | Result | Evidence |
|------------------|--------|----------|
| `cargo fmt --all -- --check` | Pass | Formatting completed without changes. |
| `git diff --check` | Pass | No whitespace errors. |
| `cargo clippy --workspace --all-targets -- -D warnings` | Pass | Every workspace target completed with warnings denied. |
| `cargo test --workspace --all-targets` | Pass | All workspace targets passed. Editor reported 309 passing tests; scene reported 103 passing tests and one ignored manual migration test. |
| FBX dependency/import regressions | Pass | Six focused tests cover the committed chair, sibling `textures/`, `.fbm/`, missing bundles, parent traversal, and destination symlink containment. Thumbnail regressions cover terminal missing-texture state and first-render pipeline warmup. |
| `cargo validate-levels --project .` | Pass | 84 dependencies, six known nonblocking findings, zero blocking errors. The chair contributes one informational Authoring Override finding. |
| `cargo validate-samples --project .` | Pass | Five samples, 89 dependencies, the same six nonblocking findings, zero blocking errors. |
| Controlled Source Materials validation | Pass | Changing only the chair registry and static-manifest policies on top of `3e30c61` produced one `import.external_texture_missing` blocker for all three paths, then restoration returned to zero blockers. |
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed. |
## Native Acceptance
The exact debug binary built from `3e30c61` was launched as
`target/debug/editor --project .` under native Hyprland Wayland.
| Workflow | Result | Evidence |
|----------|--------|----------|
| First model-folder visit | Pass | The painted-chair model rendered on the first visit without manual thumbnail regeneration; the first offscreen PBR capture remained active through render-pipeline warmup. |
| Deliberately normalized chair | Pass | Selecting the committed Authoring Override chair showed one `3 missing \| override` dependency state and all three paths. Its mesh preview rendered neutrally, while source-material and missing-texture subassets settled to terminal warning icons instead of indefinite spinners. |
| Runtime log | Pass | The exact committed run emitted no stdout/stderr output, including no `bevy_asset`, `bevy_ufbx`, or path-not-found errors, and exited with code 0. |
| Checkout stability | Pass | Native startup, model browsing, thumbnail generation, and exit left `git status --short` empty. |
| Controlled broken fixture | Pass | On top of `3e30c61`, only the two chair `material_policy` fields were changed to `SourceMaterials`. The editor showed `Source Materials`, one red `3 missing` state, and terminal warning subassets. No asset/FBX/path error appeared; only two unrelated egui multi-pass layout warnings occurred at startup. |
| Fixture restoration | Pass | The two policy fields were restored to Authoring Override, `git status --short` returned empty, and `validate-levels` returned to zero blockers. |
## Native Evidence
![Authoring Override chair with a first-pass mesh thumbnail, terminal subasset warnings, and one visible dependency state](https://git.spacetrainclubhouse.com/attachments/a66b1844-2d17-4975-ba6e-1c0e00a02709)
- Gitea attachment asset 43: `blacksite-issue58-chair-normalized-3e30c61.png`, 1426x3384
RGB PNG, 1,802,863 bytes.
- SHA-256: `e492082f7eb3314bed6c97d424bc2281b125849552997f12931013a8e50630f2`.
![Controlled Source Materials fixture with three missing dependencies and terminal warning subassets](https://git.spacetrainclubhouse.com/attachments/a64cd69b-0fe7-4dc8-9f24-a333e018a682)
- Gitea attachment asset 44: `blacksite-issue58-chair-broken-source-materials-3e30c61.png`,
1426x3384 RGB PNG, 2,042,528 bytes.
- SHA-256: `759297276287a05bf678ea72e26159d5cb4613d917db447a1cbc1efa562fc831`.
Both images are ordinary Gitea issue attachments. This record does not use repository raw or Git
LFS pointer URLs. A direct header check returned HTTP 200, `Content-Type: image/png`, inline content
disposition, and the recorded byte length for each attachment.
## Release Use
The #58 source and native feature-level acceptance record is complete. A future production
candidate must rerun representative sibling-folder and `.fbm` imports, the deliberate override
case, and the broken Source Materials case from the exact nominated commit. This record does not
nominate a candidate or establish production readiness.
@@ -0,0 +1,72 @@
# Guarded Shutdown And Clean Savepoints Evaluation
**Date:** 2026-07-13
**Issue:** [Gitea #55](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/55)
**Branch:** `codex/guarded-shutdown-savepoints`
**Implementation commit:** `4b33f3235761fd0dd3daf219e5bbbaee884eb626`
**Release-candidate commit:** Not nominated
**Implementation validation:** **Pass**
**Native acceptance:** **Pass**
This record covers editor-owned shutdown authorization and per-document authored-content clean
checkpoints. The permanent architecture contract lives in
[ADR 0042](../../../adr/0042-guarded-editor-shutdown-and-document-savepoints.md). The automated
results below apply to the exact implementation commit. Native rows exercise the same shutdown
implementation after the unrelated toolbar fix disclosed below. Neither replaces the clean-checkout,
soak, or independent-signoff requirements for a future release candidate.
## Automated Verification
| Command or suite | Result | Evidence |
|------------------|--------|----------|
| `cargo fmt --all -- --check` | Pass | Formatting check completed without changes. |
| `git diff --check` | Pass | No whitespace errors. |
| `cargo clippy --workspace --all-targets -- -D warnings` | Pass | Workspace and all targets completed with warnings denied. |
| `cargo test --workspace --all-targets --no-fail-fast` | Pass | All workspace targets passed; the editor crate reported 282 passing tests. |
| Guarded shutdown regressions | Pass | Native close, menu/programmatic exit, cancel/discard, broker contention, late-authoring mutation, and secondary-window behavior are covered by 13 focused tests. |
| Save All regressions | Pass | Named and untitled tab sequencing, cancellation, conflict retention, duplicate destination rejection, and active-tab restoration are covered by six focused tests. |
| Project-switch regressions | Pass | Three focused tests cover guarded handoff, cancellation, and browser-spawn failure. |
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed. |
## Native Acceptance
The guarded-shutdown implementation under test is the source commit named above. The native debug
editor was rebuilt at `9e23ae731f95dc351ecc744d6ca61f6bc4467317` after the independently scoped
[UI action-safety fix](../scoped-ui-actions/) ([Gitea #57](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/57))
made the untitled-scene toolbar workflow reachable, then launched as
`target/debug/editor --project .`. Each row records an observed workflow rather than inferring
behavior from the automated suite.
| Workflow | Result | Evidence |
|----------|--------|----------|
| Undo back to the clean checkpoint | Pass | A scene mutation added the dirty marker; undo restored the canonical authored projection and cleared the marker. |
| Native window close, then **Cancel** | Pass | The dirty-document decision appeared; Cancel retained the dirty document and kept the editor running. |
| **File > Quit**, then **Discard** | Pass | The same guarded decision path ran and the editor process exited with code 0 without saving the dirty draft. |
| **File > Switch Project...** guard | Pass | A dirty document was intercepted by the shared shutdown decision before project-browser handoff. |
| Dirty named document, **Save All** | Pass | The named scene write completed before authorization and the editor then exited with code 0. |
| Clean untitled document close | Pass | No dirty-work decision was needed and the editor exited with code 0. |
| Dirty untitled document, **Save All**, then Save As continuation | Pass | **File > New Scene** created an untitled tab; the toolbar Cube action spawned authored content and marked it dirty. Native close followed by **Save All** opened KDE Save As in `assets/levels`; saving as `issue55_shutdown_qa.scn.ron` wrote a 1,986-byte scene and the editor exited with code 0. The QA scene was verified and removed. |
## Evidence Status
![Native guarded-shutdown decision over the Blacksite editor](https://git.spacetrainclubhouse.com/attachments/b9538ef6-25e0-46b0-9997-9a4311584893)
- Native modal capture: `/tmp/blacksite-issue55-shutdown-modal-4b33f32.png` (temporary staging;
3426x1384 RGB PNG, 1,656,602 bytes).
- SHA-256: `2ddb2571325e0d99f5559efd1ba3164845ffba64767833d4e5ad8d2925aedfb5`.
- Gitea #55 native attachment: asset 36, uploaded through the issue attachment API.
The Gitea copy was uploaded as an ordinary issue attachment. No repository PNG or LFS raw URL is
claimed by this evaluation.
## Release Use
The #55 source and native feature-level acceptance record is complete. A future production candidate
must still rerun these workflows from the exact nominated commit; this record does not nominate a
candidate or establish production readiness.
@@ -4,15 +4,17 @@ Date: 2026-07-12
![Three selected props settled on the committed placement floor](physics-placement-settled.png) ![Three selected props settled on the committed placement floor](physics-placement-settled.png)
The native Wayland editor is shown with the committed The native Wayland editor is shown with the 2026-07-12 revision of
`assets/levels/physics_placement_showcase.scn.ron` fixture. Placement Prop A, B, and C were `assets/levels/physics_placement_showcase.scn.ron`. At that revision, Placement Prop A, B, and C were
multi-selected and released from three different heights through the hand/down-arrow action in the multi-selected and released from three different heights through the hand/down-arrow action in the
existing horizontal viewport toolbar. existing horizontal viewport toolbar. The fixture now exposes those stable actor IDs as Placement
Cuboid, Placement Sphere, and Placement Capsule; its distinct-shape rerun is tracked by the
[sample-pack evaluation](../sample-regression-pack/).
## Acceptance ## Acceptance
- All three props used the hydrated Avian cuboid colliders and settled on Placement Floor after - In the recorded revision, all three props used hydrated Avian cuboid colliders and settled on
1.5 simulated seconds. Placement Floor after 1.5 simulated seconds.
- During preview the HUD reported selection count, simulated time, and Settled state; transform - During preview the HUD reported selection count, simulated time, and Settled state; transform
gizmos and viewport picking did not compete with the modal tool. gizmos and viewport picking did not compete with the modal tool.
- Escape restored every starting transform and left history empty. - Escape restored every starting transform and left history empty.
@@ -25,4 +27,3 @@ existing horizontal viewport toolbar.
error after the stale-binding fix. error after the stale-binding fix.
Packaged-runtime tests remain intentionally deferred by project-owner request. Packaged-runtime tests remain intentionally deferred by project-owner request.
@@ -1,8 +1,8 @@
# Production-Readiness Acceptance Matrix # Production-Readiness Acceptance Matrix
**Matrix version:** 0.2 **Matrix version:** 0.7
**Last audit:** 2026-07-12 **Last audit:** 2026-07-13
**Release-candidate commit:** Not nominated **Release-candidate commit:** Not nominated
@@ -30,21 +30,21 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| ID | Requirement | State | Current evidence and gap | | ID | Requirement | State | Current evidence and gap |
|----|-------------|-------|--------------------------| |----|-------------|-------|--------------------------|
| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Collaborative file safety `#49` and non-blocking native dialogs `#52` passed live acceptance. Candidate-specific end-to-end reruns remain. | | G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Collaborative file safety `#49`, non-blocking native dialogs `#52`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, deterministic asset fingerprints `#56`, and [external FBX dependencies](../fbx-external-texture-dependencies/) `#58` have feature-level source/native acceptance. #56 additionally passed a fresh LFS checkout, both validators, mtime-only drift, and artifact hash stability at `cbd380a`; #58 passed both override and blocking dependency states at `3e30c61`. Candidate-specific end-to-end reruns remain. |
| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, renderer/material foundation `#51`, Material Library, targeted material drops, terrain `#22`-`#24`, physics placement `#25`, and build foundations are implemented with source/live fixtures. Brush acceptance `#37` remains incomplete. Packaged testing is owner-deferred. | | G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Partial | The [five-area sample pack](../sample-regression-pack/) passed source and native acceptance on exact implementation commit `d52cc2e`, including Brush, Material, Terrain, Physics Placement, and Rendering. No release candidate is nominated, brush acceptance `#37` remains open, and combined animation/audio/navigation/PIE/build evidence is incomplete. Packaged testing is owner-deferred. |
| G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | Source implementation and focused evidence are complete in [operator regression testing](../../operator-regression-testing.md) and the [operator-invariants evaluation](../operator-invariants/); Gitea `#33` is ready to close. A clean, exact-candidate rerun is still required for `Pass`. | | G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | Source implementation and focused evidence are complete in [operator regression testing](../../operator-regression-testing.md) and the [operator-invariants evaluation](../operator-invariants/); Gitea `#33` closed at `c55f347`. A clean, exact-candidate rerun is still required for `Pass`. |
| G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. | | G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. |
| G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. | | G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. |
| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) exists and local source/headless checks have passed during feature work, but no clean-checkout candidate run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. | | G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) hydrates LFS, runs both project/sample content gates, and asserts a pristine checkout. The [#56 feature run](../deterministic-asset-fingerprints/) passed native startup and both validators from a fresh LFS-hydrated worktree at `cbd380a`; [#58](../fbx-external-texture-dependencies/) passed both validators and clean native startup at `3e30c61`. No release candidate is nominated and no candidate CI run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. |
| G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. | | G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. |
| G8 | Known limitations have severity/workaround and no P0 blocker remains | Fail | Limitations are distributed across feature docs rather than one candidate ledger. The remaining open P0 implementation blocker is `#32`; `#50` cannot close while it remains. Operator invariants `#33`, renderer foundation `#51`, roadmap audit `#35`, Material Library `#16`, targeted drops `#18`, collaborative safety `#49`, and dialog responsiveness `#52` are complete. Property-block application `#53` is P1; dynamic deformed Solari geometry `#54` is a documented P2 limitation with Forward/raster fallback. | | G8 | Known limitations have severity/workaround and no P0 blocker remains | Partial | Sample-pack gap `#32`, guarded shutdown/savepoints `#55`, scoped UI action safety `#57`, deterministic imported-asset fingerprints `#56`, and external FBX dependency handling `#58` have complete feature-level acceptance; no known P0 implementation blocker remains. A consolidated candidate limitations ledger and exact-candidate rerun are still missing. Property-block application `#53` remains P1; dynamic deformed Solari geometry `#54` is a documented P2 limitation with Forward/raster fallback. |
## Deliverables ## Deliverables
| ID | Deliverable | State | Evidence or next action | | ID | Deliverable | State | Evidence or next action |
|----|-------------|-------|-------------------------| |----|-------------|-------|-------------------------|
| D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.2. | | D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.6. |
| D2 | Release-candidate representative project and reproducible validation commands | Missing | Expand the committed project/regression pack through `#32`, including terrain and physics-placement samples, then nominate an exact commit. | | D2 | Release-candidate representative project and reproducible validation commands | Partial | The committed [sample regression pack](../sample-regression-pack/), commands, exact-implementation native evidence, and [fresh-checkout fingerprint protocol](../deterministic-asset-fingerprints/) exist. Nominate a release candidate and rerun the complete set from a clean LFS-hydrated checkout. |
| D3 | Signed milestone comment linking evidence, limitations, and exact commit | Missing | Post only after G1-G8 pass; no candidate exists yet. | | D3 | Signed milestone comment linking evidence, limitations, and exact commit | Missing | Post only after G1-G8 pass; no candidate exists yet. |
## Workflow Coverage ## Workflow Coverage
@@ -55,11 +55,13 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| Scene save, autosave, recovery | Implemented | Not rerun | | Scene save, autosave, recovery | Implemented | Not rerun |
| Hierarchy parenting and prefab structure | Implemented | Not rerun | | Hierarchy parenting and prefab structure | Implemented | Not rerun |
| Multi-scene composition | Implemented | Not rerun | | Multi-scene composition | Implemented | Not rerun |
| Five-area editor sample pack | Implemented with manifest, native menu, typed scene gate, and headless validation | Exact-implementation source/native acceptance passed at `d52cc2e`; not rerun as one release candidate |
| Brush blockout/edit/CSG | Implemented foundation; `#37` open | Not signed off | | Brush blockout/edit/CSG | Implemented foundation; `#37` open | Not signed off |
| Material catalog and assignment | Renderer/material foundation `#51`, Material Library, and exact targeted drops accepted; optional property-block promotion is `#53` | Not rerun as one candidate | | Material catalog and assignment | Renderer/material foundation `#51`, Material Library, and exact targeted drops accepted; optional property-block promotion is `#53` | Not rerun as one candidate |
| Terrain authoring | `#22`-`#24` source/live acceptance complete; M3 closed | Pass; packaged-runtime acceptance owner-deferred | | Rendering volumes and look development | Deterministic visible rendering fixture is in the sample pack | Not rerun as one candidate |
| Physics placement | `#25` source/live acceptance complete | Pass; packaged-runtime acceptance owner-deferred | | Terrain authoring | `#22`-`#24` source/live acceptance complete; M3 closed | Feature-level live acceptance exists; not rerun as one candidate. Packaged-runtime acceptance owner-deferred. |
| Collider authoring and diagnostics | `#26` source/live acceptance complete | Pass; packaged-runtime acceptance owner-deferred | | Physics placement | `#25` source/live acceptance complete | Feature-level live acceptance exists; not rerun as one candidate. Packaged-runtime acceptance owner-deferred. |
| Collider authoring and diagnostics | `#26` source/live acceptance complete | Feature-level live acceptance exists; not rerun as one candidate. Packaged-runtime acceptance owner-deferred. |
| Animation | Implemented | Not rerun | | Animation | Implemented | Not rerun |
| Audio | Implemented | Not rerun | | Audio | Implemented | Not rerun |
| Navigation | Implemented | Not rerun | | Navigation | Implemented | Not rerun |
@@ -67,6 +69,10 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| Build/package/runtime | Implemented foundation | Deferred by owner | | Build/package/runtime | Implemented foundation | Deferred by owner |
| Collaborative file safety | Implemented; `#49` closed with live external-change acceptance | Not rerun as one candidate | | Collaborative file safety | Implemented; `#49` closed with live external-change acceptance | Not rerun as one candidate |
| Native file/folder dialogs | Implemented; `#52` closed with live 12-second compositor-responsiveness hold | Not rerun as one candidate | | Native file/folder dialogs | Implemented; `#52` closed with live 12-second compositor-responsiveness hold | Not rerun as one candidate |
| Guarded shutdown and clean savepoints | Implemented; `#55` source validation and all seven native workflows passed at source implementation `4b33f32` | Feature-level acceptance complete; not rerun as one candidate |
| Scoped UI action safety | Implemented; `#57` source validation, six focused regressions, selection precedence, and native toolbar/Inspector/diagnostics workflows passed at `9e23ae7` | Feature-level acceptance complete; not rerun as one candidate |
| Imported asset identity and generated artifacts | Implemented; `#56` uses shared BLAKE3 fingerprints, byte-preserving semantic publication, and normalized registry order | Fresh LFS checkout, native startup, mtime-only drift, validators, and artifact hashes passed at `cbd380a`; not rerun as one candidate |
| FBX external texture dependencies | Implemented; `#58` uses one sandboxed resolver, transactional bundle import, labeled loader images, authoritative manifests, and explicit Source Materials/Authoring Override semantics | Sibling/`.fbm`/missing/traversal/symlink tests, both validators, exact-implementation native chair QA, and a controlled broken fixture passed at `3e30c61`; not rerun as one candidate |
## Candidate Validation Commands ## Candidate Validation Commands
@@ -81,6 +87,7 @@ cargo clippy --workspace --all-targets -- -D warnings
cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings
cargo test --workspace cargo test --workspace
cargo validate-levels --project . cargo validate-levels --project .
cargo validate-samples --project .
cargo bake-navigation --project . --check cargo bake-navigation --project . --check
``` ```
@@ -92,8 +99,9 @@ package hash verification, and packaged-runtime smoke protocol used for the cand
The final candidate must run for eight continuous hours against the representative project. The The final candidate must run for eight continuous hours against the representative project. The
record must sample process RSS, GPU memory, target-directory size, recovery generations, background record must sample process RSS, GPU memory, target-directory size, recovery generations, background
job counts, and error/warning totals at least every five minutes. Exercise scene switching, save and job counts, and error/warning totals at least every five minutes. Exercise scene switching, save and
recovery, asset refresh, material editing, brush/terrain/physics tools, animation/audio/navigation, recovery, asset refresh, all five sample-pack scenes, material editing, brush/terrain/physics tools,
PIE transitions, and build UI cancellation without replacing the candidate during the run. animation/audio/navigation, PIE transitions, and build UI cancellation without replacing the
candidate during the run.
A pass requires no unrecoverable editor failure, no lost authored work, no unbounded upward trend in A pass requires no unrecoverable editor failure, no lost authored work, no unbounded upward trend in
steady-state resource use, bounded recovery/cache behavior, and a triaged explanation for every steady-state resource use, bounded recovery/cache behavior, and a triaged explanation for every
@@ -0,0 +1,71 @@
# Sample Regression Pack Evaluation
**Date:** 2026-07-13
**Issue:** [Gitea #32](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/32)
**Implementation commit:** `d52cc2e3b72c908d192ed9e9f49306c25367599b`
**Release-candidate commit:** Not nominated
**Implementation validation:** **Pass**
**Native visual acceptance:** **Pass**
This record separates source/fixture verification from release-candidate acceptance. The exact
implementation commit above passed the five-area native protocol on a clean tracked worktree. These
results do not transfer to a later release-candidate commit.
## Source Evidence
| Check | Result | Evidence |
|-------|--------|----------|
| Manifest contract | Pass | Schema v1 contains one ordered entry for Brush, Material, Terrain, Physics Placement, and Rendering, with stable IDs and nonempty checks. |
| Authored scene fixtures | Pass | All five scene paths exist; actors use stable IDs and each scene contains its required authored feature. |
| Project validation | Pass | `cargo validate-levels --project .` reported 81 dependencies, five known nonblocking import/platform findings, and zero blocking errors on 2026-07-13. |
| Typed no-GPU deserialization | Pass | `cargo test -p editor every_manifest_sample_typed_deserializes_without_a_gpu --lib`: one passed, zero failed, 257 filtered out. |
| Sample-pack validation | Pass | `cargo validate-samples --project .`: five ordered samples, 86 dependencies, five known nonblocking findings, zero blocking errors. |
| Clean-checkout CI | Pending | The exact candidate must hydrate LFS and pass both content gates. Current Gitea does not expose an Actions run endpoint for this repository. |
## Native Protocol
Open every row through **File > Open Sample**, not through a typed filesystem path. Capture native
screenshots only after confirming the viewport is nonblank and correctly framed.
| Sample | Required native interaction and visual result | Result |
|--------|-----------------------------------------------|--------|
| Brush Blockout | Foundation, material-face tower, and red subtractive marker are distinct; enter brush edit and cancel one edit or clip preview without leaving helpers | Pass - selected one tower face in Brush Clip, observed the magenta preview, then canceled with no history or helper leak. |
| Material Lab | Concrete cube, custom sphere, instance block, and emissive panel are visible; perform one exact primitive material drop and undo | Pass - dropped `surface_tint_instance` on `Concrete Reference / Surface`; one history entry was created and Ctrl+Z restored the exact prior material. |
| Terrain Authoring | Hill chunks and two material layers render; perform and cancel one sculpt stroke and one paint stroke | Pass - Concrete/Surface Tint rendered visibly under active Solari through the forward raster boundary; both stroke cancels restored data and left history clean. |
| Physics Placement | Cuboid, sphere, and capsule settle on the floor; cancel restores all three, then commit/undo behaves as one transaction | Pass - three props settled in 2.3 seconds; cancel restored the airborne transforms, and the second run committed one `Move Selection` entry that Ctrl+Z restored. |
| Rendering Lab | Red/cyan/amber anchors and emissive strip render; camera traversal visibly changes vignette, fog, and exposure ownership | Pass - HUD ownership reached Foggy courtyard 73%/2 overrides, Cave mouth 100%/2 overrides, and Vignette demo 68% with the expected visible changes. |
For each row, inspect the status strip, Diagnostics panel, and process log for missing references,
hydration errors, render errors, helper leaks, or operator failures. Attach native images to the Gitea
issue as ordinary uploaded attachments rather than embedding repository raw URLs. A committed
original may remain beside this record through Git LFS under the shared evaluation policy.
## Native Environment And Artifacts
- Arch Linux `7.1.3-arch1-1`, Hyprland `0.55.4`, native Wayland.
- NVIDIA GeForce RTX 3080 Ti, driver `610.43.03`.
- Bevy `0.19.0`; the viewport reported the effective `Solari` path throughout the pass.
- Exact binary: `target/debug/editor --project .`, built from the implementation commit above.
- Process log: no warnings or errors across all five menu opens and interactions.
- [Gitea issue comment #1057](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/32#issuecomment-1057)
embeds full-resolution 3426x1384 PNG uploads, not repository/LFS raw links:
`blacksite-brush-d52cc2e.png`
(`sha256:3853bb51a70320b95af2cc48a1609251defc22705fb5f27fd3b1ab434f71877f`),
`blacksite-terrain-solari-d52cc2e.png`
(`sha256:8ee4e5d5c40436a5719fbec34deaef10f5bcb79748b052268781c29468e1ef7b`), and
`blacksite-rendering-vignette-d52cc2e.png`
(`sha256:67a09743f86439adf98ad2cf9b9d91041f89954aea2b8f29c29bbf10ead8c000`).
## Release Use
A future candidate may mark this evaluation fully passed only when the exact nominated commit has:
1. Passed typed scene deserialization, `validate-levels`, and `validate-samples` from a clean,
LFS-hydrated checkout.
2. Opened all five entries through the native menu and completed the interactions above.
3. Recorded the commit, machine profile, commands, exit codes, logs, and native attachments.
@@ -0,0 +1,68 @@
# Scoped UI Action Safety Evaluation
**Date:** 2026-07-13
**Issue:** [Gitea #57](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/57)
**Implementation commit:** `9e23ae731f95dc351ecc744d6ca61f6bc4467317`
**Release-candidate commit:** Not nominated
**Source validation:** **Pass**
**Native acceptance:** **Pass**
This record covers synchronous editor actions invoked while the egui host scopes `UiState` out of
the Bevy `World`. The implementation keeps callback-owned state in independently registered
resources, passes viewport data into toolbar/navigation actions, routes cross-panel selection and
tab requests through explicit APIs, and reconciles the complete selection slice so a direct UI
selection takes precedence over a stale deferred request.
## Automated Verification
| Command or suite | Result | Evidence |
|------------------|--------|----------|
| `cargo fmt --all -- --check` | Pass | Formatting check completed without changes. |
| `git diff --check` | Pass | No whitespace errors. |
| `cargo clippy --workspace --all-targets -- -D warnings` | Pass | Workspace and all targets completed with warnings denied. |
| `cargo test --workspace --all-targets --no-fail-fast` | Pass | All workspace targets passed; the editor crate reported 290 of 290 tests passing. |
| Scoped-action regressions | Pass | Six focused regressions cover history multi-selection, diagnostics selection, Inspector collapse and asset reveal state, primitive spawn, and navigation spawn while `UiState` is scoped out. |
| Selection precedence | Pass | Full-slice reconciliation preserves a direct primary or secondary UI selection over stale single- or multi-selection requests. |
| Independent re-review | Pass | The post-fix review found no remaining blockers. |
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed. |
## Native Acceptance
The exact rebuilt debug binary from the implementation commit was launched as
`target/debug/editor --project .`.
| Workflow | Result | Evidence |
|----------|--------|----------|
| Toolbar authoring actions | Pass | After **File > New Scene**, Cube, Ramp, Sphere, Point Light, and Navigation Bounds all spawned. Selection, transform gizmo, viewport overlay, hierarchy, and Inspector stayed synchronized. |
| Inspector state | Pass | Collapsing the Transform component persisted across subsequent UI rendering and selection work. |
| Cross-panel diagnostics action | Pass | **Window > Brush Diagnostics > Select** kept the editor live and synchronized the selected actor across hierarchy, viewport, and Inspector. |
| Guarded shutdown | Pass | The dirty native-close decision accepted **Discard** and the editor exited with code 0. |
## Native Evidence
![Scoped toolbar actions with authored actors selected in the live editor](https://git.spacetrainclubhouse.com/attachments/d265651b-aa8e-4ea5-841c-1fa8eb622766)
- Gitea attachment asset 37: `blacksite-issue57-scoped-ui-actions.png`, 3426x1384 RGB PNG,
890,021 bytes.
- SHA-256: `4225aca19268e4817148507e95cdad56a5f18734fd69e2fe5702df1dc304142e`.
![Brush Diagnostics Select synchronized hierarchy, viewport, and Inspector](https://git.spacetrainclubhouse.com/attachments/ba176d82-fb2f-403b-a71c-108de9649f11)
- Gitea attachment asset 38: `blacksite-issue57-diagnostics-select.png`, 3426x1384 RGB PNG,
1,418,849 bytes.
- SHA-256: `40422be59766a3e61005973c315d0fd6f663dd2d227aa92055fa2aa2e91320c3`.
Both images were uploaded as ordinary Gitea issue attachments; this record does not use repository
raw or LFS pointer URLs.
## Release Use
The #57 source and native feature-level acceptance record is complete. A future production candidate
must still rerun representative toolbar, Inspector, diagnostics, selection, and guarded-exit paths
from the exact nominated commit. This record does not nominate a candidate or establish production
readiness.
+5
View File
@@ -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 discarding the active document. Save and Save As affect the active tab, while project switching
offers to save every modified tab. 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 ## Composition workflow
The **Composition** menu beside the tabs edits the active scene's persisted `SceneComposition`: The **Composition** menu beside the tabs edits the active scene's persisted `SceneComposition`:
+9
View File
@@ -16,6 +16,13 @@ loop or editor rendering.
- Collaborative Save As performs the same revision and destination checks after selection. - 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 - 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. 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 ## 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. 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). 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 Live native-Wayland acceptance is recorded in the
[native-dialog responsiveness evaluation](evaluations/native-dialog-responsiveness/). [native-dialog responsiveness evaluation](evaluations/native-dialog-responsiveness/).
+4 -3
View File
@@ -30,9 +30,10 @@ and placement status agree about missing, invalid, stale, disabled, or trigger c
ten-second simulated-time limit stops unstable previews while ten-second simulated-time limit stops unstable previews while
leaving explicit commit and cancel available. leaving explicit commit and cancel available.
`assets/levels/physics_placement_showcase.scn.ron` is the committed acceptance fixture. Select `assets/levels/physics_placement_showcase.scn.ron` is the Physics Placement entry in the committed
**Placement Prop A**, **B**, and **C** together, start physics placement, and verify that the three [sample regression pack](sample-regression-pack.md). Select **Placement Cuboid**, **Placement
different shapes settle on **Placement Floor** as one commit/cancel transaction. Sphere**, and **Placement Capsule** together, start physics placement, and verify that the three
distinct collider cases settle on **Placement Floor** as one commit/cancel transaction.
The clock and transaction boundary are specified by The clock and transaction boundary are specified by
[ADR 0041](../adr/0041-transactional-editor-physics-placement.md). [ADR 0041](../adr/0041-transactional-editor-physics-placement.md).
+2 -1
View File
@@ -2,7 +2,8 @@
## Shipped ## Shipped
- Stable asset registry (`assets/.index/registry.ron`) with import settings - Stable asset registry (`assets/.index/registry.ron`) with import settings and content-addressed
model/texture/audio source fingerprints
- Prefab instances (`PrefabInstance`) + save-as-prefab workflow - Prefab instances (`PrefabInstance`) + save-as-prefab workflow
- Unsaved-scene guards on New/Open/Recent - Unsaved-scene guards on New/Open/Recent
- Hierarchy additive select, reparent/unparent undo, multi-entity gizmo delta - Hierarchy additive select, reparent/unparent undo, multi-entity gizmo delta
+4 -1
View File
@@ -89,7 +89,10 @@ Shipped examples: `post_fx/vignette.ron`, `post_fx/chromatic_aberration.ron`, `r
## Example level ## Example level
Open `assets/levels/rendering_showcase.scn.ron` for fog, exposure, and vignette volume examples. Open **File > Open Sample > Rendering Lab** for the committed rendering fixture. Its red sphere,
cyan cube, amber block, and emissive horizon make the adjacent vignette, fog, and dark-exposure zones
visually comparable while the volume actors exercise stable ownership, profile, and fullscreen-effect
references. See the [sample regression pack](sample-regression-pack.md) for the native QA protocol.
## Troubleshooting ## Troubleshooting
+5 -4
View File
@@ -119,11 +119,12 @@ Phased work for the in-process editor (`crates/editor`). Status reflects the cur
| Item | Status | Notes | | Item | Status | Notes |
|------|--------|-------| |------|--------|-------|
| `asset_db.rs` registry | Done | Stable UUIDs by path; import settings in details | | `asset_db.rs` registry | Done | Stable UUIDs by path/content, deterministic model/texture/audio BLAKE3 fingerprints, normalized publication order, and import settings in details |
| Model import formats | Done | glTF/GLB + FBX (binary); `.fbm` sidecar copy on import | | Model import formats | Done | glTF/GLB + binary FBX; sandboxed `textures/`/`.fbm/` discovery and transactional referenced-bundle copy |
| Thumbnails | Done | Textures via asset load; glTF albedo fast-path; FBX/untextured models via offscreen studio | | Thumbnails | Done | Textures via asset load; glTF albedo fast-path; direct neutral FBX geometry; preflighted source-material dependency state |
| Import settings per asset | Done | Scale/collider/LOD in registry + details pane | | Import settings per asset | Done | Scale/collider/LOD in registry + details pane |
| Prefab workflow | Done | Shared stable nested property/component/structural overrides, recursive validation, committed variant fixtures, transactional source Apply, conflict recovery, and undoable outer unpack/recursive local conversion passed headless, packaged-runtime, and live editor acceptance in Gitea #43 | | Prefab workflow | Done | Shared stable nested property/component/structural overrides, recursive validation, committed variant fixtures, transactional source Apply, conflict recovery, and undoable outer unpack/recursive local conversion passed headless, packaged-runtime, and live editor acceptance in Gitea #43 |
| Curated editor regression samples | Done | Versioned five-area manifest, dedicated brush/material labs, strengthened terrain/physics/rendering fixtures, **File > Open Sample**, typed scene coverage, and `validate-samples` release gate in Gitea #32 |
## Phase 6 — Extensibility ## Phase 6 — Extensibility
@@ -150,7 +151,7 @@ with implementation sequencing in
| Milestone | Exit condition | Status | | 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 | | 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. #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. | | M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#49 are complete after source, headless, and native acceptance. P0 #55 is complete at source implementation `4b33f32`, follow-on P0 #57 scoped UI action safety is complete at `9e23ae7`, and P1 #56 deterministic imported-asset fingerprints pass workspace, clean-checkout, validator, hash-stability, and native acceptance at `cbd380a`. No known P0 implementation blocker remains, but #50 is still the final candidate gate and production readiness is not established. Packaged acceptance is deferred until requested by the project owner. |
Production readiness is not inferred from feature count. Gitea Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50) [`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
+57
View File
@@ -0,0 +1,57 @@
# Editor Sample Regression Pack
The editor sample regression pack is the committed, deterministic first stop for content and native
viewport QA. Its source of truth is `assets/samples/editor_samples.ron`; manifest order is also the
order shown by **File > Open Sample** and by headless reports.
## Open And Exercise A Sample
1. Open **File > Open Sample** and choose the relevant area.
2. Confirm the scene opens in a normal scene tab and the viewport contains the expected anchors.
3. Perform the checks listed in the manifest and the table below.
4. Watch the status strip and Diagnostics panel for missing references, hydration failures, or
operator errors.
5. Use **Save As** before destructive experimentation. The committed samples are regular project
scenes, not disposable or read-only copies.
An invalid or unavailable manifest leaves an actionable disabled item in the menu. It must not
silently fall back to another scene.
## Pack Contents
| Area | Scene and visual composition | Representative checks |
|------|------------------------------|-----------------------|
| Brush | `brush_blockout.scn.ron`: broad concrete foundation, tall additive brush with a contrasting shared-material top face, red rotated subtractive marker | Select object and face targets; enter brush edit; exercise draw/clip/CSG preview and cancel; verify shared face material resolution |
| Material | `material_lab.scn.ron`: neutral floor, concrete cube, blue custom-surface sphere, rotated Material Instance block, cyan emissive backdrop | Inspect shared Material/Instance paths; target a primitive with a Material drop; compare standard, custom, and emissive hydration |
| Terrain | `terrain_authoring_showcase.scn.ron`: asymmetric 5x5 hill, four deterministic chunks, two painted shared-material layers | Sculpt and paint preview/cancel; inspect normalized weights and layer refs; verify generated selection and collider state |
| Physics Placement | `physics_placement_showcase.scn.ron`: cuboid, sphere, and tall capsule above a static floor | Multi-select all three props; settle; cancel and compare exact starting transforms; repeat, commit, undo, and redo as one group |
| Rendering | `rendering_showcase.scn.ron`: red sphere, cyan cube, amber block, emissive horizon, and three adjacent vignette/fog/exposure volumes | Move the camera through all zones; inspect active-volume ownership; verify profile/fullscreen-effect refs and visible transitions |
All authored sample actors have stable `ActorId` values. Generated hydration children are deliberately
absent from the committed scene documents.
## Headless Validation
Run both gates from the project root with Git LFS content hydrated:
```bash
cargo validate-levels --project .
cargo validate-samples --project .
```
`validate-levels` remains the authoritative project dependency/finding report. `validate-samples`
adds the pack contract: schema and safe paths, exactly one entry per required area, stable actor IDs,
authoring-only scene data, required area components, and nonempty operator checks. Either command
must exit nonzero on a blocking finding. Use `--json` when attaching machine-readable evidence.
## Maintenance Contract
- Keep exactly the five areas `Brush`, `Material`, `Terrain`, `PhysicsPlacement`, and `Rendering`.
- Treat manifest IDs as persistent automation keys; rename labels instead of IDs.
- Keep scene paths project-relative, inside `assets/levels/`, and free of symlink or traversal escapes.
- When a sample changes, update its manifest summary/checks and this visual-composition table in the
same change.
- Run the typed no-GPU scene test plus both validation commands before native QA.
- Record exact-commit native results under
[evaluations/sample-regression-pack/](evaluations/sample-regression-pack/). Implementation checks
from a dirty worktree do not satisfy release-candidate acceptance.
+5 -1
View File
@@ -13,10 +13,14 @@ or credentials.
## Restart behavior ## 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 - **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 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. 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 - Dirty scene data remains governed by the independent scene recovery workflow in
[ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md). [ADR 0023](../adr/0023-transactional-scene-persistence-and-recovery.md).
+8 -5
View File
@@ -38,10 +38,12 @@ weight to the remaining channels. Every sample stays normalized to 255, the terr
or amber footprint previews the brush, and release records one undo entry. Escape or right-click or amber footprint previews the brush, and release records one undo entry. Escape or right-click
restores the exact pre-stroke weights or closes the idle tool. restores the exact pre-stroke weights or closes the idle tool.
`assets/levels/terrain_authoring_showcase.scn.ron` is the deterministic foundation fixture. Its 5×5 `assets/levels/terrain_authoring_showcase.scn.ron` is the Terrain entry in the deterministic
[sample regression pack](sample-regression-pack.md). Its 5×5
grid forms an asymmetric hill split into four 2×2-quad chunks. It validates chunk boundaries, grid forms an asymmetric hill split into four 2×2-quad chunks. It validates chunk boundaries,
normals, selection through generated children, collider generation, inspector state, and save normals, selection through generated children, collider generation, inspector state, and save
stripping without requiring external assets. stripping. Height geometry is inline, while its committed shared Material and Material Instance
references deliberately validate terrain dependency resolution and layer transport.
## Data And Hydration ## Data And Hydration
@@ -57,9 +59,10 @@ stripping without requiring external assets.
fallback rather than missing geometry. fallback rather than missing geometry.
- Generated `HydratedTerrainChunk` children own mesh, optional trimesh collider, and shadow state. - Generated `HydratedTerrainChunk` children own mesh, optional trimesh collider, and shadow state.
They are runtime-only and never serialized as authored actors. They are runtime-only and never serialized as authored actors.
- Foundation chunks are explicitly excluded from Solari submission and remain raster-visible while - Foundation chunks are explicitly excluded from Solari submission and force their layer blend
Auto/Solari is active. Raster material-layer parity is shipped; matching Solari terrain evaluation through Bevy's forward opaque raster path while Auto/Solari is active. Raster material-layer
remains explicit future work, and the editor never substitutes a semantically different proxy. parity is shipped; matching Solari terrain evaluation remains explicit future work, and the editor
never substitutes a semantically different proxy.
The terrain foundation is recorded in [ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md), The terrain foundation is recorded in [ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md),
and layer weight persistence/render transport in and layer weight persistence/render transport in
+1
View File
@@ -25,6 +25,7 @@ pub mod material;
pub mod mesh; pub mod mesh;
pub mod node; pub mod node;
pub mod scene; pub mod scene;
pub mod texture;
pub mod types; pub mod types;
pub mod utils; pub mod utils;
+118 -66
View File
@@ -5,11 +5,12 @@ use crate::material::process_materials;
use crate::mesh::process_meshes; use crate::mesh::process_meshes;
use crate::node::{process_nodes, process_skins}; use crate::node::{process_nodes, process_skins};
use crate::scene::build_scene; use crate::scene::build_scene;
use crate::texture::external_texture_path_report;
use crate::types::{Fbx, FbxAxisSystem, FbxMeta, Handedness}; use crate::types::{Fbx, FbxAxisSystem, FbxMeta, Handedness};
use bevy::asset::{io::Reader, AssetLoader, LoadContext, RenderAssetUsages}; use bevy::asset::{io::Reader, AssetLoader, LoadContext, RenderAssetUsages};
use bevy::prelude::*; use bevy::prelude::*;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::collections::HashMap; use std::collections::{BTreeSet, HashMap};
/// Settings for FBX file loading. /// Settings for FBX file loading.
/// ///
@@ -74,77 +75,128 @@ impl AssetLoader for FbxLoader {
return Err(FbxError::InvalidData("FBX file too small".to_string())); return Err(FbxError::InvalidData("FBX file too small".to_string()));
} }
// Parse with ufbx
// Provide the asset path as a filename hint so ufbx can compute relative_filename
let filename_hint = load_context.path().path().to_string_lossy().to_string(); let filename_hint = load_context.path().path().to_string_lossy().to_string();
let root = ufbx::load_memory( let root = parse_fbx(&bytes, &filename_hint)?;
&bytes, let texture_report = external_texture_path_report(&root);
ufbx::LoadOpts { if texture_report.paths.is_empty() {
target_unit_meters: 1.0, if !texture_report.errors.is_empty() {
target_axes: ufbx::CoordinateAxes::right_handed_y_up(), warn_texture_failures(
filename: ufbx::StringOpt::Ref(&filename_hint), load_context.path(),
..Default::default() texture_report.errors.iter().map(ToString::to_string),
}, );
) }
.map_err(|e| FbxError::UfbxError(format!("{:?}", e)))?; return process_scene(&root, settings, load_context, &HashMap::new());
let scene: &ufbx::Scene = &*root; }
// Process meshes // `ufbx::Scene` is not Send, so finish discovery and drop it before awaiting asset I/O.
let (meshes, named_meshes, mesh_transforms, mesh_material_info) = drop(root);
process_meshes(scene, settings, load_context)?; let mut failures = texture_report
.errors
.iter()
.map(ToString::to_string)
.collect::<BTreeSet<_>>();
let mut external_texture_bytes = HashMap::new();
let asset_path = load_context.path().clone();
for relative_path in texture_report.paths {
let resolved_path = match asset_path.resolve_embed_str(&relative_path) {
Ok(path) => path,
Err(error) => {
failures.insert(format!("{relative_path} ({error})"));
continue;
}
};
match load_context.read_asset_bytes(resolved_path.clone()).await {
Ok(bytes) => {
external_texture_bytes.insert(relative_path, bytes);
}
Err(error) => {
failures.insert(format!("{resolved_path} ({error})"));
}
}
}
if !failures.is_empty() {
warn_texture_failures(load_context.path(), failures);
}
// Process materials and textures let root = parse_fbx(&bytes, &filename_hint)?;
let (materials, named_materials) = if !settings.load_materials.is_empty() { process_scene(&root, settings, load_context, &external_texture_bytes)
process_materials(scene, settings, load_context)?
} else {
(Vec::new(), HashMap::new())
};
// Process nodes and hierarchy
let (nodes, named_nodes, node_map) = process_nodes(scene, &meshes, load_context)?;
// Process skins
let (skins, named_skins) = process_skins(scene, &node_map, load_context)?;
// Build scene
let scene_handle = build_scene(
scene,
&meshes,
&materials,
&named_materials,
&mesh_transforms,
&mesh_material_info,
settings,
load_context,
)?;
// Extract metadata
let metadata = FbxMeta::default();
// Build final FBX asset
Ok(Fbx {
scenes: vec![scene_handle.clone()],
named_scenes: HashMap::new(),
meshes,
named_meshes,
materials,
named_materials,
nodes,
named_nodes,
skins,
named_skins,
default_scene: Some(scene_handle),
axis_system: FbxAxisSystem {
up: Vec3::Y,
front: Vec3::Z,
handedness: Handedness::Right,
},
unit_scale: 1.0,
metadata,
})
} }
fn extensions(&self) -> &[&str] { fn extensions(&self) -> &[&str] {
&["fbx"] &["fbx"]
} }
} }
fn parse_fbx(bytes: &[u8], filename_hint: &str) -> Result<ufbx::SceneRoot, FbxError> {
ufbx::load_memory(
bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
filename: ufbx::StringOpt::Ref(filename_hint),
..Default::default()
},
)
.map_err(|error| FbxError::UfbxError(format!("{error:?}")))
}
fn process_scene(
scene: &ufbx::Scene,
settings: &FbxLoaderSettings,
load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result<Fbx, FbxError> {
let (meshes, named_meshes, mesh_transforms, mesh_material_info) =
process_meshes(scene, settings, load_context)?;
let (materials, named_materials) = if !settings.load_materials.is_empty() {
process_materials(scene, settings, load_context, external_texture_bytes)?
} else {
(Vec::new(), HashMap::new())
};
let (nodes, named_nodes, node_map) = process_nodes(scene, &meshes, load_context)?;
let (skins, named_skins) = process_skins(scene, &node_map, load_context)?;
let scene_handle = build_scene(
scene,
&meshes,
&materials,
&named_materials,
&mesh_transforms,
&mesh_material_info,
settings,
load_context,
)?;
Ok(Fbx {
scenes: vec![scene_handle.clone()],
named_scenes: HashMap::new(),
meshes,
named_meshes,
materials,
named_materials,
nodes,
named_nodes,
skins,
named_skins,
default_scene: Some(scene_handle),
axis_system: FbxAxisSystem {
up: Vec3::Y,
front: Vec3::Z,
handedness: Handedness::Right,
},
unit_scale: 1.0,
metadata: FbxMeta::default(),
})
}
fn warn_texture_failures(
asset_path: &bevy::asset::AssetPath<'_>,
failures: impl IntoIterator<Item = String>,
) {
let failures = failures.into_iter().collect::<Vec<_>>();
warn!(
"bevy_ufbx: skipped {} unavailable external texture reference(s) for {}: {}",
failures.len(),
asset_path,
failures.join("; ")
);
}
+62 -77
View File
@@ -3,19 +3,21 @@
use crate::error::FbxError; use crate::error::FbxError;
use crate::label::FbxAssetLabel; use crate::label::FbxAssetLabel;
use crate::loader::FbxLoaderSettings; use crate::loader::FbxLoaderSettings;
use crate::texture::external_texture_reference;
use crate::utils::convert_texture_uv_transform; use crate::utils::convert_texture_uv_transform;
use bevy::asset::{Handle, LoadContext}; use bevy::asset::{Handle, LoadContext};
use bevy::pbr::StandardMaterial; use bevy::pbr::StandardMaterial;
use bevy::prelude::*; use bevy::prelude::*;
use bevy_material::AlphaMode; use bevy_material::AlphaMode;
use bevy_image::{CompressedImageFormats, ImageSampler, ImageType}; use bevy_image::{CompressedImageFormats, ImageSampler, ImageType};
use std::collections::HashMap; use std::collections::{BTreeSet, HashMap};
/// Process all materials from the FBX scene. /// Process all materials from the FBX scene.
pub fn process_materials( pub fn process_materials(
scene: &ufbx::Scene, scene: &ufbx::Scene,
settings: &FbxLoaderSettings, settings: &FbxLoaderSettings,
load_context: &mut LoadContext, load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result< ) -> Result<
( (
Vec<Handle<StandardMaterial>>, Vec<Handle<StandardMaterial>>,
@@ -25,7 +27,12 @@ pub fn process_materials(
> { > {
let mut materials = Vec::new(); let mut materials = Vec::new();
let mut named_materials = HashMap::new(); let mut named_materials = HashMap::new();
let texture_handles = process_textures(scene, settings, load_context)?; let texture_handles = process_textures(
scene,
settings,
load_context,
external_texture_bytes,
)?;
for (index, ufbx_material) in scene.materials.as_ref().iter().enumerate() { for (index, ufbx_material) in scene.materials.as_ref().iter().enumerate() {
if ufbx_material.element.element_id == 0 { if ufbx_material.element.element_id == 0 {
@@ -60,18 +67,15 @@ pub fn process_materials(
pub fn process_textures( pub fn process_textures(
scene: &ufbx::Scene, scene: &ufbx::Scene,
settings: &FbxLoaderSettings, settings: &FbxLoaderSettings,
load_context: &mut LoadContext, load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result<HashMap<u32, Handle<Image>>, FbxError> { ) -> Result<HashMap<u32, Handle<Image>>, FbxError> {
let mut texture_handles = HashMap::new(); let mut texture_handles = HashMap::new();
let mut external_handles = HashMap::<String, Handle<Image>>::new();
let mut unavailable = BTreeSet::new();
let asset_path = load_context.path().clone();
for (index, texture) in scene.textures.as_ref().iter().enumerate() { for (index, texture) in scene.textures.as_ref().iter().enumerate() {
let asset_path = load_context.path().clone();
let fbx_dir = asset_path
.path()
.parent()
.unwrap_or_else(|| std::path::Path::new(""))
.to_path_buf();
// Priority 1: Embedded texture data // Priority 1: Embedded texture data
if !texture.content.is_empty() { if !texture.content.is_empty() {
let ext = extract_extension(&texture.filename).unwrap_or("png"); let ext = extract_extension(&texture.filename).unwrap_or("png");
@@ -91,39 +95,62 @@ pub fn process_textures(
texture_handles.insert(texture.element.element_id, handle); texture_handles.insert(texture.element.element_id, handle);
continue; continue;
} }
Err(e) => { Err(error) => {
eprintln!("bevy_ufbx: failed to load embedded texture {index}: {e}"); warn!(
// Fall through to try external paths "bevy_ufbx: skipped embedded texture {index} for {asset_path}: {error}"
);
continue;
} }
} }
} }
// Priority 2: relative_filename from ufbx (relative to FBX file) let reference = match external_texture_reference(index, texture) {
if !texture.relative_filename.is_empty() { Ok(Some(reference)) => reference,
let rel = texture.relative_filename.as_ref(); Ok(None) => continue,
let is_absolute = rel.starts_with('/') Err(error) => {
|| (rel.len() >= 3 && rel.chars().nth(1) == Some(':')); unavailable.insert(error.to_string());
if !is_absolute {
let texture_path = fbx_dir.join(rel).to_string_lossy().to_string();
let image_handle = load_context.load(texture_path);
texture_handles.insert(texture.element.element_id, image_handle);
continue; continue;
} }
};
if let Some(handle) = external_handles.get(&reference.relative_path) {
texture_handles.insert(reference.element_id, handle.clone());
continue;
} }
// Priority 3: Extract relative path from filename / absolute_filename let Some(bytes) = external_texture_bytes.get(&reference.relative_path) else {
// Preserves .fbm folder structure if present (e.g., "model.fbm/texture.jpg") continue;
let relative_path = extract_relative_texture_path(texture); };
let extension = std::path::Path::new(&reference.relative_path)
.extension()
.and_then(|extension| extension.to_str())
.unwrap_or("png");
let image = match Image::from_buffer(
&bytes,
ImageType::Extension(extension),
CompressedImageFormats::NONE,
true,
ImageSampler::Default,
settings.load_materials,
) {
Ok(image) => image,
Err(error) => {
unavailable.insert(format!("{} ({error})", reference.relative_path));
continue;
}
};
let handle = load_context
.add_labeled_asset(FbxAssetLabel::Texture(index).to_string(), image);
external_handles.insert(reference.relative_path, handle.clone());
texture_handles.insert(reference.element_id, handle);
}
if !relative_path.is_empty() { if !unavailable.is_empty() {
let texture_path = fbx_dir warn!(
.join(relative_path) "bevy_ufbx: skipped {} unavailable external texture reference(s) for {}: {}",
.to_string_lossy() unavailable.len(),
.to_string(); asset_path,
unavailable.into_iter().collect::<Vec<_>>().join("; ")
let image_handle = load_context.load(texture_path); );
texture_handles.insert(texture.element.element_id, image_handle);
}
} }
Ok(texture_handles) Ok(texture_handles)
@@ -140,48 +167,6 @@ fn extract_extension(filename: &ufbx::String) -> Option<&str> {
.filter(|ext| !ext.contains('/') && !ext.contains('\\')) .filter(|ext| !ext.contains('/') && !ext.contains('\\'))
} }
/// Extract a relative texture path from a ufbx Texture's filename or absolute_filename.
///
/// Handles absolute paths by looking for `.fbm` folders (FBX's standard embedded texture
/// directory) and extracting from there, or falling back to just the filename.
fn extract_relative_texture_path<'a>(texture: &'a ufbx::Texture) -> &'a str {
if !texture.filename.is_empty() {
let filename = texture.filename.as_ref();
let is_absolute = filename.starts_with('/')
|| (filename.len() >= 3 && filename.chars().nth(1) == Some(':'));
if is_absolute {
extract_from_absolute(filename)
} else {
filename
}
} else if !texture.absolute_filename.is_empty() {
extract_from_absolute(texture.absolute_filename.as_ref())
} else {
""
}
}
/// Extract a relative path from an absolute path, preserving `.fbm` folder structure.
fn extract_from_absolute(path: &str) -> &str {
if let Some(fbm_pos) = path.rfind(".fbm/").or_else(|| path.rfind(".fbm\\")) {
let before_fbm = &path[..fbm_pos];
let folder_start = before_fbm
.rfind(&['/', '\\'][..])
.map(|p| p + 1)
.unwrap_or(0);
&path[folder_start..]
} else {
let last_slash = path.rfind(&['/', '\\'][..]);
if let Some(pos) = last_slash {
&path[pos + 1..]
} else {
path
}
}
}
/// Create a StandardMaterial from ufbx material. /// Create a StandardMaterial from ufbx material.
pub fn create_standard_material( pub fn create_standard_material(
ufbx_material: &ufbx::Material, ufbx_material: &ufbx::Material,
+211
View File
@@ -0,0 +1,211 @@
//! External FBX texture reference discovery and path normalization.
use std::collections::BTreeSet;
use std::fmt;
use std::path::{Component, Path};
/// One safe external texture reference declared by an FBX texture element.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FbxExternalTextureReference {
pub texture_index: usize,
pub element_id: u32,
pub relative_path: String,
}
/// A texture reference that cannot be resolved inside the FBX asset source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FbxTexturePathError {
pub texture_index: usize,
pub raw_path: String,
pub reason: String,
}
/// Deterministic external texture discovery result, including safe and rejected references.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FbxExternalTexturePathReport {
pub paths: Vec<String>,
pub errors: Vec<FbxTexturePathError>,
}
impl fmt::Display for FbxTexturePathError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"texture {} path `{}` is unsafe: {}",
self.texture_index, self.raw_path, self.reason
)
}
}
/// Returns the normalized external path for one texture, or `None` for embedded/no-file textures.
pub fn external_texture_reference(
texture_index: usize,
texture: &ufbx::Texture,
) -> Result<Option<FbxExternalTextureReference>, FbxTexturePathError> {
if !texture.content.is_empty() {
return Ok(None);
}
let Some(raw_path) = texture_path_candidate(texture) else {
return Ok(None);
};
let relative_path = normalize_external_texture_path(raw_path).map_err(|reason| {
FbxTexturePathError {
texture_index,
raw_path: raw_path.to_string(),
reason,
}
})?;
Ok(Some(FbxExternalTextureReference {
texture_index,
element_id: texture.element.element_id,
relative_path,
}))
}
/// Returns every distinct safe external texture path in deterministic order.
pub fn external_texture_paths(
scene: &ufbx::Scene,
) -> Result<Vec<String>, Vec<FbxTexturePathError>> {
let report = external_texture_path_report(scene);
if report.errors.is_empty() {
Ok(report.paths)
} else {
Err(report.errors)
}
}
/// Discovers safe and rejected references without discarding either side of the result.
pub fn external_texture_path_report(scene: &ufbx::Scene) -> FbxExternalTexturePathReport {
let mut paths = BTreeSet::new();
let mut errors = Vec::new();
for (texture_index, texture) in scene.textures.as_ref().iter().enumerate() {
match external_texture_reference(texture_index, texture) {
Ok(Some(reference)) => {
paths.insert(reference.relative_path);
}
Ok(None) => {}
Err(error) => errors.push(error),
}
}
errors.sort_by(|left, right| {
(left.texture_index, &left.raw_path).cmp(&(right.texture_index, &right.raw_path))
});
errors.dedup();
FbxExternalTexturePathReport {
paths: paths.into_iter().collect(),
errors,
}
}
fn texture_path_candidate(texture: &ufbx::Texture) -> Option<&str> {
if !texture.relative_filename.is_empty() {
return Some(texture.relative_filename.as_ref());
}
if !texture.filename.is_empty() {
return Some(texture.filename.as_ref());
}
if !texture.absolute_filename.is_empty() {
return Some(texture.absolute_filename.as_ref());
}
None
}
fn normalize_external_texture_path(raw_path: &str) -> Result<String, String> {
let normalized = raw_path.trim().replace('\\', "/");
if normalized.is_empty() {
return Err("path is empty".into());
}
if normalized.contains('\0') {
return Err("path contains a NUL byte".into());
}
if normalized.contains('#') || normalized.contains('?') || normalized.contains("://") {
return Err("path contains asset-source, label, or query syntax".into());
}
let normalized = if is_absolute_like(&normalized) {
extract_fbm_suffix(&normalized).ok_or_else(|| {
"absolute paths are rejected unless they identify a portable .fbm sidecar".to_string()
})?
} else {
normalized
};
let mut components = Vec::new();
for component in Path::new(&normalized).components() {
match component {
Component::Normal(segment) => {
let segment = segment.to_str().ok_or_else(|| "path is not UTF-8".to_string())?;
if segment.contains(':') {
return Err("path contains a platform or asset-source prefix".into());
}
components.push(segment);
}
Component::CurDir => {}
Component::ParentDir => return Err("parent traversal is not allowed".into()),
Component::RootDir | Component::Prefix(_) => {
return Err("absolute paths are not allowed".into());
}
}
}
if components.is_empty() {
return Err("path does not identify a file".into());
}
Ok(components.join("/"))
}
fn is_absolute_like(path: &str) -> bool {
path.starts_with('/')
|| path.starts_with("//")
|| path.as_bytes().get(1).is_some_and(|byte| *byte == b':')
}
fn extract_fbm_suffix(path: &str) -> Option<String> {
let lower = path.to_ascii_lowercase();
let fbm_end = lower.rfind(".fbm/")? + ".fbm/".len();
let fbm_start = path[..fbm_end - 1]
.rfind('/')
.map(|index| index + 1)
.unwrap_or(0);
Some(path[fbm_start..].to_string())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sibling_texture_folder_is_preserved() {
assert_eq!(
normalize_external_texture_path("textures\\chair_diff.jpg").unwrap(),
"textures/chair_diff.jpg"
);
}
#[test]
fn absolute_fbm_path_is_portably_rebased() {
assert_eq!(
normalize_external_texture_path("C:\\Build\\Chair.fbm\\chair_diff.jpg").unwrap(),
"Chair.fbm/chair_diff.jpg"
);
}
#[test]
fn absolute_non_sidecar_path_is_rejected() {
let error = normalize_external_texture_path("C:\\Build\\textures\\chair_diff.jpg")
.unwrap_err();
assert!(error.contains("absolute paths are rejected"));
}
#[test]
fn parent_traversal_is_rejected() {
let error = normalize_external_texture_path("../shared/chair_diff.jpg").unwrap_err();
assert!(error.contains("parent traversal"));
}
#[test]
fn asset_path_syntax_is_rejected() {
assert!(normalize_external_texture_path("remote://chair_diff.jpg").is_err());
assert!(normalize_external_texture_path("textures/chair.jpg#Image0").is_err());
}
}
+6
View File
@@ -9,6 +9,11 @@ name = "validate-levels"
path = "src/validate_levels.rs" path = "src/validate_levels.rs"
required-features = ["validate-levels"] required-features = ["validate-levels"]
[[bin]]
name = "validate-samples"
path = "src/validate_samples.rs"
required-features = ["validate-samples"]
[[bin]] [[bin]]
name = "clean-target" name = "clean-target"
path = "src/clean_target.rs" path = "src/clean_target.rs"
@@ -44,3 +49,4 @@ libc = "0.2"
[features] [features]
default = [] default = []
validate-levels = ["dep:scene", "dep:settings", "dep:shared"] validate-levels = ["dep:scene", "dep:settings", "dep:shared"]
validate-samples = ["validate-levels"]
+209
View File
@@ -0,0 +1,209 @@
//! Validate the canonical editor sample pack and the complete project dependency graph.
use std::path::PathBuf;
use scene::{
sample_pack::validate_editor_sample_pack, ProjectValidationReport, ValidationSeverity,
};
use serde::Serialize;
#[derive(Serialize)]
struct ValidateSamplesOutput<'a> {
manifest_path: &'a str,
samples: &'a [scene::sample_pack::EditorSampleEntry],
dependencies: &'a [scene::ProjectDependency],
findings: &'a [scene::ProjectValidationFinding],
}
fn main() {
let mut project_root = PathBuf::from(".");
let mut json = false;
let mut args = std::env::args().skip(1);
while let Some(argument) = args.next() {
match argument.as_str() {
"--json" => json = true,
"--project" => {
let Some(path) = args.next() else {
eprintln!("validate-samples: --project requires a path");
std::process::exit(2);
};
project_root = PathBuf::from(path);
}
_ => {
eprintln!("validate-samples: unknown argument `{argument}`");
std::process::exit(2);
}
}
}
let sample_validation = validate_editor_sample_pack(&project_root);
let mut report = scene::validate_project(&project_root);
merge_reports(&mut report, &sample_validation.report);
if json {
let output = ValidateSamplesOutput {
manifest_path: &sample_validation.manifest_path,
samples: &sample_validation.samples,
dependencies: &report.dependencies,
findings: &report.findings,
};
println!(
"{}",
serde_json::to_string_pretty(&output).expect("sample validation report must serialize")
);
} else {
for sample in &sample_validation.samples {
println!(
"sample: {} [{}] {} ({})",
sample.area, sample.id, sample.label, sample.scene
);
}
for finding in &report.findings {
let actor = finding
.owner_actor_id
.as_deref()
.map(|actor| format!(" actor={actor}"))
.unwrap_or_default();
eprintln!(
"{:?} [{}] {}{}: {}",
finding.severity, finding.code, finding.source_path, actor, finding.message
);
}
println!(
"validate-samples: {} samples, {} dependencies, {} findings, {} blocking errors",
sample_validation.samples.len(),
report.dependencies.len(),
report.findings.len(),
report.blocking_error_count()
);
}
if !report.is_release_ready() {
std::process::exit(1);
}
}
fn merge_reports(target: &mut ProjectValidationReport, source: &ProjectValidationReport) {
target
.dependencies
.extend(source.dependencies.iter().cloned());
target.findings.extend(source.findings.iter().cloned());
target.dependencies.sort_by(|left, right| {
(
&left.owner_path,
&left.owner_actor_id,
&left.kind,
&left.reference,
)
.cmp(&(
&right.owner_path,
&right.owner_actor_id,
&right.kind,
&right.reference,
))
});
target.dependencies.dedup();
target.findings.sort_by(|left, right| {
(
&left.source_path,
&left.owner_actor_id,
&left.code,
&left.reference,
&left.message,
severity_rank(left.severity),
&left.repair,
)
.cmp(&(
&right.source_path,
&right.owner_actor_id,
&right.code,
&right.reference,
&right.message,
severity_rank(right.severity),
&right.repair,
))
});
target.findings.dedup();
}
const fn severity_rank(severity: ValidationSeverity) -> u8 {
match severity {
ValidationSeverity::Error => 0,
ValidationSeverity::Warning => 1,
ValidationSeverity::Info => 2,
}
}
#[cfg(test)]
mod tests {
use super::*;
use scene::{ProjectDependency, ProjectValidationFinding};
#[test]
fn merged_report_is_sorted_and_deduplicated() {
let dependency = ProjectDependency {
owner_path: "assets/samples/editor_samples.ron".into(),
owner_actor_id: None,
kind: "editor_sample_scene".into(),
reference: "assets/levels/samples/brush.scn.ron".into(),
};
let finding = ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "sample_pack.scene_missing".into(),
source_path: "assets/samples/editor_samples.ron".into(),
owner_actor_id: None,
reference: Some("assets/levels/samples/brush.scn.ron".into()),
message: "missing".into(),
repair: "restore".into(),
};
let source = ProjectValidationReport {
dependencies: vec![dependency.clone()],
findings: vec![finding.clone()],
};
let mut target = source.clone();
merge_reports(&mut target, &source);
assert_eq!(target.dependencies, vec![dependency]);
assert_eq!(target.findings, vec![finding]);
}
#[test]
fn merged_json_is_deterministic_across_input_order() {
let dependency = |reference: &str| ProjectDependency {
owner_path: "assets/samples/editor_samples.ron".into(),
owner_actor_id: None,
kind: "editor_sample_scene".into(),
reference: reference.into(),
};
let finding = |code: &str, repair: &str| ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: code.into(),
source_path: "assets/samples/editor_samples.ron".into(),
owner_actor_id: None,
reference: Some(code.into()),
message: code.into(),
repair: repair.into(),
};
let first = ProjectValidationReport {
dependencies: vec![dependency("assets/levels/z.scn.ron")],
findings: vec![finding("sample_pack.same", "repair-z")],
};
let second = ProjectValidationReport {
dependencies: vec![dependency("assets/levels/a.scn.ron")],
findings: vec![finding("sample_pack.same", "repair-a")],
};
let mut left = first.clone();
merge_reports(&mut left, &second);
let mut right = second;
merge_reports(&mut right, &first);
let left_json = serde_json::to_string(&left).unwrap();
let right_json = serde_json::to_string(&right).unwrap();
assert_eq!(left, right);
assert_eq!(left_json, right_json);
assert_eq!(left.findings[0].repair, "repair-a");
assert_eq!(left.findings[1].repair, "repair-z");
}
}