Please disclose if any significant portion of your mod was created using AI tools by adding the 'AI Generated' category. Failing to do so may result in the mod being removed from Thunderstore.
DwarvenDefender
Simple and effective mod enforcement for Valheim servers. Players must have every Whitelist mod, may have Greylist mods, and anything else is refused or kicked with the exact reason. Lists hot-reload, no restart.
CHANGELOG
Changelog
0.1.0
First release. A server-enforced mod-list check for Valheim 1.0.21 (network version 41). Runs on the dedicated server and on every client.
Added
- Whitelist and Greylist folders under
BepInEx/config/DwarvenDefender/([1 - General]List folder): every DLL inWhitelist/is required, a DLL inGreylist/is allowed, any other DLL refuses the player. One folder per package (<Owner>-<Name>-<version>/). - Content matching. Files are compared by SHA-256 of their bytes, never by name or folder. A list file is only hashed, never loaded, so native DLLs and patchers can sit on a list without breaking it.
- What a client reports. Every
*.dllunder the client'sBepInEx/plugins/andBepInEx/patchers/(any depth), plus any loaded plugin outside them. Gale's disabled*.dll.oldfiles do not count; BepInExcore/is not checked. The report is sent inZNet.OnNewConnection, beforePeerInfo, on the same ordered channel. - The join check, a
Priority.Firstprefix onZNet.RPC_PeerInfoon the server. Refusal is vanilla's: the reason goes to the client, thenError(ErrorVersion), and the connection is dropped after 3 s if the client keeps it open. A client without DwarvenDefender gets vanilla's "Incompatible version". A crash inside the check refuses the player instead of letting them in. - The reason on the player's screen: the connect-error (or kicked) dialog lists the missing Whitelist entries and the DLLs to remove, 12 of each at most.
- Hot reload. The lists are polled every 2 s (
Poll seconds), and a file watcher wakes the check early. A change applies once the folders have been unchanged for 3 s (Settle seconds), and only if they are still unchanged after hashing, so a half-copied DLL is never used. A list folder that disappears is refused (empty it to clear a list). A read error keeps the old lists, warns once and retries every 30 s.dd_reloadforces a rescan. - Kick on list change (
[2 - Hot reload]Kick on list change, on). After a change, connected players who no longer match are re-checked afterKick grace seconds(30) against the lists as they are then, and kicked with vanilla's kick and the reason. A change made in steps does not kick anyone by accident. New joins use the new lists at once. - Admins exempt (
Exempt admins, on):adminlist.txtplayers join with any mods, and are not kicked on a reload. - Check patchers (on): patcher DLLs must be listed too. Off = patchers are reported and logged, never refused.
- Dedicated servers only by default. A game hosted from the main menu enforces nothing unless
Enforce when hostingis on. - DwarvenDefender's own DLL is allowed automatically by the server's own copy's hash. The build is deterministic, so the same source gives the same file. Clients must run the server's build; put another build on the Greylist to accept it too.
- Logs.
rejections.log(one line per refusal or kick, rotated to.1at 5 MB) andreports/<id>.txt(each player's last report, every DLL markedWHITE/GREY/SELF/NONEwith its hash and path;Save reports, on). - Admin console commands, run on the server from an admin's in-game console:
dd_status(the lists and every connected player's state) anddd_reload. Enabled(on): off = log what would be refused and refuse nobody.
Safety
- Each connection is judged once; a client that sends
PeerInfoagain after a refusal is dropped at once, with no further logging. The report is capped at 4096 files; client-supplied paths and names are clipped and stripped of control characters and rich-text brackets before they reach a log or an admin's console. - Linux clients: paths are compared case-sensitively when building the report, so two folders differing only in case are both reported.
Tested
- 36 unit tests on the list loader, watcher, report format and verifier.
- A headless dedicated server (1.0.21, build 26266951) with hot reload exercised live: adding an entry, a slow copy (applied once, after it finished), deleting the Whitelist folder (refused) and restoring it.
- The real 1.0.21 client against that server, driven unattended: compliant join, Greylist mod, Gale
.oldfile, missing Whitelist mod, extra plugin, extra patcher, no DwarvenDefender, and a kick after a list change. All 8 pass.
Known limits
- The client reports its own files: a client deliberately modified to send another pack's hashes can pass. This is a mod-list enforcer, not anti-cheat.
- A same-size replacement that keeps the old file's modified time is not noticed until
dd_reload.