feat(fbx): embed all referenced textures (normal/PBR slots) in Video.Content on export, not just the eager-loaded diffuse

[fernandotonon]

What was observed

Slice G's `qtmesh optimize Rumba.fbx -o out.fbx` produced an FBX that, when re-imported via File→Open in the editor, renders without the normal map. The diffuse texture loads (because it sits next to the file on disk, and Ogre re-resolves it through the resource group), but the normal map shows up as flat-lit geometry.

Same behaviour from any tool that round-trips FBX through our exporter:

• `qtmesh convert`
• `qtmesh fix`
• `qtmesh anim --simplify` (slice C4 fix path)
• `qtmesh optimize` (slice G)

Root cause

`FBXExporter::exportFBX` writes texture filenames into the FBX properties (`Maya|TEX_normal_map`, `NormalMap`, etc.) AND attempts to embed the texture bytes into a `Video.Content` block — but it only succeeds when Ogre's `TextureManager` has the texture loaded in-memory at export time.

The diffuse texture gets loaded eagerly by Assimp's importer because it's bound to the FFP `diffuse_map` texture-unit-state, which Ogre's renderer touches on the first frame. The normal map is wired through our `RTShaderHelper` / Cook-Torrance path, which records the texture name string in the material but never forces an explicit `Ogre::TextureManager::getSingleton().load(name)` on it. So on a CLI-headless export the normal map is just a name with no bytes in the pool, and `FBXExporter` writes a name-only reference.

When the resulting FBX is later opened from a directory that doesn't contain the normal map file by that name, the normal map disappears.

Acceptance criteria

• `FBXExporter::exportFBX` walks every `TextureUnitState` referenced by every `Pass` of every `SubEntity`'s `Material` (including the RTSS-managed slots: albedo / metallic / roughness / ao / emissive / normal). For each, force a `TextureManager::load()` if the texture isn't already in the pool, then embed it via `Video.Content` exactly like the diffuse path does today.
• When a referenced texture name can't be resolved to a file on the resource-group search path, fall back to the current name-only reference but emit a Sentry breadcrumb / log line so the operator knows the file will be missing on re-import.
• Round-trip test: `Rumba Dancing.fbx` → `qtmesh optimize` → re-import → normal map renders correctly when the user moves the output FBX to a directory that doesn't contain `Boss_normal.png` next to it.
• Round-trip test for `qtmesh fix` and the slice C4 `scan --fix` (redundant-keyframe rewrite) so we catch the same regression in those flows.

Workarounds today

Until this is fixed:

• Run optimize / fix / convert with the texture files in the same directory as both the input and the output, OR
• Manually copy the `*.png` files next to the output FBX after export.

Related

• Slice G PR feat(opt): batch optimize pipeline — qtmesh optimize + optimize_mesh (Phase 6 slice G) #507 — surfaced this via the optimize → re-import test the reporter ran. Slice G is shippable as-is because the geometry / animation / material-reference data is intact; only the texture embed is incomplete.
• CLAUDE.md mentions `FBXExporter` "embeds textures (Video.Content) so avoid emitting sidecar .material" — that description is accurate only for the diffuse channel today.

🤖 Generated with Claude Code

[fernandotonon]

Deeper investigation results (from slice G PR #507 verification)

Confirmed via instrumentation that the bug is not slice G–specific — it reproduces on `qtmesh convert .fbx -o .fbx` (plain convert, no optimize stages):

```
$ qtmesh convert ~/Downloads/Rumba\ Dancing.fbx -o /tmp/just_convert.fbx
$ qtmesh info /tmp/just_convert.fbx --verbose | grep -iE 'RTSS normal|Boss_normal|Textures'
Textures: Boss_diffuse.png
```

No "Applying RTSS normal map" line on re-import. Normal map dropped. Same outcome from `qtmesh fix`, `qtmesh optimize`, and (presumably) the editor's File→Save As FBX flow.

Verified mechanism

Walking the export-time material with debug logging:

```
FBXExporter probe: mat 'Clothes_MAT' isLoaded=yes group='/Users/fernandotonon/Downloads' has 1 techniques
technique[0] scheme='Default' passes=1
pass[0].TUS[0] name='0' tex='Boss_diffuse.png'
```

But during import of the same file, RTSS logs:

```
Texture 'Boss_normal.png': Loading 1 faces(PF_B8G8R8,1024x1024x1) ...
MaterialProcessor: Applying RTSS normal map 'Boss_normal.png' to existing material 'Clothes_MAT'
```

So `applyRTSSNormalMap` runs and modifies a `MaterialPtr` named `Clothes_MAT` — but at export time `sub->getMaterial()` returns a different `MaterialPtr` (or the same one with the normal-map TUS magically dropped). The first frame doesn't render the normal map back into the TUS list either — meaning the TUS that `RTShaderHelper::applyNormalMap` creates at `RTShaderHelper.cpp:401` is being garbage-collected by RTSS's scheme-not-found handler before any user code can see it.

Suspected root cause

The Downloads `Rumba Dancing.fbx` triggers TWO independent sources for material `Clothes_MAT`:

1. The FBX itself (Mixamo embeds 4 materials).
2. A bundled `.material` script (`media/models/Rumba_Dancing.material`) that defines `Rumba_DancingClothes_MAT`. The Ogre resource group parses this on directory-load and tries to register `Clothes_MAT` — gets an `ItemIdentityException: Material with the name Rumba_DancingClothes_MAT already exists`.

This dual-registration confuses Ogre's resource group lookup. `sub->getMaterial()` resolves a stale instance that doesn't have the RTSS normal-map TUS. The actual modified material exists somewhere in another group, but the exporter walks the wrong one.

What this means for issue #508

The fix isn't just "FBXExporter should walk RTSS-bound slots" — that helper would find nothing on the `MaterialPtr` it has. The actual fix needs to either:

1. Resolve at export time which resource-group's `MaterialPtr` was actually configured by `MaterialProcessor::applyRTSSNormalMap`. The breadcrumb the importer leaves behind would let the exporter follow it.
2. Stash the normal-map texture name on the entity / mesh user data at import time so the exporter can read it back without depending on which MaterialPtr got modified.
3. Avoid the dual-registration: gate the `.material` script auto-load when an FBX is being imported.

(2) is probably the cheapest. `MaterialProcessor::applyRTSSNormalMap` already knows the texture name; storing it on the entity's user-object bindings (like `mesh->getUserObjectBindings().setUserAny("qtme.normal_map", normalTexName)`) gives `FBXExporter::writeTextureObjects` a reliable place to find it.

Slice G PR #507 disposition

Slice G's optimize pipeline composes the existing import / vertex-cache / decimate / simplify-anim / export sequence. The export-side normal-map drop predates this PR — confirmed by reproducing on plain `qtmesh convert`. PR #507 is shippable as-is; this issue captures the underlying FBX-export gap for a focused follow-up.