ShaderHelperForMac

A BepInEx plugin for Valheim on Apple Silicon (ARM Mac) that fixes broken/pink materials caused by mod shaders compiled without Metal GPU support.

Do not run this mod unless you are on an Apple Silicon Mac.

Yes I play on a Mac...not because I want to but it is all I have and cannot afford to buy a PC at this time. For all us ARM Mac users, this is a work in progress but has already made a meaningful difference to me and I am wanting to share it with you. You know the lovely Magenta/Pink shader experience we have when no Metal shader is available. This mod CAN HELP but not fix everything. If a mod still shows pink after trying the options below, you can submit the mod name in my appropriate Discord channel and I MAY analyse it. No guarantees on response time — I have a full-time job and a family. Below are sample before and after images when using CoreWoodExtras and WardIsLove mods.

Before	After

The Problem

Valheim mods ship Unity asset bundles with shaders compiled only for Windows (Direct3D 11). When loaded on macOS with the Metal graphics API, Unity cannot find a Metal-compatible shader variant and substitutes a bright magenta/pink error material. This happens silently — the mod author doesn't need to do anything wrong for it to occur.

Why It May Not Always Work

Several factors affect whether this plugin can fix a pink shader. Understanding these helps set expectations:

• Bundle byte layout varies by Unity version. The plugin reads shader names directly from the raw bundle binary. Different Unity versions and build tools place data at different byte offsets. If the layout doesn't match a known pattern, the shader's name can't be read and it becomes unattributable — meaning DLL-based config overrides won't apply to it.

• shader.isSupported is not always accurate. Unity's runtime check is the primary gate for detecting broken shaders, but some shaders report isSupported = true while still rendering pink on Metal. These slip through undetected.

• Shaders loaded after startup are not always caught. The plugin sweeps at scene load and after ZNetScene.Awake. Mods that load shaders or instantiate objects later (e.g. via coroutines or events) may appear after the sweep and remain pink until the next scene load. Running shaderhelper sweep from the console forces an immediate re-sweep.

• Valheim's own shaders exist in both the game and mod bundles. Shaders like Custom/Piece and Custom/Creature are built into the game with Metal support, but mod bundles often ship their own copies without Metal support. The plugin tries to distinguish these using instance IDs, but the detection is incomplete — some game-owned copies may be incorrectly replaced.

• Unattributable shaders (dll='unknown') cannot be controlled per-mod. When the scanner can't read a shader's name from its bundle, that shader has no DLL association. Adding the mod's DLL name to any config file has no effect on those materials. With DefaultAllTransparent = true they still go transparent; with DefaultAllTransparent = false they stay pink.

• Transparent is not always the right fix. Making a shader transparent eliminates pink but hides the geometry entirely. For particle effects this is usually fine; for buildings or furniture it means invisible objects. Use usefallbackshader.txt for mods where visible-but-untextured is better than invisible.

• Some mods manage shader replacement themselves. Mods using Jotunn's JVLmock_ system replace their own shaders at runtime. The plugin is already aware of these and skips them. Other mods that do custom runtime replacement may conflict — add them to useoriginalshader.txt to leave them untouched.

• The fallback shader carries no textures. When a material is replaced with the fallback, it renders as a solid flat color with no textures, normal maps, or emission. This is a compatibility shim — correct visuals require the mod author to recompile their shaders with Metal support.

How It Works

At startup the plugin:

1. Scans all .dll and .bundle files in BepInEx/plugins/ for shaders, recording which DLL each shader name came from.
2. Selects a fallback shader — tries Custom/Piece, then Custom/Vegetation, then Standard, preferring one with isSupported = true.
3. Records canonical Valheim shader IDs — to distinguish the game's own supported copies from unsupported bundle copies of the same name.
4. Installs Harmony patches — ZNetScene.Awake postfix triggers a re-sweep after Jotunn registers custom prefabs; Shader.Find postfix intercepts runtime shader lookups for broken shaders.
5. Sweeps all loaded materials on every scene load, applying replacements based on the config files and settings.

Installation

Requirements

• Valheim (any recent version) on Steam, Apple Silicon Mac
• BepInEx for Valheim installed

Steps

1. Create the folder:

   BepInEx/plugins/ShaderHelperForMac-DrummerCraig/
   

2. Copy both files from the download into that folder:

   ShaderHelperForMac.dll
   AssetsTools.NET.dll
   

3. Launch Valheim. The plugin initializes automatically.

Configuration

BepInEx config file

Located at BepInEx/config/drummercraig.shaderhelperformac.cfg. Edit with any text editor.

Text config files

Located at BepInEx/config/ShaderHelperForMac/. One DLL name per line (without .dll), case-insensitive. Lines starting with # are comments. Files are watched live — changes take effect without restarting (run shaderhelper sweep to apply immediately).

To find a mod's DLL name, look in BepInEx/plugins/. The filename without .dll is what to use (e.g. DarkWoodFurnitures).

Console Commands

Open the in-game console with F5.

Troubleshooting

Objects are still pink

Run shaderhelper pink from the console while near the pink objects. Check BepInEx/LogOutput.log for the output — it shows every unhandled pink material with its shader name and whether it could be attributed to a DLL. If the DLL is known, add it to usetransparentshader.txt or usefallbackshader.txt. If the DLL shows as unknown, the scanner couldn't attribute it — enable DefaultAllTransparent = true in the .cfg file to handle these automatically.

Objects that should be visible are transparent

The plugin made them invisible because their shader was broken. Find the mod's DLL name in BepInEx/plugins/ and add it to usefallbackshader.txt. Takes effect on the next scene load (or immediately after shaderhelper sweep).

A mod looks wrong after being set to fallback (flat color, no textures)

Expected — the fallback shader has no textures. This is a compatibility placeholder. Correct visuals require the mod author to recompile with Metal support.

The plugin seems stuck at startup

The scanner reads all mod bundles at launch. With many large mods this takes a few seconds. The log will show [N/76] 'ModName' — X shader(s) lines as it progresses.

Game won't load at all

Check BepInEx/LogOutput.log from the top. This is almost always a different mod crashing during Chainloader::Start. Look for Exception or Error lines before the [ShaderHelperForMac] entries.