# FBX External Texture Dependencies

> **Historical plan — not current implementation guidance.** Use the [documentation index](../../docs/README.md) for current behavior and architecture.

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