Beastheim Server Mods

Server management, character protection, mod enforcement, and community monitoring for Valheim dedicated servers.

Beastheim Server Mods is a collection of configurable server-management tools originally developed for the Beastheim Valheim community.

Built to help server administrators maintain fair progression, manage limited player slots, enforce modpack consistency, and monitor server activity, it combines several essential systems into one plugin.

Features

• Server-Authoritative Characters: Bind each player's character to your server, preventing the normal import of items, equipment, and progression from other worlds. Includes persistent saves, controlled character resets, revision history, backups, and administrative recovery.
• Modpack Enforcement: Check connecting players against the server's required and optional mods. Reject missing, modified, incompatible, or unauthorized plugins with clear, player-facing explanations.
• AFK Detection & Management (optional, off by default): Detect inactive players, issue configurable warnings, and disconnect idle players to free up limited server slots. Includes final-save handling to help protect character progress.
• Discord Webhooks & Monitoring (optional, off by default): Send server status, player connection activity, and administrative alerts to separate Discord channels without blocking gameplay.
• Connection Status & Integration: Provide connection-state information and a limited server-side identity API for other compatible mods.

Built for Beastheim. Available to the Community.

Although developed for Beastheim, the systems are configurable for other Valheim dedicated servers, from private groups to larger multiplayer communities.

Installation: Install on the dedicated server and on every client that connects. The plugin goes in BepInEx/plugins. The server is the authority; clients answer its questions and show its messages. A client without the plugin cannot join a server that enforces it. Requires BepInExPack for Valheim.

Compatibility: Built and tested against Valheim 1.0.17 with BepInExPack 5.4.2350 and 5.4.2351.

Status. Validated on Valheim 1.0.17 with a real client against a real dedicated server (BepInExPack 5.4.2350): first-join registration, mod-check admission, the character surviving logouts, reconnects and two server restarts byte for byte, a second character being refused with a readable message, and a clean character store afterwards. It has not yet had a long run on a public server, and it is built for modpacks that use the Jotunn library (as the Beastheim pack does). Please report problems with the Beastheim Server Mods lines of the log and what you were doing.

What players see

When the server turns a player away, the main menu shows a dialog titled Cannot join this server with the reason and an OK button (Enter also closes it). Examples:

• A second character on an account: Only one character is allowed per player on this server. Your registered character is <name>. Select that character and join again. Lost your character? Contact a server administrator.
• A mod problem: Beastheim mod check failed. followed by lines such as Install required: ..., Remove not allowed: ... or Update or reinstall: ... naming the mods, and Restart Valheim after changing mods, then try again.

The dialog is drawn by this mod with the game's own font, because the game's built-in connection-failed panel is shared with the game and other mods and can come out blank. A player without this mod installed cannot receive the reason and sees the game's stock "Incompatible version" message instead.

Quick start for server operators

1. Install this mod on the server and give every player the same modpack that includes it.
2. Put the original DLL of every mod players must run in BepInEx/config/BeastheimServerMods/required/ (one folder per mod is fine), and any mod players may add in optional/.
3. In BepInEx/config/beastheim.servermods.cfg set [Enforcement] Mode = Enforce and [Characters] Mode = Enforce, then start the server.
4. Join with a test client first. Check the server log for Beastheim Server Mods ... loaded and Policy loaded: N required.
5. Back up BepInEx/BeastheimCharacters (see Backups below). It is not part of the world save.

Start with Mode = WarnOnly if you want to see what would be refused before refusing anyone.

1. The mod check

Policy is two folders of the mods' own DLL files on the server:

BepInEx/config/BeastheimServerMods/required/   every client must have these, identical
BepInEx/config/BeastheimServerMods/optional/   a client may have these, identical if present

Copy each mod's original, unmodified DLL from its Thunderstore download into the right folder. Do not copy files from a compatibility or shadow cache. Edits to the policy folders are picked up live; no restart is needed.

At connection time the client reports every plugin it has loaded with a hash of its file. The server compares that with the folders and decides:

Mode is Enforce (refuse), WarnOnly (log what would be refused, admit everyone) or Disabled. Server administrators listed in Valheim's adminlist.txt may be allowed through a failed check (AllowAdminBypass), and it is logged when they are.

The first time a client joins, hashing its mods takes some time. It runs on a background thread and its duration is logged, so a slow join can be measured rather than guessed at.

2. Server characters

Set Characters.Mode = Enforce on the server (restart required) and every player has exactly one character.

• A player's first join registers the character they selected. A brand-new character must really be new (default items and recognised mod data only); a stolen, edited or pre-played character cannot be enrolled as "new".
• Every later join must present that same character. A different character, or one that has gone backwards or sideways from what the server holds, is refused with a reason. The server never swaps or repairs a character.
• The server keeps every saved revision, so a client's bad day does not become your data loss.
• Character names are unique (case, accents and look-alike letters are normalised) and 15 characters or fewer.
• Reset. Players can start over from the Character button in the Esc menu. The screen shows whether a reset is allowed right now, the cooldown remaining and how many resets are left in the rolling window, before anything destructive is confirmed. Defaults: 3 resets per rolling 30 days, a 24 hour wait before registering the next character, and the old character archived for 30 days (its name stays reserved for that long; its character ID is retired permanently).
• Both local and Steam Cloud characters are supported; the server reads what the game actually loaded.
• Protocol limits and rate limits apply before a player is even logged in, so a hostile client cannot flood the server with uploads.

Administration

Dangerous recovery actions are not in-game commands. They are done offline by the server operator with the separate bsm-admin tool (distributed to server operators only, never part of this package, never needed by players) (adopt a different character, roll back, restore, archive, purge, hold, cooldown changes, backups, audit). Each shows a parsed diff of what would change, asks for an explicit typed confirmation, takes a backup first and writes an audit entry.

Backups: read this

The character store (BepInEx/BeastheimCharacters) is production data. A hosting panel's backup of the world may not include it. The mod writes verified snapshots on a schedule and after every enrollment, reset or restore (Characters.Backup), and can mirror them to a second folder (Backup.MirrorFolder). Put that folder somewhere that is backed up, and rehearse a restore.

3. Configuration

Everything is in BepInEx/config/beastheim.servermods.cfg (created on first start). The settings that matter most:

[Enforcement]
Mode = Enforce                 # Enforce | WarnOnly | Disabled
BlockUnlistedPlugins = true
MissingManifestPolicy = Reject
InternalErrorPolicy = Reject
EmptyPolicyBehavior = Reject   # the default: an empty policy folder is a fault, not "allow all"

[Characters]
Mode = Enforce                 # Off (default) | Enforce; needs a restart

[Afk]
Enabled = false                # the default: completely inert
TimeoutMinutes = 30
WarningMinutes = 5,1           # minutes REMAINING at which a warning is shown

Changes to the file are applied while the server runs, except Characters.Mode.

Idle players (optional, off by default)

With [Afk] Enabled = true a player who shows no sign of life for TimeoutMinutes is warned, then removed. Signs of life the server can see are movement beyond ActivityRadiusMeters, an emote change, a chat message, and (for up to SleepMaxMinutes) sleeping in a bed. Nothing counts while a player is loading, being admitted, or inside a character reset or final save, and a new player gets GraceSeconds before the clock starts. Admins (ExemptAdmins) and ExemptSteamIds are never removed.

When the timeout is reached the server asks the player's game for its character through the same path used for logout and reset, waits at most FinalSaveWaitSeconds for the save to be uploaded, validated, committed and acknowledged, tells the player, waits DrainSeconds so the message arrives, and disconnects. If the save is not confirmed in time the player is still removed, the last acknowledged revision is kept, the problem is logged (and published to the admin webhook), and the player is told the server could not confirm their latest progress was saved, so recent changes may be lost. Without Characters.Mode = Enforce nothing can be confirmed, so the notice always carries that warning. Other Beastheim mods can pause the clock briefly with BsmAfk.Suppress and BsmAfk.Release. Do not run it together with the separate AfkDetector mod.

[Afk]
Enabled = true
TimeoutMinutes = 30
WarningMinutes = 5,1
ActivityRadiusMeters = 3
GraceSeconds = 60
FinalSaveWaitSeconds = 15
DrainSeconds = 3

4. Discord webhooks (optional)

Webhook settings live in their own file, BepInEx/config/beastheim.servermods.webhooks.cfg (created on the server only), so the secret URLs never sit in the main config. Leave the URLs empty and the feature does not exist. Set Discord.PublicWebhookUrl and/or Discord.AdminWebhookUrl (two separate channels) and choose events in [Events].

• Delivery is asynchronous with a bounded queue, timeouts, retries with back-off, rate limiting and flood merging. A Discord outage, slow response or revoked webhook can never delay a login, a character save or the server.
• Messages contain no character contents, no credentials and no webhook addresses. Player-controlled text is sanitised and cannot ping anyone. Steam IDs go only to the admin channel.
• Only https addresses on Discord's own hosts are accepted. The URL is a secret: it is never logged.

5. For other mods

Beastheim.ServerMods.Status.BsmStatus is a read-only status surface (current connection state, safe rejection text). It reports discrete states only. It has no progress percentage because the game does not provide one.

Beastheim.ServerMods.BsmIdentity (server only, ApiVersion 1) lets other server-side plugins ask one question: which character did Server Characters verify this connection to be? TryGetCharacterId(connection, out id) and TryGetCharacterIdBySteam64(steam64, out id) return the character ID (the game's player ID, the number wards use) and nothing else. They return false unless Characters.Mode = Enforce and the connection is currently admitted with a validated character, so "unknown" can never be mistaken for "verified". The character store and its revisions are not exposed.

Known limits

• Every player needs this mod. Without it a player cannot be shown the reason for a refusal and, on an enforcing server, cannot join.
• The mod check trusts the files a client reports. It is a guard against mistakes and casual tampering, not a defence against a determined cheater.
• Checked against Valheim 1.0.17 and BepInExPack 5.4.2350 and 5.4.2351. A Valheim update can change the game code this mod hooks; check the changelog before updating the game on a live server.
• Steam Cloud characters are supported by design but have had less real-world testing than local ones.

Support

When reporting a problem, include the Beastheim Server Mods lines of BepInEx/LogOutput.log (server or client). They are written not to contain character data or secrets.