Material Sprawl Collapser - Collapses Duplicate Base Materials into One Parameterised Master (UE 5.8)

Three hundred base materials that are, structurally, about eleven

Someone needs the crate in a different brown, so they duplicate M_Crate and change one constant. Repeat that for two years across four artists and a Datasmith pipeline.

Every one of those duplicates is a separate shader — separate compile time, separate package size, separate memory, and a separate slot in every review.

Material Sprawl Collapser finds base materials whose expression graphs are identical except for their textures and their scalar/vector constants, generates one master with those leaves promoted to parameters, converts every duplicate into a material instance carrying its own original values, and repoints every referencing slot.

Unreal ships nothing that finds this

• Material Analyzer compares instances that already share a parent, and only their static parameters. Two separate base materials are never compared to each other at all — and a project with no instances yet produces no output whatsoever.
• Size Map tells you what an asset costs, not which assets are the same shape.
• Reference Viewer tells you what points at what.

This compares the expression graphs themselves.

The safety property, stated first because it is the reason to trust it

The dangerous failure here is not a crash. It is a false merge: two materials that were not actually interchangeable get collapsed, and the game looks different on one prop, possibly unnoticed for weeks.

So the predicate has one rule and no exceptions: every ambiguity resolves toward not collapsible.

An expression class the walker will not hash withdraws the whole material — it is never hashed as "some node". So does a property the hasher cannot decompose, a cycle in the graph, and anything that changes the shader permutation rather than a value: static switches, static bools, static component masks, material attribute layers. Floats are hashed by their exact IEEE-754 bits, never by decimal formatting, because formatting rounds and two materials differing below the printed precision would otherwise hash equal and be merged.

Missing a legitimate collapse costs you a smaller report. Merging two materials that differed costs you a bug you will not find. Those are not comparable.

It tells you what it NEARLY collapsed, and why not

"These 47 materials differ only in Node[7].Class" is actionable. Silence is not. The report names the closest pair that failed to merge and the exact field that split them — so a strict predicate never reads as "your project is fine".

It does not blanket-load your project

Stage 1 buckets every material using asset registry tags alone — nothing is loaded. Stage 2 loads only the members of buckets with two or more entries.

That is why the report says "examined 12,000, loaded 340" rather than "scanned 12,000". The gap between those two numbers is your evidence that a twenty-minute editor hang is not happening.

Plan first, apply second

The scan writes a deterministic JSON plan and a standalone HTML report. -Apply on its own is a full dry run — it loads every member, re-hashes it against the plan, resolves the parameters and inspects the referencers, and skips only the writes. A plan is a file, and a file goes stale; a group whose materials changed since the scan is refused, and counted as refused rather than as a failure. Those are different numbers on purpose.

A budget, because sprawl grows back

-Budget=N exits 1 when more than N materials are collapsible. Exit codes are deliberately distinct — 0 ok, 1 over budget, 2 the tool failed, 3 bad arguments — because "your project is over budget" and "the tool crashed" are different mornings, and a CI job should be able to tell them apart.

Getting started

1. Copy the MaterialCollapser folder into YourProject/Plugins/.
2. Launch the editor once and confirm it is enabled under Edit > Plugins > Editor.
3. From your Unreal install's Engine\Binaries\Win64, run the scan — it writes nothing:
   UnrealEditor-Cmd.exe C:\Path\To\YourProject.uproject -run=MaterialCollapser -Paths=/Game -unattended
4. Open YourProject\Saved\MaterialCollapser\report.html in any browser.
5. Commit to source control, then apply with -Apply -Execute.

Full switch reference, the recommended sequence and every refusal reason: Documentation

Requirements and limits, stated plainly

• Unreal Engine 5.8 only. That is the only version it has been built and verified against, and the .uplugin declares it. Editor-only: no runtime module, no runtime cost.
• Version 1 walks material expression graphs. Material function calls are not walked, so a material that calls one is withdrawn rather than guessed at.
• This build promotes 2D texture samples only. A group whose hole texture is not a UTexture2D is refused with that stated as the reason.
• Windows. The packaging gate ran Win64 and nothing else.

---

More Unreal pipeline tools from Core Systems Asset Factory:
Duplicate Mesh Consolidator · Plugin Cleaner · Config Warden · Migration Ledger · Asset Sentinel
See the whole catalogue at csaf.itch.io.

New from Core Systems Asset Factory: Primary Asset Doctor — rewrites the Asset Manager config that leaves GetPrimaryAssetIdList empty, then re-scans to prove the repair worked.