# Valheim modding

Valheim code mods commonly load through **BepInEx**. The community-maintained **Jötunn** library adds registration helpers and a ready-made development template. These are separate dependencies: a plain BepInEx plugin does not require Jötunn, while a Jötunn-based mod does. The [Jötunn step-by-step guide](https://valheim-modding.github.io/Jotunn/guides/guide.html) is the main source for the workflow below.

> **Quick start:** install the Valheim-configured BepInEx pack, create a project from Jötunn's ModStub, rename the plugin metadata, build a DLL, and confirm one log message in-game before registering content.

## Prepare a test installation

Use a separate game profile or a copy of saves. Follow the [Jötunn installation guide](https://valheim-modding.github.io/Jotunn/guides/installation.html) and the specific [step-by-step guide](https://valheim-modding.github.io/Jotunn/guides/guide.html) for your target version. The latter recommends the **Valheim-configured BepInEx pack** rather than a generic BepInEx download. Start the game once with the loader alone and check its log. If BepInEx itself does not initialize, there is no point debugging your C# project yet.

Decide whether your mod is client-only, server-side, or both. A UI feature may live only on the client. New networked items and behavior usually require compatible versions on the server and clients; test with a separate server before claiming multiplayer support.

## Build a first plugin

Jötunn's [ModStub template](https://github.com/Valheim-Modding/JotunnModStub) supplies a project configured for its library and Valheim references. In Visual Studio, clone or copy it, then rename the solution, project, namespace, assembly name, `PluginGUID`, `PluginName`, and `PluginVersion`. The guide recommends a GUID based on a namespace you control. Keeping the template's GUID risks clashing with another plugin.

The project can use Jötunn's prebuild automation to find installed Valheim assemblies and generate publicized references. If your game folder is not found automatically, the guide documents `Environment.props` values for `VALHEIM_INSTALL`, `BEPINEX_PATH`, and `MOD_DEPLOYPATH`. Do not copy another user's absolute paths. Build **Debug** and confirm the resulting DLL is copied to `Valheim/BepInEx/plugins` or your configured directory. Launch the game and check BepInEx's log for your plugin name and your own one-line startup message.

If the DLL does not load, verify the installed game's runtime, the matching BepInEx pack, the template's target framework and the Jötunn version before adding Unity patches. A successful compile only proves that the project resolved its references; it does not prove that the game loaded the DLL.

## Add content after the load test

Jötunn's [tutorial index](https://valheim-modding.github.io/Jotunn/tutorials/overview.html) covers custom items, pieces, recipes, prefabs and localization. Pick one object type. Inspect the current tutorial for its manager and registration timing; then test the new object through the game's normal acquisition path. For example, a registered item that cannot be crafted or spawned by the intended route is only half implemented. Keep asset names unique, and include only assets you created or can distribute.

When you need a change outside Jötunn's registration helpers, use the [BepInEx plugin guide](https://docs.bepinex.dev/master/articles/dev_guide/plugin_tutorial/index.html) for lifecycle basics and inspect the installed game's code before choosing a Harmony patch. Game internals can change between Valheim updates; document the build you tested.

## Test and package

Test loading, a new world, an existing world copy, uninstall/reinstall, and multiplayer where applicable. Jötunn's [build guide](https://valheim-modding.github.io/Jotunn/guides/guide.html) explains that its Release configuration prepares a package with the DLL and README. Include dependency versions and make clear whether Jötunn is required. A Thunderstore package is a distribution format, not proof of in-game compatibility.

This guide is **unfinished** because it provides a source-backed DLL path but not a version-tested new item with a complete prefab, recipe, icon and multiplayer test. The current Jötunn tutorials remain the authority for those details.
