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

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.

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).
3. 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.
4. 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 }
  ]
}

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

If this mod has made your journey through the Tenth World a little better, consider tossing a coin into my Ko-fi jar: https://ko-fi.com/draugrforgedgaming. Your support keeps the forge hot and the mead flowing! Skål!

Changelog

All notable changes to CustomMonsterReplacer.

[1.4.3]

• Package fix: Blurrg.glb was shipping in the deployed profile but was missing from the 1.4.2 package, so anyone installing from Thunderstore got a mod one model short of the one the author had been testing. The package now stages models straight from the build output rather than from a hand-kept list, so this cannot silently recur.
• Re-verified against Valheim 1.0.16.

[1.4.2] - Performance

Four separate causes of lag, all real, all fixed:

• updateWhenOffscreen was forced on for every custom SkinnedMeshRenderer, so the CPU re-skinned all 25 trooper.glb parts (and the bundle meshes) every frame for every greydwarf at any distance. It is now explicitly off.
• AnimatorCullingMode.AlwaysAnimate on bundle creatures is now CullUpdateTransforms. Bones are still written, so culling does not make them pop.
• MonsterRenderCuller registered itself in Attach(), which only runs on the prefab, so no live clone was ever in the ticker's list and nothing was ever culled. Registration moved to OnEnable/OnDisable. The log now prints distance culler: N custom model(s) in the world whenever N changes; if that stays at 0, culling is broken again.
• The /options prefab cache walked all ~4,600 entries of ZNetScene.m_prefabs with a GetComponent<Character> on each, every 2 seconds. It now rebuilds only when the loaded prefab count changes.

Also: the model's Colliders are disabled alongside its renderers when culled, and Animator.parameters (which allocates a new array on every call) is no longer read from Update.

[1.4.0] - Creature mode and the monster manager

• Two kinds of entry. Replace swaps a vanilla prefab's visuals in place, keeping its AI, stats and loot. Creature clones a vanilla prefab under a new registered name with its own mesh, health, faction, AI ranges and spawn entries.
• The tuning GUI is now a monster manager. Entries are added and removed in the browser rather than by editing JSON.
• Pre-1.4 configs (one with a root TargetPath) migrate once into three entries: the old visual replace, the old Creature block, and the code-defined ogre.
• Creatures are patched in place on re-apply rather than rebuilt, because the clone is registered in ZNetScene and destroying it would break spawn.
• Added the valheimbear and valheimogre AssetBundles (BearPlayer, OgrePlayer) and ogre.glb.

[1.2.0]

• Skeleton binding: GLB skin joints are remapped to the vanilla Greydwarf skeleton by name (proximity-weighted fallback) so rigged models animate.
• Live web tuning GUI (http://127.0.0.1:8777/): scale/position/rotation sliders, per-mesh enable/disable, auto-height-fit, skeleton overlay, and a generated Blender armature script for content creators.
• Config moved/kept as JSON (monsterreplacer_config.json) beside the DLL, saved automatically on tuning.

[1.0.0] - Initial release

• Replaces the Greydwarf visual with the bundled trooper.glb model via custom GLB/GLTF runtime parsing.
• Uses Jotunn's PrefabManager.OnPrefabsRegistered.
• Requires Jotunn (Jotunn 2.30.x).