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

1. Install BepInEx for Valheim from Thunderstore if you haven't already.
2. Drop ShaderHelperForMac.dll and AssetsTools.NET.dll into BepInEx/plugins/ShaderHelperForMac-DrummerCraig/.
3. 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. Run around for a minute — most pink should be gone.

Upgrading from an older version (v2.x or earlier)

If you ever ran an older release of this plugin and hand-edited per-mod txt files in BepInEx/config/ShaderHelperForMac/, the rule shapes have evolved. Follow the required upgrade procedure below.

Required upgrade procedure:

1. Back up BepInEx/config/ShaderHelperForMac/ (zip the whole folder somewhere safe so you can recover anything you wrote).
2. Delete the per-mod <DllName>.txt files in that folder along with the usefallbackshader.txt, usetransparentshader.txt, useoriginalshader.txt. Leave _vanilla_baseline.cache, and any file beginning with _ alone — those are plugin-managed.
3. Launch the game. Re-derive any rules you actually need with the nearby → patch workflow described below. The modern patch command writes correctly-shaped rules and you'll typically end up with shorter, simpler txt files than you had before. Check my discord for files I use: https://discord.gg/zUngMHPDsz

If this is a fresh install (no prior plugin history), skip this section entirely.

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:

1. 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).
2. Launch Valheim and load any world.
3. Open the F5 console and run shaderhelper capturevanilla.
4. 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

If you see a pink object after install, follow this 3-step workflow. It works for ~95% of leftover pink reports.

1. Stand next to the pink object. Closer is better.
2. 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.
3. 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/<DllName>.txt (one file per mod, named after the mod's BepInEx DLL). Files reload automatically on save. After editing, try shaderhelper reload followed by shaderhelper sweep in the F5 console to apply changes immediately; depending on the specific change, restarting the game is sometimes necessary to see the result.

Lines starting with # are comments. The four sections you'll actually use:

[forcefallback] — for solid pink (props, weapons, armor)

When a piece of geometry shows up pink, add the material name shaderhelper nearby reported:

[forcefallback]
mat:weapons1
mat:CrudeBow_mat

This routes the material to the visible fallback shader. The object renders with its texture (sometimes flat, but at least visible).

[forcetransparent] — for VFX and particles (smoke, glow, sparkles, trails)

When an effect (a flame, sparkle, smoke trail, weapon glow, projectile burst) shows up as pink — or as solid black squares — make it transparent instead:

[forcetransparent]
mat:portal_flame_DO
mat:smoke_ashen_fire
mat:BowArcherGlow

Particle materials almost never look right on the fallback path; transparent is the correct treatment for them.

[useshader] — pin a specific shader to a material

Use this when [forcefallback] doesn't quite look right (e.g. a piece of solid geometry renders flat-white because the fallback can't bind the texture). You explicitly pick the target shader.

Finding the right shader name:

1. Run shaderhelper nearby 15 mod near the broken material. The output line shows shader='SomeShaderName' — that's the original shader the mod authored against.
2. Try one of Valheim's own working shaders as the target. The most common picks:
   • Custom/Piece — solid geometry with proper texture binding (most weapons, armor, props)
   • Custom/Creature — the generic visible fallback (good when Custom/Piece doesn't work)
   • Custom/Vegetation — for plant-like materials
3. Add the rule and reload. Test in-game; if the visual is still wrong, try the next shader on the list.

Examples:

[useshader]
mat:CBDH0s_wheels Custom/Piece
mat:BowIceGlow Custom/Creature _Color=#00000000 _EmissionColor=#00000000

The first line pins crossbow wheels to Custom/Piece (which the fallback path was rendering as flat-white). The second pins a bow's glow material to Custom/Creature AND zeros out its color and emission — the _Color=#00000000 / _EmissionColor=#00000000 tokens force fully-transparent black, which is how you "kill" an unwanted glow without hiding the rest of the bow. Color values are hex #RRGGBBAA.

[prefab] — scope rules to a specific prefab

Some mod materials share names with vanilla materials (e.g. glow_0, smoke). Without scoping, a mat:glow_0 rule could affect vanilla Valheim torches. Adding a [prefab] line tells the plugin "only apply rules in this file under this prefab's hierarchy":

[prefab]
ArmorSapphireFalconChestDO
BowEvoCoreAshlandsNatureDO

Find candidate prefab names with shaderhelper modprefabs <ModName> — it lists every prefab the plugin has attributed to that mod plus their child material names.

Advanced sections (rare)

For completeness, these exist but most users never touch them:

• [fallback] / [transparent] — soft variants of [forcefallback] / [forcetransparent]. Only fire when the plugin already decided the material needs replacement; less aggressive.
• [original] — opt a specific material out of replacement entirely (for mods that manage their own shader replacement at runtime).
• [hiderenderer] — disable a renderer entirely instead of replacing the material. Requires a [prefab] line in the same file. Last-resort tool when nothing else makes the object look right.
• [default] — fallback / transparent / original on its own line; routes every replaceable material in this mod through that action.

v3.2.4

• New shader code for MagicalMounts.

v3.2.0

• Improved automation for fewer rules.
• Updated txt files on my discord.

v3.1.0

• Brand new logic, Vanilla cache and protection.
• Changes too numerous to list.

v2.0.0

New: Per-mod txt configuration files

• Each mod now gets its own .txt file in BepInEx/config/ShaderHelperForMac/ with section-based rules
• Sections: [forcefallback], [forcetransparent], [fallback], [transparent], [original], [default]
• [forcefallback] and [forcetransparent] handle shaders that report isSupported=true but still render pink on Metal
• mat:MaterialName and suffix:_name rules let you target specific materials without affecting the whole mod
• Global BepInEx config prefix entries remain supported for backwards compatibility

New: shaderhelper initmod command

• Auto-generates a starter txt file for a mod from what the plugin has already observed in-game
• Includes confirmed replacements, suspected problem shaders (commented out), and suffix groupings
• Use shaderhelper initmod <DllName> force to regenerate an existing file

New: shaderhelper nearby command

• Logs all materials on renderers within a configurable radius of the player
• Shows shader name, support status, action, and DLL attribution
• Supports mod filter (hides vanilla shaders) and DLL name filter
• Scans CanvasRenderer objects (TextMeshPro/UI elements) in addition to standard renderers

New: shaderhelper reload command

• Reloads all config files without triggering a full sweep

New: shaderhelper loaded command

• Scans all materials in memory, including prefab assets not yet placed in the scene
• Accepts an optional DLL name filter

Sweep improvements

• shaderhelper sweep always reloads config files before sweeping (fixes macOS FileSystemWatcher reliability issues)
• Sweep triggered by the console command now shows a center-screen HUD notification when complete

New Harmony patches

• DungeonGenerator.GenerateDungeon postfix — sweeps after dungeon rooms are instantiated on zone load
• VisEquipment.AttachItem postfix — sweeps immediately when weapons/armour/items are equipped
• AssetBundle.LoadAsset postfix — intercepts materials the moment a bundle is loaded, eliminating first-frame pink flicker

Shader fixes

• TextMeshPro/Distance Field (Surface) — swapped to the non-Surface variant at runtime; fixes pink text on noticeboards and signs
• Hidden/InternalErrorShader — now correctly receives the fallback shader instead of being left unchanged

Bug fixes

• Explicit mat: rules now correctly override the _forceReplacedMaterialIds guard (fixes cases where a material couldn't be moved between transparent and fallback)
• initmod no longer emits suffix rules for materials using canonical Valheim shaders (e.g. draugr_eyes_elite)
• initmod no longer emits entries in [fallback]/[transparent] for shaders covered by built-in defaults (e.g. Legacy Shaders/Particles/)
• shaderhelper nearby uses transform.position instead of bounds.center — fixes incorrect distances for TextMeshPro sub-mesh renderers whose bounds are uninitialized

Configuration changes

• Default All Transparent now defaults to false — mods must be explicitly configured
• Removed Mod Enabled toggle (shader replacements are in-memory and cannot be undone without a restart)
• Config entries renamed for clarity: Default All Transparent, Force Transparent Shader Prefixes, Force Fallback Shader Prefixes, Periodic Sweep Interval
• Assembly version updated to 2.0.0

v1.2.0

• Sweep interval made configurable via BepInEx config
• Periodic sweep skips when no local player is present (main menu, loading screen)

v1.1.0

• Added usefallbackshader.txt — replaces broken shaders with a solid visible placeholder instead of making objects invisible
• Added shaderhelper scan and shaderhelper dumpmod console commands
• ZNetScene.Awake postfix patch — catches Jotunn mod prefabs registered after startup sweep

v1.0.1

• Additional logic analysis to capture pinks