Launchbox Precache Manager - Speed up your build - BETA VERSION! 0.17_Beta

LaunchBox Precache Manager (WebP / Image Optimizer)

Author: McFly
Platform: Windows 10/11 – LaunchBox / BigBox
Language: PowerShell 5.1 (built into Windows)

This toolset helps you shrink your LaunchBox Images folder safely by:

Converting heavy originals into WebP precache images in a _Precache folder

Keeping a full-quality backup copy in an _Originals folder

Letting you preview savings with an audit before you touch anything

Letting you backfill any images that were missed by earlier runs

Providing tools to activate / deactivate the precache and clean XML references

Everything is designed to be:

Reversible – originals are preserved in _Originals

Incremental – you can run multiple passes with different presets

Safe on huge libraries – supports checkpoints/resume and quick sampling

Included Files

Place all of these in the same folder (e.g. C:\Users\<You>\Desktop\LB-Precache):

LB-Precache-Manager.ps1 – the main menu script (what you run)

Build-LaunchBox-Thumbnails-Parallel.ps1 – the engine that does actual conversion / activation / restore

Audit-LaunchBox-Images.ps1 – audit script that scans the library and estimates potential savings

Hardware-Probe.ps1 – lightweight hardware probe (CPU/RAM/GPU, disk info, etc.)

cwebp.exe – Google’s WebP encoder (required for conversion)

Recommended launcher (.cmd)

Because Windows blocks unsigned .ps1 files, it’s easiest to call the manager via a .cmd file in the same folder; Double-click the Launch-LPM.cmd to start the Manager.

What the Manager Does (High Level)

Hardware probe
On startup it briefly checks your CPU, threads and memory and picks default worker / batch settings that shouldn’t bog your system down.

LaunchBox path detection
It asks where your LaunchBox folder is (e.g. H:\LaunchBox) and remembers that for the current session. It then derives:

Images root → H:\LaunchBox\Images

Data folder → H:\LaunchBox\Data

Optional Defender exclusions
In FULL mode it can temporarily add Defender exclusions for your Images folder to avoid the AV scanner throttling disk I/O during long runs. These are removed when the Manager exits.

Menu-driven workflow
Everything else is driven from the Main Menu: audit, build thumbnails, activate precache, restore originals, clean XML, and backfill missing precache.

Start-Up Prompts (explained)
1. Safe vs Full mode

Choose run mode:
[0] SAFE – low impact (single worker, small batch, no Defender changes)
[1] FULL – uses hardware recommendations (multi-threaded, faster on SSD/NVMe)

SAFE mode – good for old machines, USB drives, or if you’re nervous.

FULL mode – recommended on modern PCs and internal SSD/NVMe.

This just affects default worker/batch values and whether you’re offered Defender exclusions.

2. LaunchBox folder

Where is your LaunchBox installed?
Examples: D:\Games\LaunchBox or H:\LaunchBox

If you just press Enter it uses the default shown (you can change that in the script).
It then prints:

LaunchBox Root – the folder you picked

Images Root – where it will work (creates _Precache / _Originals under here)

Data Folder – where XML cleaning uses metadata

3. Defender exclusion prompt (FULL mode only)

Add temporary Defender exclusion for "H:\LaunchBox\Images"? (y/N)

Y – adds temporary Microsoft Defender exclusions for Images and the _Precache folder to speed up heavy disk activity.

N / Enter – skip; nothing is changed in Defender.

On exit, any exclusions this tool added are removed.

4. Hardware summary

You’ll see a short hardware summary and the recommended defaults:

CPU model & thread count

Total RAM

Default workers / batch for Fast / Balanced / Extreme profiles

This is just for info; you can override any of it later on the Build Thumbnails screen.

Main Menu (all options)

From here on, everything is menu-driven:

Main Menu
  [0] Audit images (recommended first step)
  [1] Build Thumbnails
  [2] Activate Precache (junction swap)
  [3] Restore Originals
  [4] Clean XML references
  [5] Backfill missing precache from Images
  [6] Exit
Select [0..6] (default 0):

Below is what each option does and every question you’ll see.

[0] Audit images – “What could I save?”

Use this FIRST on a new setup. It’s read-only.

Prompts

Quick vs full audit

Run a quick sample-based audit (recommended)? (Y/n)

Enter / Y – quick sample (default cap ~250,000 files). Great for a fast preview.

N – full audit of the entire Images tree (can be hours on huge libraries).

Quick mode does not write checkpoints; full mode does.

Checkpoint (full audits only)

If you’ve run a full audit before and stopped it, you’ll see:

Checkpoint file found… Resume from this checkpoint? (Y/N) [Y]

Enter / Y – resumes where it left off using the lightweight ledger file.

N – discards old checkpoint + ledger and starts fresh.

During a full audit, every ~5,000 files it will print:

[Checkpoint] Saved at …, ProcessedCount = N

Output & summary

When done, it writes:

lb_audit.json – machine-readable summary

lb_audit.csv – per-extension breakdown (for Excel/Sheets)

Console summary shows:

total files / image files / non-image files

bytes by zone: Base, _Originals, _Precache (each with GB in brackets)

how many original ↔ precache pairs exist and how many bytes they’ve saved

how many originals still have no precache and how many bytes are sitting there

estimated extra savings if you converted everything

This is what feeds the planning hints you see before a Build run.

[1] Build Thumbnails – “Make / update precache images”

This is the main conversion action.

Step 1 – Choose preset

You’ll see something like:

[0] Fast
[1] Balanced
[2] Extreme
[3] Custom
Select speed/quality preset [default 1]:

Fast – more conservative, quicker, less aggressive compression

Balanced – default sweet spot

Extreme – slowest, aims for maximum size savings

If you choose Custom, you’ll be asked:

Which profile baseline (Fast / Balanced / Extreme)

Whether to force JPEG only (no WebP)

Custom JPEG quality (1–100; lower = smaller files, more loss)

Step 2 – Planning hints (from last audit)

If you have a recent audit, it prints:

=== Planning hints from last audit ===
Audit scope: X files (Y images)
Convertible originals: N files (~AAA.GB), potential extra savings up to ~BBB.GB if fully converted.
Profile Extreme: rough full-library runtime ~5h 50m; estimated recoverable space ~211.39 GB.

This helps you decide if this preset is worth it before you commit.

Step 3 – Worker / batch size

Workers (3):
Batch size (800):

Defaults are based on your hardware/audit. You can:

Hit Enter to accept

Or type a different number of parallel workers and batch size

Step 4 – Category scope (what types of imagery to process)

You’ll see a menu like:

0) All        – Everything under Images
1) Logos      – Clear Logo*, Logo*, Platform Clear Logo*
2) Banners    – Banner*, Steam Banner*, Epic Games Banner* ...
3) BoxArt     – Box - Front/Back/Spine/Full, 3D Box, Reconstructed, Front/Back
4) Screenshots...
5) Fanart...
6) Marquees...
7) Media...
😎 CartsDiscs...
9) Custom     – Type a comma-separated list (e.g. Marquee,Banner)

Prompt:

Choose category numbers (e.g. 0 or 2,5,6). For Custom, choose 9:

0 → All

2,5,6 → just those specific categories

9 → then you type names like Banners,BoxArt (not numbers)

Special handling for Logos:

If Logos are included, you get a “Include Logos in this run? (Y/N)” gate.

This is because LaunchBox really prefers Logos to remain PNG.

Step 5 – Filtered view vs full Images

If you didn’t pick All, the Manager builds a filtered _LBTemp\_view using junctions so the engine only traverses relevant folders. You’ll see:

Heads up: building the filtered view. This can take a while.
Keep an eye on the Explorer window – links will appear as the view builds.

If _LBTemp\_view already exists, you’ll be asked:

Delete _view and rebuild junctions? (Y/n)

Y / Enter – rebuild with new categories

N – reuse existing view if the category scope matches

Step 6 – Final run summary

Example:

=== Run Summary ===
Root         : H:\LaunchBox\Images\_LBTemp\_view
Profile      : Extreme
Workers      : 3
BatchSize    : 500
UseWebP      : True
JpegQuality  : 80
Categories   : Banners, BoxArt, Screenshots, Fanart, Marquees, Media, CartsDiscs
Proceed? (Y/n):

Y / Enter – start the conversion

N – cancel and return to Main Menu (junction view is cleaned up)

Behind the scenes it sends these settings into Build-LaunchBox-Thumbnails-Parallel.ps1, which:

Reads ImagesRoot (full Images or _LBTemp\_view)

Writes WebP precache images under _Precache

Copies the original into _Originals the first time it converts a given asset

[2] Activate Precache – “Use the optimized images in LaunchBox”

This calls the engine with:

Mode = Activate

ImagesRoot = ...\Images

PrecacheRoot = ...\Images\_Precache

The engine does a junction swap so LaunchBox starts using your precache images (while preserving originals in _Originals).

Prompts:

Just a confirmation message + “Press Enter to return to Main Menu” if success.

On error, you’ll see a reason (permissions, missing _Precache, etc.).

[3] Restore Originals – “Undo and go back to full originals”

This is the reverse of Activate:

Mode = Restore

Uses _Originals folder as the source of truth.

Use this if:

You want to revert the library to original quality

You want to change presets and rebuild everything from scratch

Again you’ll see a short message and be returned to the Main Menu.

[4] Clean XML references – “Tidy up image paths in LB XML”

Calls the engine with:

Mode = CleanXml

ImagesRoot + LBData (your Data folder) + _Precache

This scans LaunchBox XML metadata and fixes any image references that:

Point to files that no longer exist

Need to be pointed at new precache paths

You get a completion message and then a “Press Enter to return to Main Menu” prompt.

[5] Backfill missing precache from Images – “Second chance pass”

Use this after you’ve run one or more big conversions and maybe changed presets. It:

Rescans your main Images folder directly

Looks for originals that don’t currently have a precache copy

Converts those and copies originals into _Originals so your safety net stays complete

This is especially useful after:

You added new platforms/games

You did earlier partial runs with different categories or presets

You want to push any remaining unconverted originals through with a more aggressive profile

Prompts

Confirmation

This will rescan your main Images folder... Proceed with backfill now? (Y/n)

Profile choice

Choose profile for backfill:
  [0] Balanced (recommended)
  [1] Extreme (slower, aims for maximum savings)
Select [0/1] (default 0):

Workers / batch

Shown and editable (same as Build).

Backfill summary

=== Backfill Summary ===
ImagesRoot  : H:\LaunchBox\Images
PrecacheRoot: H:\LaunchBox\Images\_Precache
Profile     : Extreme
Workers     : 4
BatchSize   : 5000000
UseWebP     : True
JpegQuality : 80
Run backfill with these settings? (Y/n):

Y / Enter – runs a targeted pass that only acts on originals with no precache.

N – cancel.

[6] Exit

Cleanly exits the Manager. If Defender exclusions were applied earlier in this session, they’re removed here.

Safety Notes

The tool is heavily biased toward safety:

Every converted image’s original is stored in _Originals

You can always Restore Originals

Audit is read-only

Feel free to create your own LaunchBox Images folder backup (or the whole LB folder) before large first-time runs on production setups if you're unsure.

Long runs on external USB drives can take many hours; that’s normal with multi-million-image libraries.

If you like this and want to help me out, buy me a coffee! https://buymeacoffee.com/mcflylpm