Material Swaps (MSWP)¶
Fallout 4's material swap system allows the same model to render with different surface colors. This is the mechanism behind differently colored crates or car paints, billboards with differing advertisements, etc.
The Three Variant Mechanisms¶
1. MSWP Records¶
A MSWP (Material Swap) record is a list of substitutions:
BNAM zstring original material path (.bgsm/.bgem, relative to Data\Materials\)
SNAM zstring replacement material path
FNAM float32 optional ColorRemappingIndex (omitted when unused; NaN in some tools)
At render time the engine walks the model's shapes; any shape whose material (the
BSLightingShaderProperty.Name / BSEffectShaderProperty.Name BGSM/BGEM path) matches an
original gets the replacement material instead. Shapes that match nothing keep their
default material. A swap is a sparse override, not a full reskin.
2. Where Swaps Are Referenced¶
| Subrecord | On | Payload |
|---|---|---|
XMSP |
placed refs (REFR, rarely ACHR/PGRE) | 4-byte MSWP formid |
MODS |
base records (STAT, MSTT, CONT, FURN, DOOR, ACTI, FLOR, SCOL, ...) | 4-byte MSWP formid |
MODC |
base records (model data) | float32 color-remapping index |
3. MODC (Recoloring Without a Swap Record)¶
MODC is a record-level float that re-selects the palette LUT band for every
grayscale-to-palette material on the model (see
Textures & Materials, Greyscale-to-Palette).
It needs no MSWP record at all, and it is the coloring mechanism for some of the most common
objects in the game:
CrateLargeGreen/Blue/Red/Aqua/Gray/..., the painted large crates (one shared grayscale diffusecratelarge01_d.dds, with one band per base)ShippingCrate01Gray/Green/Orange/Blue, the shipping containers (shippingcrates01.bgsm, bands at neat fractions: 0.4375, 0.5625, 0.6875, 0.8125)- The burnt-car MSTT fleet (
CarSedan03= 0.36,CarCoupe01= 0.113, etc.)
142 MODC-only bases cover ~4,519 placements. Without MODC support every such object renders one default color per model.
MODC only has meaning for palette-flagged materials; on a model with none it is inert (7 of the 144 MODC bases are like that in vanilla).
ColorRemappingIndex on a MSWP substitution is the same float with the same meaning,
scoped to one substitution: 104 of the 156 entries carrying it have
original == replacement, making them pure recolors of the same material
(for example, MachineKitGreenLight01: machinekit01.bgsm maps to itself at index 0.57).
The Two Variant Classes¶
- Path swaps. The replacement BGSM points at different textures
(
vault_crate_01_d.dds->vault_crate_05_d.dds,truck01a_d.dds->truck02a_d.dds). This is the majority of swaps. - LUT-row recolors. The replacement BGSM has identical texture paths and differs only
in
grayscale_to_palette_scale(the Sportscar/StationWagon families are byte-identical files except for that one float), or the substitution/record supplies aColorRemappingIndex/MODC. These are invisible unless the palette system honors the band float.
LOD Behavior¶
LOD meshes have their own materials (materials/lod/...), so a swap only affects LOD if
the MSWP author added substitutions for them. Vanilla contains 94 such LOD entries
(machine-kit colors, DecoKit brick walls, wet coast cliffs, Glowing Sea rock slabs, themed
marble). Everything else renders the default LOD material. For example, all billboards share
one generic LOD ad (materials/lod/billboard02lod.bgsm, which no swap touches); the per-ref
advertisement only appears once the full model streams in.
Data Quirks¶
All observed in vanilla Fallout4.esm:
| Quirk | Example | Notes |
|---|---|---|
| Bare filenames, no directory | Sportscar01_Rust.BGSM |
Must resolve via sibling-directory of the other side, then unique-filename lookup |
Missing materials\ prefix |
setdressing\vault\Vault_Crate_01.BGSM |
Try both prefixed/unprefixed |
| Mixed case | .BGSM vs .bgsm |
Normalize to lowercase |
| Null padding entries | 509 of 6,051 | Skip |
* wildcards in originals |
landscape\ground\craterdebris01*.bgsm (3 records) |
Rare; only 3 records use this |
| CK auto-generated swaps | CustomMaterialSwap00247516 (per-base) |
Ordinary MSWPs, nothing special |
| Leftover swaps that match nothing | Car02RustOnlySwap on CarCoupe04_Static (its model has coupe01_rust materials, the swap substitutes car00/car02chrome) |
Inert in vanilla too |
| Replacements that never shipped | VltAtmosphereSensor01_Damage.BGSM, 8 AstoundinglyAwesome* magazine textures |
Entry is a no-op |
| SCOL | Swaps apply to the whole merged collection (no per-part swap data exists, as SCOL is just ONAM+DATA pairs). 2,480 SCOL refs carry XMSP |
Per-primitive source-material matching handles it |