Valheim Death Ban

Version 1.2.8

A configurable death-ban mod for Valheim. By default, a confirmed death causes an account ban and disconnection after a short delay. Bans use the game's native ban list, so creating another character on the same account does not bypass them.

Prefer death notifications without permadeath? Set BanOnDeath = false on the server. The death journal, chat announcements, banners and optional Discord notifications remain available.

Features

• Server-side death detection, including players whose models are not loaded on the server.
• Persistent account bans with a configurable delay and administrator immunity.
• A separate switch for death bans, enabled by default.
• Death journal with names, account IDs, timestamps and detailed reasons when available.
• Global chat announcements and queued red Norse-style banners.
• PvP messages with the killer and victim names.
• Optional Discord notifications with the result of the death-ban action.
• Optional Steam whitelist using a loaded ValheimEnforcer character database.
• Automatic reload of saved configuration changes and optional scan diagnostics.

Requires BepInEx 5. Jotunn and PvP Tweaks are not required. ValheimEnforcer is optional and only needed for its whitelist integration.

Installation

1. Install BepInExPack Valheim on the server.
2. Copy ValheimDeathBan.dll into BepInEx/plugins/ValheimDeathBan/.
3. Start the server once to create the configuration file.
4. For detailed client death reasons, chat announcements and banners, also install the mod on players' clients.

Use 1.2.8 on the server. Clients running 1.2.7 or 1.2.8 use the same protocol for reasons and announcements. Clients older than 1.2.7 cannot use these additional features with the new server; server-side detection and bans do not require the client mod.

The local-world host is always exempt from death bans. Host deaths are still recorded and announced while death processing is enabled.

Choose the action on death

Edit the server's configuration:

BepInEx/config/com.xtasy.ValheimDeathBan.cfg

The default behavior is:

[General]
Enabled = true
BanOnDeath = true

To record and announce deaths without death bans or disconnections:

[General]
Enabled = true
BanOnDeath = false

Enabled controls death processing as a whole. Keep it enabled to use the journal and notifications. BanOnDeath controls the ban/disconnect action separately.

Saved changes normally take effect within 1–2 seconds. Turning BanOnDeath off before a pending ban is applied cancels that action and stops further retry attempts. Turning it on later does not retroactively ban deaths processed with the setting off. Existing native bans are not removed.

Configuration

Default values:

[General]
Enabled = true
BanOnDeath = true
KickDelaySeconds = 3
BanAdmins = false
ScanIntervalSeconds = 0.25

[Announcements]
Chat = true
Banner = true
BannerSeconds = 8
BannerFontSize = 60

[Enforcer]
IntegrationEnabled = false
WhitelistEnabled = false
WhitelistExemptAdmins = true

[Discord]
Enabled = false
WebhookUrl =

[Diagnostics]
Enabled = true
LogIntervalMinutes = 15

Each installation reads its own configuration; settings are not synchronized. Configure bans, announcement switches, whitelist and Discord on the server. Banner duration and font size are configured on each client.

Automatic reload applies only to this mod's configuration. Read failures are logged and retried after 10 seconds. Changes to the whitelist affect subsequent connection attempts. The ban delay is captured when a death is detected; changing that delay affects subsequent deaths.

Administrators and bans

With BanAdmins = false, accounts recognized by the game's native administrator check are exempt. This includes the supported plain and platform-qualified Steam ID forms. Their deaths are still recorded and announced.

The captured account ID is added directly to the native ban list, without resolving it as a character name. Success is reported after checking the saved entries through the game's local/cloud storage reader.

Failed ban attempts are retried up to five times, with pauses of 2, 4, 8 and 16 seconds between attempts. Retries do not repeat the death journal entry or announcements. Final success or failure is written to the server log and sent to Discord when enabled.

Death bans share Valheim's standard bannedlist.txt with administrative bans. Use the game's normal ban management to remove them. Disabling death bans, disabling the mod or uninstalling it does not clear existing bans. Custom deathban list, deathban unban and deathban clear commands are not implemented.

Death messages and journal

Sentence templates are Russian. Creature names use Russian on Russian clients and English on other clients. Discord uses the server's selected language for creature names, falling back to English when no selected language is available. Character names are used without grammatical declension.

Creature names come from the game's localization tables. Missing translations use Неизвестное существо or Unknown creature. Translations injected only into another mod's global localization instance may not be available.

Chat announcements have no distance restriction. Banners are displayed near the top of the screen; up to 100 waiting messages are queued, with the oldest waiting message dropped on overflow. The game's message font is used if the Norse font asset is unavailable. If another mod also announces deaths, configure its notifications to avoid duplicates.

Death entries are appended in UTF-8 to:

BepInEx/config/ValheimDeathBan/deaths.txt

Entries contain the server-local timestamp and time-zone offset, character name, account ID, detailed reason, source and exemption flag. The journal records the death before the ban action; the enforcement result is reported separately in the server log and optional Discord notification. Host entries use id=local-host.

Discord

Create a webhook for a Discord text channel and configure it on the server:

[Discord]
Enabled = true
WebhookUrl = https://discord.com/api/webhooks/ID/TOKEN

Notifications contain the death message, account ID, detection time and action result: banned, exempt, bans disabled or an enforcement error.

The URL is not synchronized to clients. Keep it private and exclude it from shared configuration files and release packages. Mentions are disabled.

Delivery uses a bounded asynchronous queue, a 10-second request timeout and limited retries for rate limits. Discord failures do not prevent the journal or ban action. Ordinary network failures are not retried automatically, and queued notifications can be lost when the process stops.

Optional Enforcer Steam whitelist

Install ValheimEnforcer on the server, then enable both switches:

[Enforcer]
IntegrationEnabled = true
WhitelistEnabled = true
WhitelistExemptAdmins = true

The whitelist compares the connection's Steam account ID with Enforcer's character account registry. Plain and Steam_-prefixed IDs are normalized. Both YAML and internal storage modes are supported.

WhitelistExemptAdmins and BanAdmins are separate settings. The whitelist exemption does not bypass native bans, passwords or Enforcer's own rules. The local host does not go through the remote admission check.

To populate a new database, keep WhitelistEnabled = false while participants join and Enforcer saves their characters; enable it afterward. Rejected accounts cannot register through a rejected connection.

Rejected attempts are appended to:

BepInEx/config/ValheimDeathBan/whitelist_rejections.txt

The whitelist is independent of General.Enabled and General.BanOnDeath.

Diagnostics and limitations

Diagnostics are written to BepInEx/LogOutput.log every 15 minutes by default. They include scan counts, failures, tracked characters, ZDO lookups and scan timing. Disable Diagnostics.Enabled to stop measurements without stopping death detection.

The server checks synchronized character death state. A missing ZDO is not treated as a death. Previous character bindings are retained for up to 30 seconds to allow late synchronization after a character change or disconnection.

Client reports supply reasons only and cannot independently trigger a ban. Reports are tied to the actual connection and character ID; announcements are accepted only from a client's actual server connection. This mod is not an anti-cheat system: missing or delayed game synchronization can still prevent detection.

Damage-over-time deaths may lose the original attacker. A zero-second ban delay may leave insufficient time for a reason report. Without a compatible client report, remote deaths use an unknown reason. Host reasons are read locally.

Targets .NET Framework 4.7.2 and BepInEx 5. Compatibility with future game versions and other mod combinations must be checked separately.

Updating

Replace the DLL and restart the server/game to load the new code. Existing configuration values are preserved; new settings receive their defaults. BanOnDeath is added as true, so updating keeps death bans enabled unless you change it.

Clients 1.2.7 and 1.2.8 are compatible with the 1.2.8 server for reasons and announcements. Update older clients for those features.

Remove the standalone ValheimSteamWhitelist.dll when switching to the combined whitelist. Computer-name checks were removed in 1.2.5: old [MachineCheck] settings are ignored, and existing machines.txt files are not deleted or updated.

Краткая инструкция на русском

По умолчанию мод банит аккаунт после смерти. Для режима без бана измените конфиг сервера:

[General]
Enabled = true
BanOnDeath = false

Журнал, чат, баннер и включённые уведомления Discord продолжат работать. BanOnDeath = true возвращает бан после смерти; это значение установлено по умолчанию. Уже существующие баны не снимаются.

BanAdmins = false освобождает администраторов от death ban. Хозяин локального мира всегда освобождён. Настройка WhitelistExemptAdmins отдельно управляет исключением администраторов из белого списка Enforcer.

Серверу нужна версия 1.2.8; для причин смерти, чата и баннеров подходят клиенты 1.2.7 и 1.2.8. Изменения конфига обычно применяются за 1–2 секунды после сохранения. Для загрузки новой DLL требуется перезапуск.

Changelog

1.2.8

• Added General.BanOnDeath, enabled by default, to choose whether a confirmed death causes an account ban and disconnection.
• With BanOnDeath = false, retain the journal, chat, banners and enabled Discord notifications without a death-ban action.
• Cancel pending ban actions and stop further retries when the setting is disabled before the action is applied.
• Do not retroactively ban deaths processed with bans disabled. Existing native bans remain unchanged.
• Keep General.Enabled as the separate switch for death processing as a whole.
• Added regression coverage for the default, repeated deaths without bans and setting changes during pending actions.
• Kept the reason/announcement protocol compatible with clients 1.2.7 and 1.2.8.
• Reworked the README with current configuration defaults, installation steps and upgrade instructions.

1.2.7

• Fixed administrator immunity by using the game's native administrator check, including platform-qualified Steam IDs.
• Apply bans directly to the captured account ID; character-name collisions no longer redirect the ban to another account.
• Disconnect the actual matching account connection instead of resolving a player by name.
• Verify saved native ban-list entries through the game's local/cloud storage reader before reporting success.
• Retry failed bans up to five times, with pauses of 2, 4, 8 and 16 seconds, without repeating the journal or announcements.
• Limited General.ScanIntervalSeconds to 0.05–1 second to reduce deaths missed before normal respawn removes the old character state. Older larger values are clamped.
• Replaced routed messages with direct connection RPCs. Server-bound death reasons use the actual sender connection; clients accept announcements only from their actual server connection.
• Bound reasons to character ZDO IDs and rejected reports from other accounts or already closed death events.
• Cancel pending account jobs and unregister connection handlers when the server/world changes.
• Restore the cloned banner renderer's tint when showing a message.
• Updated DLL version metadata, configuration descriptions and isolated regression tests.
• Clients older than 1.2.7 need updating for reasons, chat and banners; server-side detection and bans continue to work without a client mod.

1.2.6

• Added Enforcer.WhitelistExemptAdmins (default true) for native adminlist accounts.
• Added automatic configuration-file reload on the main thread after saved changes settle.
• Disabled per-entry config saves during reload and added retries for file access failures.

1.2.5

• Removed computer-name reporting, machine-check RPCs, configuration entries and machine journaling.

1.2.4

• Removed hardcoded creature-name lists; Russian and English dictionaries now start empty and load from game localization tables.
• Retained unknown-creature messages and delayed retries when translations are unavailable.

1.2.3

• Added killer and victim names to PvP death announcements in chat, banners and Discord.
• Added a fallback message when the attacking player name is unavailable.

1.2.2

• Added the client-local Announcements.BannerFontSize setting (16–120, default 60).
• Preserved automatic font shrinking for long messages and scaled the banner area for larger fonts.

1.2.1

• Loaded both Russian and English creature names from game localization.
• Selected Russian names for Russian clients and English names for every other client language.
• Updated announcement RPCs; server and clients must be updated together.

1.2.0

• Added optional ValheimEnforcer integration with separate integration and whitelist switches.
• Added server-side admission checks against Enforcer’s character account database, supporting YAML and internal storage.
• Disabled whitelist checks when integration is disabled or Enforcer is not loaded.
• Rejected unknown accounts and database-check failures while the whitelist is active.
• Added a UTF-8 journal for rejected whitelist attempts.
• Added Russian creature-name loading from game localization tables with delayed retries.
• Loaded localization tables without invoking the Localization constructor, preserving the global translation handler.

1.1.13

• Fixes

1.1.12

• Updated README with current features, configuration options and installation instructions.
• No code changes.

1.1.11

• Added server-side Discord webhook notifications with death messages, account IDs, timestamps, and ban outcomes.
• Added notifications for exempt administrators and local-world hosts.
• Added asynchronous Discord delivery with a bounded queue, request timeout, and limited rate-limit retries.
• Added death announcements in chat using the PvP Tweaks rendering approach.
• Added large red death banners using the Valheim-Norsebold font.
• Added a banner queue for multiple deaths.
• Added shared Russian death messages for creature attacks, falling, drowning, trees, poison, freezing, and fire.
• Preserved detailed death reasons in the text journal.
• Added configurable player scan intervals through General.ScanIntervalSeconds, defaulting to 0.25 seconds.
• Added diagnostic logs with the last, average, and maximum scan times, player counts, ZDO checks, and scan failures.
• Added Diagnostics.Enabled, enabled by default, and Diagnostics.LogIntervalMinutes, defaulting to 15 minutes.
• Disabling diagnostics stops timing measurements and diagnostic logs without affecting death detection.
• Preserved server-side death detection, persistent bans, admin exemptions, and the configurable disconnect delay.
• Client installation is required for chat announcements, banners, and death-reason reporting. Server-side death detection and bans continue to work without the client mod.

1.1.4

• Switched death detection to the s_dead flag in the server’s copy of character ZDO data.
• Added checks every 0.25 seconds without requiring player models to be loaded on the server.
• Client reports now provide death reasons only and no longer trigger bans.
• Removed reliance on Player.RPC_OnDeath for death detection.
• Added protection against processing the same death more than once.
• Previous characters remain tracked for 30 seconds after character changes or disconnection to allow delayed synchronization.
• Preserved admin exemptions, death logging, and the configurable disconnect delay.
• Client installation is no longer required for death detection. The client mod is only needed to report the cause of death.

1.1.2

• Added direct death journaling for local-world hosts.
• Exempted the local-world host from bans.
• Avoided peer lookup warnings for local-host deaths.

1.1.1

• Fixed private GetServerPeerID access using reflection.

1.1.0

• Added a UTF-8 death journal with timestamps, names, account IDs, reasons and exemption status.
• Added optional client reporting of death reasons and attacker names.
• Changed the default BanAdmins value to false.
• Added the UnityEngine facade reference required for building.
• Captured account IDs at death to preserve them across disconnects during the delay.

1.0.0

• Initial development version with native persistent account bans, configurable kick delay and admin exemption setting.