BS-JD-210 - Resolve external FBX texture dependencies without repeated load errors #58

New Issue

Rbanh · 2026-07-13T12:06:31-04:00

Rbanh commented

2026-07-13 12:06:31 -04:00

Summary

Make FBX external-texture discovery, import, validation, and editor preview deterministic and actionable. A committed FBX must either resolve its referenced textures or report one stable dependency error before Bevy repeatedly attempts the missing paths.

Native QA finding

During #56 native acceptance at e1b2f86a495496da83947777d332d00a15a1779d, selecting assets/models/painted_wooden_chair_02_2k.fbx rendered its Asset Browser entry but produced six Bevy asset-server load errors for three absent files:

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

The paths were requested more than once. The previous dependency extraction was limited to .fbm sidecar discovery, while this source references a sibling textures/ layout.

Original finding: imported model browser and selected FBX details

Acceptance criteria

The committed painted-chair fixture resolves its intended textures, or is deliberately normalized as untextured without asset-server errors.
FBX dependency extraction records every externally referenced texture path supported by the importer, including non-.fbm relative layouts.
Import/copy preserves or remaps required sidecars transactionally.
Project validation reports missing FBX dependencies before native asset loading and remains read-only.
Asset Browser preview exposes one stable actionable dependency state; it does not repeatedly enqueue known-missing paths or spam duplicate load errors.
Tests cover .fbm, sibling relative texture folders, missing dependencies, and path traversal/sandbox rejection.
Native QA confirms the painted chair preview and a deliberately broken fixture behave as specified.

Scope note

This defect was exposed while validating deterministic fingerprints but is independent of #56. The #56 registry and generated artifacts remained byte-stable and its clean-checkout gate passed.

Exact-commit native evidence

Normalized chair at implementation commit 3e30c61:

Deliberately broken Source Materials fixture at implementation commit 3e30c61:

## Summary Make FBX external-texture discovery, import, validation, and editor preview deterministic and actionable. A committed FBX must either resolve its referenced textures or report one stable dependency error before Bevy repeatedly attempts the missing paths. ## Native QA finding During #56 native acceptance at `e1b2f86a495496da83947777d332d00a15a1779d`, selecting `assets/models/painted_wooden_chair_02_2k.fbx` rendered its Asset Browser entry but produced six Bevy asset-server load errors for three absent files: - `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` The paths were requested more than once. The previous dependency extraction was limited to `.fbm` sidecar discovery, while this source references a sibling `textures/` layout. Original finding: [imported model browser and selected FBX details](https://git.spacetrainclubhouse.com/attachments/93da7803-de47-43fb-bb8c-f759970a2b5f) ## Acceptance criteria - [x] The committed painted-chair fixture resolves its intended textures, or is deliberately normalized as untextured without asset-server errors. - [x] FBX dependency extraction records every externally referenced texture path supported by the importer, including non-`.fbm` relative layouts. - [x] Import/copy preserves or remaps required sidecars transactionally. - [x] Project validation reports missing FBX dependencies before native asset loading and remains read-only. - [x] Asset Browser preview exposes one stable actionable dependency state; it does not repeatedly enqueue known-missing paths or spam duplicate load errors. - [x] Tests cover `.fbm`, sibling relative texture folders, missing dependencies, and path traversal/sandbox rejection. - [x] Native QA confirms the painted chair preview and a deliberately broken fixture behave as specified. ## Scope note This defect was exposed while validating deterministic fingerprints but is independent of #56. The #56 registry and generated artifacts remained byte-stable and its clean-checkout gate passed. ## Exact-commit native evidence Normalized chair at implementation commit `3e30c61`: ![Normalized chair Asset Browser state](https://git.spacetrainclubhouse.com/attachments/a66b1844-2d17-4975-ba6e-1c0e00a02709) Deliberately broken Source Materials fixture at implementation commit `3e30c61`: ![Broken chair dependency state](https://git.spacetrainclubhouse.com/attachments/a64cd69b-0fe7-4dc8-9f24-a333e018a682)

blacksite-issue58-chair-normalized.png

1.7 MiB

blacksite-issue58-chair-broken-source-materials.png

1.7 MiB

blacksite-issue58-chair-normalized-3e30c61.png

1.7 MiB

blacksite-issue58-chair-broken-source-materials-3e30c61.png

1.9 MiB

Rbanh added this to the M2 - Content workspace and asset pipeline milestone 2026-07-13 12:06:31 -04:00

Rbanh added the

labels 2026-07-13 12:06:31 -04:00

Rbanh referenced this issue

2026-07-13 12:11:22 -04:00

BS-JD-209 - Deterministic imported-asset fingerprints #56

Rbanh referenced this issue

2026-07-13 12:12:37 -04:00

BS-PR-707 - Production-readiness acceptance gate and release checklist #50

Rbanh referenced this issue

2026-07-13 12:12:47 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Rbanh changed reference from ~~codex/deterministic-asset-fingerprints~~ to codex/fbx-external-textures

2026-07-13 14:12:37 -04:00

Rbanh commented

2026-07-13 14:12:52 -04:00

Closeout

Implemented in 3e30c61 and documented in 931f561, now published on main.

Shipped behavior:

one shared sandboxed FBX texture-path resolver across loading, import, validation, and manifests;
transactional sidecar copying with preflight, staging, backup, rollback, and source/destination containment checks;
read-only validation with one consolidated missing-dependency blocker;
Asset Browser terminal dependency states, neutral previews, and no repeated requests for known-missing textures;
the committed chair is deliberately normalized through AuthoringOverride.

Verification:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets (editor 309 passed; scene 103 passed, 1 manual migration ignored)
focused import coverage for sibling folders, .fbm, missing files, traversal, and destination symlinks
cargo validate-levels --project .: 84 dependencies, 6 findings, 0 blockers
cargo validate-samples --project .: 5 samples, 89 dependencies, 6 findings, 0 blockers
deliberately broken exact-commit native fixture: exactly one consolidated three-file blocker, terminal browser warnings, and no repeated bevy_asset/bevy_ufbx missing-path output
restored normalized exact-commit run: clean worktree, zero blockers, and no stdout/stderr

The versioned evidence record contains the attachment hashes and full acceptance matrix.

Packaged acceptance remains explicitly owner-deferred. This closes #58 at feature level; it does not nominate a release candidate or change #50 from Not ready.

## Closeout Implemented in [`3e30c61`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/3e30c61c71fc942c33635aae3d922b70401fe7c7) and documented in [`931f561`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/931f561e7ff1489f897e22ebb3cc7545fcfef702), now published on `main`. Shipped behavior: - one shared sandboxed FBX texture-path resolver across loading, import, validation, and manifests; - transactional sidecar copying with preflight, staging, backup, rollback, and source/destination containment checks; - read-only validation with one consolidated missing-dependency blocker; - Asset Browser terminal dependency states, neutral previews, and no repeated requests for known-missing textures; - the committed chair is deliberately normalized through `AuthoringOverride`. Verification: - `cargo fmt --all -- --check` - `cargo clippy --workspace --all-targets -- -D warnings` - `cargo test --workspace --all-targets` (editor 309 passed; scene 103 passed, 1 manual migration ignored) - focused import coverage for sibling folders, `.fbm`, missing files, traversal, and destination symlinks - `cargo validate-levels --project .`: 84 dependencies, 6 findings, 0 blockers - `cargo validate-samples --project .`: 5 samples, 89 dependencies, 6 findings, 0 blockers - deliberately broken exact-commit native fixture: exactly one consolidated three-file blocker, terminal browser warnings, and no repeated `bevy_asset`/`bevy_ufbx` missing-path output - restored normalized exact-commit run: clean worktree, zero blockers, and no stdout/stderr The [versioned evidence record](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/931f561e7ff1489f897e22ebb3cc7545fcfef702/docs/editor/evaluations/fbx-external-texture-dependencies/README.md) contains the attachment hashes and full acceptance matrix. Packaged acceptance remains explicitly owner-deferred. This closes #58 at feature level; it does not nominate a release candidate or change #50 from **Not ready**.

Rbanh changed reference from ~~codex/fbx-external-textures~~ to codex/fbx-external-textures

2026-07-13 14:12:57 -04:00

Rbanh closed this issue

2026-07-13 14:12:57 -04:00

Rbanh referenced this issue

2026-07-13 14:13:15 -04:00

BS-PR-707 - Production-readiness acceptance gate and release checklist #50

Rbanh referenced this issue

2026-07-13 14:13:23 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Rbanh referenced this issue

2026-07-13 16:50:43 -04:00