ShaderHelperForMac

ShaderHelperForMac

⚠️ Apple Silicon Macs only. This mod will not help on Windows, Linux, or Intel Macs — and may produce harmless warnings on those platforms. Don't install it unless your Valheim is running on an M1/M2/M3/M4 Mac.

What it does

Many Valheim mods ship Unity asset bundles with shaders compiled only for Windows. When the game loads them on a Mac with Apple's Metal graphics API, Unity can't find a Metal-compatible variant and substitutes a bright magenta/pink error material — bows, weapons, armor, particle effects, the whole thing turns hot pink. This plugin scans every loaded mod, identifies broken shaders, and replaces them with renderable substitutes so your modded game looks better.

It's a compatibility shim, not magic — fallback materials don't always look identical to what the mod author intended (textures may render flat, glow effects may look dimmer) — but the alternative is unplayable pink.

Install

• Install BepInEx for Valheim if you haven't already.
• Drop ShaderHelperForMac.dll and AssetsTools.NET.dll into BepInEx/plugins/ShaderHelperForMac-DrummerCraig.
• Launch Valheim. The plugin starts automatically.

That's it for most installs. The plugin scans your mods at startup and fixes everything it can detect.

Vanilla shader protection (cache included)

The plugin protects vanilla Valheim materials from being touched by accident using a vanilla-baseline cache — a list of every material and shader Valheim itself ships with. The plugin refuses to replace anything in that list, even when a mod-side rule accidentally targets a vanilla name.

You don't need to do anything with this in normal use. The cache ships bundled inside the plugin DLL and is auto-extracted to BepInEx/config/ShaderHelperForMac/_vanilla_baseline.cache on first launch — it works out of the box for the Valheim version this release was built against.

When to rebuild the cache:

• After a major Valheim update. Shipped material/shader names may have changed; you'll see a [VanillaCache] version drift: cache was produced for Valheim 'X' but this install reports 'Y' warning in BepInEx/LogOutput.log when the version doesn't match.
• If vanilla content starts rendering wrong (vanilla weapons, terrain, or NPCs going pink or being replaced after previously-correct operation).

How to rebuild:

• Move every non-ShaderHelperForMac DLL out of BepInEx/plugins/ somewhere else temporarily (otherwise mod-side materials contaminate the captured baseline — the new cache must be built from a clean install).
• Launch Valheim and load any world.
• Open the F5 console and run shaderhelper capturevanilla.
• Quit Valheim, move your mod DLLs back into BepInEx/plugins, and relaunch.

The new cache is now authoritative for your Valheim version. You only need to do this rarely — typically just once after a Valheim update.

When something is still pink

Create a txt file with corrections. Several are included in the config/ShaderHelperForMac in this install. You can also find them on my discord server.

Additionally, here is a 3-step workflow to get you started on making your own.

• Stand next to the pink object. Closer is better.
• Open the F5 console and run:

shaderhelper nearby 15 mod

This lists every nearby mod material with its shader name, current state, and owning DLL. Look for lines whose action=Original (meaning the plugin has no rule for it yet) and note the mat: name and the dll= value.

• Run shaderhelper patch. The plugin auto-writes a fix rule into the right per-mod txt file and applies it. The pink should disappear.

If shaderhelper patch reports "no rules to add" or the object is still pink afterward, the material may need a more specific rule — see the section reference below.

Hand-editing per-mod txt files

Per-mod configs live at BepInEx/config/ShaderHelperForMac.txt (one file per mod, named after the mod's BepInEx DLL). Files reload automatically on save. After editing, try shaderhelper reload followed by shaderhelp