CustomMonsterReplacer

CustomMonsterReplacer

A monster manager for Valheim. Give any vanilla creature a custom 3D model, or turn a vanilla prefab into a brand-new creature of your own, without touching its AI, stats or loot. Everything is managed from a web GUI while the game runs.

A Valheim BepInEx 5 plugin built on Jotunn.

Two kinds of entry

| | Replace | Creature | |---|---|---| | What it does | Swaps a vanilla prefab's visuals in place | Clones a vanilla prefab under a new registered name | | AI / stats / loot | Untouched — stays exactly vanilla | Yours to set: health, faction, AI ranges, spawn biomes | | Networking | None — purely visual | A real prefab, registered in ZNetScene | | Good for | "make the greydwarf look like this" | "add a troll-sized bear that spawns in the Black Forest" |

Features

• Monster manager GUI at http://127.0.0.1:8777/ — add and remove entries, tune scale, position and rotation, toggle individual meshes, and set health, faction and spawns.
• GLB models, loaded with a built-in GLB/GLTF parser. Rigged models animate: skin joints are remapped to the vanilla skeleton by name, with a proximity-weighted fallback.
• Animated creatures from Unity AssetBundles, with walk and attack clips.
• Skeleton overlay in the GUI to visualise which bones matched, and a generated Blender auto-weighting script at /armature_script for content creators.
• Auto height fit — scale a model to a target height in metres, or match the source prefab's own height.
• Distance culling, so custom models stop being processed when far away. The log prints distance culler: N custom model(s) in the world; if that number is stuck at 0, culling is broken.
• A pre-1.4 config migrates itself once into the new entry list, so upgrading is silent.

Requirements

• BepInExPack Valheim (automatic)
• Jotunn (automatic)
• Valheim 1.0.16. The mod is built against it; a game update can break its patches and there is no way to detect that from inside the plugin.

Installation

Install through your mod manager. All five payload files must end up in BepInEx\plugins\CustomMonsterReplacer\, next to the DLL — the model and bundle filenames are resolved relative to it.

Manual install: copy CustomMonsterReplacer.dll, trooper.glb, ogre.glb, valheimbear and valheimogre into that folder.

Bundled models

Every entry has its own model, so nothing is ever removed from the folder.

| File | Size | Notes | |------|------|-------| | trooper.glb | 17 MB | 25 parts, skeleton-bound onto the greydwarf rig | | ogre.glb | 11 MB | Alternative model | | valheimbear | 42 MB | AssetBundle, BearPlayer, with walk/attack clips | | valheimogre | 43 MB | AssetBundle, OgrePlayer, troll-sized |

The package is ~109 MB, which is large by design: two of those files are Unity AssetBundles, which are already compressed and do not shrink further.

> The AssetBundles were built with Unity 6000.0.75f1 exactly, matching the engine in > this Valheim build. A different editor version produces bundles that will not load.

How to use

1. Start the game and open http://127.0.0.1:8777/.
2. Add an entry and pick its kind — Replace (target a vanilla prefab) or Creature

(clone one, then give it health, faction and spawn entries).

1. Choose a model, then tune scale (auto-fit or manual), position/rotation

offsets, and toggle individual meshes. Changes auto-apply and are saved to the config.

1. In-game, summon or spawn the creature and check it against the vanilla one.

Want to use your own model? Export a GLB rigged to a GreydwarfArmature skeleton — download the generated script from /armature_script — and drop it next to the DLL. It will appear in the GUI's model list.

Configuration

A JSON file created next to the DLL on first load: BepInEx\plugins\CustomMonsterReplacer\monsterreplacer_config.json. The GUI owns this file — edit entries in the browser rather than by hand, or your changes will be overwritten on the next save.

{
  "EnableWebServer": true,
  "WebPort": 8777,
  "Monsters": [
    { "Id": "greydwarf", "Kind": "Replace", "TargetPrefab": "Greydwarf",
      "ModelFile": "trooper.glb", "TargetHeight": 2.0, "CullDistance": 60.0 },
    { "Id": "dfgbear", "Kind": "Creature", "TargetPrefab": "Greydwarf",
      "BundleFile": "valheimbear", "BundlePrefab": "BearPlayer", "Health": 120.0 }
  ]
}

| Key | Default | Description | |-----|---------|-------------| | EnableWebServer | true | Serve the manager GUI. | | WebPort | 8777 | Port for the GUI. | | Monsters | see above | The entry list. | | CullDistance | 60.0 | Metres before a custom model is culled. | | UseTargetHeight | true | Auto-fit to a target height. | | TargetHeight | 2.0 | Target height in metres. | | ManualScale | 0.01 | Scale used when auto-fit is off. | | PositionX/Y/Z, RotationX/Y/Z | 0 | Offsets; rotation in degrees. | | DisabledMeshes | [] | Mesh names to hide. |

Notes & limitations

• The GUI's 3D model preview needs an internet connection (it loads three.js from a CDN). Every other endpoint works offline.
• Skeleton binding applies to the Replace path. Without it, or on a target with no usable skeleton, the model attaches statically and materials fall back to the target's shader — a magenta error material means no shader was found.
• Bundle creatures need their walk/attack clips baked in; a bundle built without them animates as a Generic rig.

Changelog

See CHANGELOG.md.

Support