Blacksite/docs/adr/0044-sandboxed-fbx-external-texture-dependencies.md

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 any stable model slot selects Source, but it can be an intentional authoring condition when every slot selects a project Material/Instance or Default.

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 while any slot selects Source and an informational consolidated finding when every slot selects Project/Default. The former whole-model Authoring Override value is accepted only as registry-v1 migration input and expands to explicit Default selections. Unsafe paths remain blocking under either selection state. 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's legacy Authoring Override migrates to per-slot Default selections 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.
• Any Source slot fails release validation when its FBX textures are absent. An all-Project/Default model 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.