STUDIOBASCINETCommunity ↗

PLAYER & SERVER OWNER GUIDE · FIELD GUIDE

ModGate
guide.

Less setup between you and your server.

ModGate checks what a Valheim server needs, reuses matching installed mods, and prepares supported downloads together. This guide covers the 0.4.4 release: install the connector once, review your setup, restart, and join again.

Start here ↓Download ModGate ↗
ModGate studio cover

THE SHORT CHECKLIST

Before you start

  • BepInEx already installed; ModGate does not install or update it.
  • The same ModGate version on the server and every joining player. This guide covers 0.4.4.
  • A normal BepInEx launch, with enough disk space for profiles, downloads, and restore points.

These instructions describe the documented defaults. Check your installed release notes and server rules if a recipe, key, or setting differs.

1. Install the connector once

Close Valheim or stop the server normally. Merge the release package’s BepInEx folder into the installation you actually launch. Both components are needed:

BepInEx/plugins/ValheimModGate/ValheimModGate.dll
BepInEx/patchers/ValheimModGate/ValheimModGate.Preloader.dll

The preloader belongs in patchers. Keep existing profiles and configs when upgrading, and update both files on the server and clients. Mod managers may use additional author/package folders; keep launching the same external manager profile. ModGate cannot show its prompt to a player who has not installed it.

2. Download the server’s mods together

  1. Launch through your usual BepInEx setup and connect normally. A matching setup continues; a different setup opens ModGate.
  2. Review the selected required mods. Choose optional mods and dependency suggestions you want.
  3. Choose Download and review. ModGate reuses accepted installed mods and prepares selected supported downloads.
  4. Review the result, then choose Install and restart, or installation on the next launch.
  5. Join the server again after restarting. ModGate does not reconnect automatically.

Windows supports automatic relaunch. Other launchers can use a manual restart. Thunderstore and Hexium are the normal automatic sources; Nexus entries open a manual download page. Follow the Nexus author’s instructions, install, restart, and retry.

ColourMeaning
GreenInstalled version accepted by the server.
RedA required mod is missing.
YellowA version change is needed, or an optional mod is absent.

3. Keep different servers ready

Press Shift + F6 to open ModGate in menus or while playing. Gameplay and camera input are blocked while the panel is open. Keep up to four server profiles plus Offline; use Activate & restart to switch.

The Mods tab controls permitted selections, Configs edits settings, Mod details explains packages, and Activity shows progress and errors. Optional sections start expanded and can be collapsed. Profiles retain separate applicable configs. New ones can copy active settings, copy Offline settings, or start fresh.

Reload configs reloads eligible current files where supported; each mod decides whether settings take effect immediately. Queued changes still require restart. Windows password remembering is enabled by default, uses Windows-account encryption, and saves only after a successful connection. You can disable it or forget a password.

4. Create the server’s requirements

  1. Install both components and start the server once.
  2. Stop it and review BepInEx/config/ModGate/server-mods.json.
  3. Confirm each mod’s side and download mapping, plus extra-mod and version rules.
  4. Restart, let background lookup finish, and review lookup-report.json.
  5. Test from a separate client using the same ModGate release.
sideWho needs it
requiredJoining players need an accepted version.
optionalPlayers choose whether to include it.
serverOnlyNever offered to players.
clientOnlyRequired for players; its ordinary plugin is suppressed on dedicated servers.

New names containing “Server Side” or “Serverside” default to server-only. Review them: names cannot classify everything reliably. Existing owner classifications are preserved. Keep server-id.txt when upgrading so saved profiles recognise the server.

5. Correct downloads and compatibility rules

Installed DLL metadata is the authority for plugin identity and version. A package’s manifest version may differ; do not change the required DLL version merely to match its package number.

Use package for an exact package mapping or downloadUrl for a supported version-specific HTTPS Thunderstore/Hexium link. For manual Nexus installs, set nexusUrl and leave downloadUrl empty. For a loose DLL, copy its original manifest into its generated folder under BepInEx/config/ModGate/manifests/<plugin-guid>/manifest.json, then restart.

allowExtraClientMods controls additional client mods. allowNewerClientVersions permits newer installed versions; per-mod allowNewerVersion overrides it. These rules cannot guarantee another mod’s compatibility. An asterisk in a text field protects it from refresh; it is not a version wildcard.

6. Configs, updates, and server health

Connected admins open Server configs through Shift + F6. Remote access requires normal server-admin-list membership and the owner-issued code from BepInEx/config/ModGate/admin-access.key. Share it privately. Server saves queue for restart; supported running-mod configs may reload live.

Automatic server updating starts off. Enable autoUpdateOnRestart, then autoUpdateAllMods or individual autoUpdate choices. Eligible updates run at dedicated-server startup. They exclude BepInEx, ModGate, loader/patcher packages and manual Nexus entries. Check server-update-report.json.

Server health uses the same admin access and reports process CPU/memory, connection latency/jitter, traffic, players, uptime and update timing. CPU 100% means one logical core. GPU and temperature data are not collected. See the full server-owner guide for detailed examples.

7. Recover when setup stops

A mod cannot download or a dependency blocks setup

Open Activity or the setup log for the actual package and error. Retry after correcting the cause. Override and continue anyway can prepare available files, but cannot make missing hard dependencies load or force the server to accept an incomplete setup.

Restart did not activate the profile

Check that the preloader is in patchers and that you launch the same game installation or external manager profile. Try the next-launch option and inspect restart/install logs.

A saved profile is damaged

Use Check profile, repair eligible files, or choose Restore…. Restoring an old setup does not change a live server’s requirements.

Server auto-updates fail with an SSL error

The host needs system curl, working HTTPS, current certificate authorities and a correct clock. Failed updates keep installed files; inspect the update report.

Remove all downloaded mods removes ModGate’s server-profile copies and restores the original Offline setup. It does not uninstall BepInEx.

8. Logs and help

Use Activity or Open setup log first. Useful files are:

BepInEx/LogOutput.log
BepInEx/ModGate/logs/profile-setup.txt
BepInEx/ModGate/install-error.txt
BepInEx/ModGate/restart-status.txt
BepInEx/ModGate/restart-error.txt

Activity can create a local support ZIP under BepInEx/ModGate/reports/. It excludes password data and raw configs, and is not uploaded automatically. Review it before sharing. Include your ModGate version, exact error and the action that caused it; never share passwords or the admin key.

Review downloads and trust the server’s choices: mods run code on your computer. ModGate keeps archive containment, protected-path checks, receipts and recovery journals; a matching mod list still does not prove runtime compatibility. Get help in the support Discord.

KEEP THESE HANDY

Project reference & help

Use the author’s project notes for current release requirements and changes. If you need help, include the installed version, what you tried, and the relevant log excerpt.

Review logs before sharing. Do not include server passwords, admin access keys, or other private information.