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.

Installation	Available features
Server only	Death detection, configured account bans, journal, diagnostics, Discord with available reasons, and the optional whitelist.
Server and clients	Adds client death-reason reports, chat announcements and banners.

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

Setting	Default	Description
General.Enabled	true	Enable server death detection and event processing.
General.BanOnDeath	true	Ban and disconnect after death. When false, retain the journal and enabled notifications.
General.KickDelaySeconds	3	Delay in seconds from server detection to the ban/disconnect action. Negative values use zero.
General.BanAdmins	false	When false, native adminlist.txt accounts are exempt from death bans.
General.ScanIntervalSeconds	0.25	Seconds between scans; range 0.05–1. Older larger values are limited to 1 second.
Announcements.Chat	true	Server sends shout-style death messages to compatible clients.
Announcements.Banner	true	Server sends red death banners to compatible clients.
Announcements.BannerSeconds	8	Client-local banner duration, limited to 1–60 seconds.
Announcements.BannerFontSize	60	Client-local maximum font size; range 16–120. Long messages can shrink to half that size.
Enforcer.IntegrationEnabled	false	Enable integration with a loaded ValheimEnforcer plugin.
Enforcer.WhitelistEnabled	false	Require Steam accounts to exist in Enforcer's database; needs integration and a loaded Enforcer.
Enforcer.WhitelistExemptAdmins	true	Exempt native administrator accounts from this mod's whitelist.
Discord.Enabled	false	Enable server-side Discord death notifications.
Discord.WebhookUrl	Empty	Discord webhook URL. An empty value disables delivery.
Diagnostics.Enabled	true	Measure server death scans and periodically log diagnostics.
Diagnostics.LogIntervalMinutes	15	Minutes between diagnostic reports; range 0.1–1440.

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.

Cause	Example
Creature attack, Russian client	Древний убивает Дэнчик
Creature attack, other client language	The Elder убивает Дэнчик
Player attack	Игрок Вася убил игрока Дэнчик
Falling	Дэнчик разбился
Falling tree	Дерево придавило Дэнчик
Drowning	Дэнчик утонул
Poison	Дэнчик отравился
Freezing	Дэнчик замёрз
Fire	Дэнчик сгорел
Unknown or other cause	Дэнчик усоп

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.

State	Result
Integration or whitelist disabled	No check from this mod.
Enforcer not loaded	Whitelist inactive; a warning is logged.
Account exists in the database	Continue the normal admission checks.
Account absent or database empty	Reject, except exempt administrators.
Enforcer API/database check fails	Reject, except exempt administrators.
Non-Steam account	Reject under an active check, except exempt administrators.

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 требуется перезапуск.