KB: mech paint audit -- per-pilot color/badge/patch substitution authored but unwired (the 'missing stripes/coloration' report)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

context/open-questions.md

@@ -644,6 +644,10 @@ register.  ⚠ The audit also flags the damage-economy item as SELF-CONTRADICTOR
   LIVENESS audit (does a live call path reach each reconstructed fn?) would catch this class.
 
 ## Rendering follow-ups (non-blocking)
+- **Per-pilot mech PAINT (color/badge/patch) — art ships, port never engages it** (2026-07-17 audit;
+  full mechanics + fix path in [[rendering]] §Per-pilot mech PAINT). Wire egg color/badge/patch into
+  `SetupMaterialSubstitutionList`, apply `substituteMaterial` in `bgfload resolve()`, per-variant
+  mesh cache. This is the "missing warning stripes / coloration" report.
 - **.PFX effect-layer polish (deferred 2026-07-08; the layer itself is LIVE + verified).** The
   reconstructed BT particle layer (L4VIDEO.cpp, see its banner) renders the authentic .PFX content
   (fire + smoke, premultiplied blend, impact-frame oriented — weapon hits AND damage bands via

context/rendering.md

@@ -105,8 +105,34 @@ models is deferred (needs the board's hot-spot semantics). [T2]
 `.BSL` is a bit-sliced container (6 grayscale sub-images per file); the BMF `0x18 BITSLICE` tag picks
 the slice. Reading it as RGB overlaid 2-3 gray sheets = the "rainbow/graffiti" bug. Fixed:
 `image.cpp decodeBSL` slice-decodes; `bgfload` threads the 0x18 channel; a cross-library RAMP registry
-resolves the mech-skin `softer` ramp (defined in OTHER libs). Every mech renders authentic gray-metal
-paint now. See [[asset-formats]]. [T2]
+resolves the mech-skin `softer` ramp (defined in OTHER libs). Every mech renders the authentic BASE
+gray-metal skin now. See [[asset-formats]]. [T2]
+
+## Per-pilot mech PAINT (color/badge/patch substitution) — NOT WIRED (2026-07 audit)
+The "missing warning stripes / coloration" report is the per-pilot paint layer, fully authored but
+never engaged by the port. Mechanics (all [T1] from the BMF/BGF/vehicletable content + FUN_004d0cc0):
+- Mech BGFs reference the BASE lib only (`blhskin:gen2_dz_rfoot_mtl` …). The binary rewrites lib
+  prefixes at load via the `vehicletable` resource `[substitute]` templates: `skin:` → `_%color%%serno%:`
+  (`blhskin:` → `blh_wht0:`) and `skin:lgo` → `<<<emblem%serno%:%badge%_%patch%>` (emblem pages →
+  `EMBLEM0.BMF` `lgoN_<patch>_dz_*` materials). Pilot egg values (color/badge/patch) map through the
+  `[color]/[badge]/[patch]` sections to the codes.
+- The COLOR libs (e.g. `BLH_WHT0.BMF`) are byte-identical to the base lib EXCEPT they add tags
+  `0x23`(diffuse RGB) + `0x24`(ambient RGB) = the pilot color to the ~35 paintable `gen*/mech*_dz_*`
+  materials (base leaves them untinted). 7 colors: wht(.99,.99,.99) red(.90,.11,.10) grn(.63,.83,.52)
+  gry(.65,.60,.65) brn(.60,.44,.28) tan(.65,.55,.43) blk(0,0,0). All 8 sernos are byte-identical
+  (verified: 0 of 193 groups differ) — `%serno%` was future variety, never used. `<mech>SKIN.BMF`
+  (bare) == `<mech>SKIN0.BMF`.
+- WARNING STRIPES are grayscale hazard-stripe art in the shared `GEN.BSL` pages (slice 1 = `gen2_tex`,
+  top-left), shown through the paintable-zone materials and tinted by the pilot color. `EMBLEM0.BMF`
+  carries `lgoN_<patchcolor>_dz_ld/rdleg` materials (8 patch tints incl. yellow .89,.73,0) over
+  `LGO.BSL` slices 0-5 (slice 5 = VGL winged logo).
+- PORT GAP: `SetupMaterialSubstitutionList` (btl4vid.cpp:2094) feeds NULL egg names (Mech's
+  resourceNameA/B/C not yet safely readable), and `substituteMaterial` (L4VIDEO.cpp:2565) is consumed
+  only by the legacy .X loader (L4D3D.cpp:151) — NOT by `bgfload`'s `MaterialResolver::resolve`. So
+  every mech renders base untinted paint + the hardwired `lgo6` (VGL) emblem. Verified live 2026-07-17:
+  MP MadCat renders white/gray, no tint/emblem/stripes. FIX PATH: (a) wire real egg color/badge/patch
+  into the substitution list; (b) apply the substitution in `resolve()` (BGF path); (c) per-variant
+  mesh caching (BgfData is cached per filename — two pilots' colors must not share a baked mesh). [T2]
 
 ## The OLD-STYLE SPECIALFX layer (the weapon-impact action) — RECONSTRUCTED 2026-07-12 (firmware-decoded)
 The per-weapon impact visuals are fully AUTHORED in `content/BTDPL.INI` `[effects_to_load]`: