Add Modding Guide
the_minisip committed
1 parent
ff965a4f43
commit
73070690cb
1 file changed
+210
+210
@@ -0,0 +1,210 @@
|
|||||||
|
<h1><strong>Modding Guide</strong></h1>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This guide explains how to install, manage, and troubleshoot mods for the
|
||||||
|
<strong>Managed Valheim</strong> server. The container includes automatic
|
||||||
|
BepInEx installation and a clean/modded directory separation, making modding
|
||||||
|
safe and predictable across updates.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>1. How Modding Works in Managed Valheim</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The container uses a two‑directory architecture:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><code>/opt/valheim_base</code> — Clean SteamCMD installation</li>
|
||||||
|
<li><code>/opt/valheim</code> — Modded runtime directory</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
SteamCMD updates the clean directory, and the container copies updated files
|
||||||
|
into the modded directory before applying BepInEx. This ensures:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Mods never interfere with SteamCMD updates</li>
|
||||||
|
<li>No rollback errors (<code>state 0x6</code>)</li>
|
||||||
|
<li>Mods persist across updates</li>
|
||||||
|
<li>BepInEx is always correctly patched</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>2. Where to Install Mods</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Mods should be placed in the BepInEx plugins directory:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<pre><code>/opt/valheim/BepInEx/plugins</code></pre>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This directory persists across updates and is safe for:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>DLL mods</li>
|
||||||
|
<li>Thunderstore modpacks (manual extraction)</li>
|
||||||
|
<li>Custom server-side plugins</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<strong>Do not place mods in <code>/opt/valheim_base</code>.</strong>
|
||||||
|
That directory must remain clean for SteamCMD.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>3. Installing Mods</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To install a mod:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Download the mod (usually a ZIP file).</li>
|
||||||
|
<li>Extract the contents.</li>
|
||||||
|
<li>Copy the mod’s DLL files into:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/plugins</code>
|
||||||
|
</li>
|
||||||
|
<li>Restart the TrueNAS SCALE app.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
On restart, BepInEx will load all plugins automatically.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>4. Installing Modpacks</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Thunderstore modpacks can be installed manually:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Download the modpack ZIP.</li>
|
||||||
|
<li>Extract it locally.</li>
|
||||||
|
<li>Copy all <code>BepInEx/plugins</code> contents into:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/plugins</code>
|
||||||
|
</li>
|
||||||
|
<li>Copy any <code>config</code> files into:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/config</code>
|
||||||
|
</li>
|
||||||
|
<li>Restart the server.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The container will not overwrite your modpack configuration.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>5. Updating Mods</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To update a mod:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Download the new version.</li>
|
||||||
|
<li>Replace the old DLL in:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/plugins</code>
|
||||||
|
</li>
|
||||||
|
<li>Restart the server.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
BepInEx will load the updated plugin automatically.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>6. Removing Mods</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To remove a mod:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Delete the mod’s DLL from:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/plugins</code>
|
||||||
|
</li>
|
||||||
|
<li>Remove any related config files from:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/config</code>
|
||||||
|
</li>
|
||||||
|
<li>Restart the server.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>7. Mod Configuration Files</strong></h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Many mods generate configuration files under:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<pre><code>/opt/valheim/BepInEx/config</code></pre>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
These files are safe to edit and persist across updates.
|
||||||
|
Restart the server after making changes.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>8. Troubleshooting Mods</strong></h2>
|
||||||
|
|
||||||
|
<h3><strong>Mod Not Loading</strong></h3>
|
||||||
|
<ul>
|
||||||
|
<li>Check <code>/opt/valheim/BepInEx/plugins</code> for the DLL.</li>
|
||||||
|
<li>Verify the mod is compatible with the current Valheim version.</li>
|
||||||
|
<li>Check BepInEx logs:<br>
|
||||||
|
<code>/opt/valheim/BepInEx/LogOutput.log</code>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3><strong>Server Crashes on Startup</strong></h3>
|
||||||
|
<ul>
|
||||||
|
<li>Remove the most recently added mod.</li>
|
||||||
|
<li>Check BepInEx crash logs.</li>
|
||||||
|
<li>Ensure no mods were placed in <code>/opt/valheim_base</code>.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3><strong>Mod Conflicts</strong></h3>
|
||||||
|
<ul>
|
||||||
|
<li>Disable mods one at a time to isolate the conflict.</li>
|
||||||
|
<li>Check mod documentation for known incompatibilities.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>9. Safe Modding Practices</strong></h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Always back up your world before installing new mods.</li>
|
||||||
|
<li>Use versioned modpacks for stability.</li>
|
||||||
|
<li>Keep BepInEx up to date (the container handles this automatically).</li>
|
||||||
|
<li>Never modify files inside <code>/opt/valheim_base</code>.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
|
||||||
|
<h2><strong>Next Steps</strong></h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="Home">Home</a></li>
|
||||||
|
<li><a href="Quick Start">Quick Start</a></li>
|
||||||
|
<li><a href="Installation">Installation</a></li>
|
||||||
|
<li><a href="Backups">Backup & Restore</a></li>
|
||||||
|
<li><a href="Troubleshooting">Troubleshooting</a></li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
With this guide, you can safely install and manage mods on your Managed
|
||||||
|
Valheim server while maintaining full update compatibility and stability.
|
||||||
|
</p>
|
||||||
Reference in new issue
Block a user