From 73070690cb488974e93158453999843aa048bbb6 Mon Sep 17 00:00:00 2001
From: the_minisip <the_minisip@theminisip.com>
Date: Fri, 16 Oct 2026 13:19:34 -0300
Subject: [PATCH] Add Modding Guide

---
 Modding-Guide.md | 210 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 210 insertions(+)
 create mode 100644 Modding-Guide.md

diff --git a/Modding-Guide.md b/Modding-Guide.md
new file mode 100644
index 0000000..be461f9
--- /dev/null
+++ b/Modding-Guide.md
@@ -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>