Resolve FBX external texture dependencies

This commit is contained in:
Rbanh committed 2026-07-13 13:41:23 -04:00
1 parent 7e99243a78
commit 3e30c61c71
22 files changed
+1670 -265

No files matched your search

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