PraetorisClient

PraetorisClient is the shared client-and-server mod for Praetoris-specific gameplay, creative-zone, administration, and network measurement features.

Requirements and integrations

• BepInEx is required.
• Jotunn is required.
• Epic Loot is required by the current build. PraetorisClient starts its Epic Loot extensions during plugin startup.
• ValheimRcon is optional. When present on the server, it receives the Server Chest commands.
• Shudnal ExtraSlots is optional. When present on a client, its items are included in creative inventory reports.
• VBNetTweaks is optional. When present, its ZDOQueueLimit supplies the socket metric queue budget.
• ValheimTracer is optional. A compatible server can issue tokens and receive uploaded network metric batches.

Features

Player features

Discord account linking

• Enter !link CODE in game chat to link a Valheim character to Discord.
• The server sends the code and player identity to the configured Praetoris bot endpoint.
• The result appears in game chat.
• The command name is configurable.

Cleanse Mead

• Adds Mead Base: Cleanse to the Mead Ketill.
• The recipe requires 6 Pukeberries, 1 Fresh Seaweed, and 1 Fragrant Bundle.
• One mead base ferments into six Cleanse Mead.
• Drinking it removes every other active status effect once. This includes beneficial and harmful effects.
• The mead leaves its own 120-second cooldown effect.

Server Chest

• Adds a buildable Server Chest for administrator deliveries.
• Alternate interact registers the chest to the player's current character.
• Each player can register only one Server Chest.
• Each registered chest can belong to only one player.
• Administrators can deliver items while the player is offline.
• Players can remove delivered items, but they cannot place items into the chest.
• The chest supports up to 64 item slots and saves its contents in the world.
• See the Server Chest command guide for delivery and lookup commands.

Creature Owner Ward

• Adds a Hammer > Misc piece made with 10 Core Wood.
• The piece assigns network ownership of nearby hostile creatures and bosses to a selected connected player.
• It does not tame creatures and does not provide normal ward protection.
• It excludes players, tamed creatures, and creatures in player-controlled factions.
• Use toggles the ward. Alternate use opens the owner-name input.
• Any connected player can use these ward controls. They are not limited to the piece creator or an administrator.
• Its hover text shows its state, selected owner, and radius.
• The default radius is 40 metres. The default update interval is 2 seconds.

World and display changes

• Prevents building in selected Hildir locations, crypts, caves, and Mistlands Dvergr entrances.
• Prevents the specific attackerless water-impact damage applied to boats. Other boat damage still applies.
• Hides area damage numbers on building pieces and non-player damage numbers on trees and logs.
• Preserves player combat damage numbers. This display option does not change damage.

Epic Loot additions

PraetorisClient adds seven Epic Loot magic effects:

• Ancestral Slam: High-rarity two-handed clubs summon an ancestral copy that repeats the player's attack near the target.
• Glancing Blows: Increases block power by 50%, but applies additional health damage after a block or parry. Armor can reduce this additional damage, but resistances cannot.
• Retaliation: Successful blocks add stacks. A later melee attack consumes a stack and increases the speed of that attack string. Higher rarities support more stacks.
• Infusion: An activated melee-weapon ability that converts recognized fire, frost, lightning, poison, or wind effects into temporary elemental damage or attack-speed bonuses. Its cooldown is 120 seconds.
• Whirlwind: High-rarity two-handed polearms gain a rapid secondary spin attack with reduced stamina cost and adjusted damage and stagger values.
• Onslaught: Club combo finishers and attacks against staggered enemies start a sequence of repeated final-combo attacks with increasing damage.
• Perfect Strike: Two-handed axes gain a timing window that starts the next combo attack and increases its damage when the player attacks at the correct time.

The mod also changes Epic Loot rune behavior:

• Extracted runes keep the effect value from the source item and round it to two decimal places.
• Etching a rune that is at least 10% stronger than the normal maximum can destroy both the rune and target item.
• The destruction chance ranges from 10% to 90% based on the rune's strength.
• The enchanting interface shows a red warning and requires a second confirmation.
• Epic Loot treasure-map chests ignore ward access checks. Ordinary chests are unchanged.

Creative-zone integration

PraetorisClient supplies the client-side parts required by the Praetoris creative server systems:

• Reports normal inventory and Shudnal ExtraSlots counts to the server.
• Can include item name, stack, quality, equipped state, source inventory, and grid position.
• Can restrict selected console commands to the player's assigned creative zone.
• Prevents skill gains while the player is inside the active creative zone.

These features receive their state from server remote procedure call (RPC) messages. They do not have local creative-zone configuration entries.

Siege portal integration

• Detects portals marked with a siege ID in their network data or with a siege:<id> portal tag.
• Stops normal portal travel and sends the character and siege ID to the server.
• Shows the selected siege ID to the player.
• Requires a compatible server-side siege system to perform the actual entry or teleport.
• Includes two development commands for marking and testing nearby siege portals.

Network measurement and stability

Frame-time monitoring

• Writes local frame-rate and frame-time summaries every 30 seconds by default.
• Records average frames per second, average frame time, percentiles, maximum frame time, and long-frame counts.
• Can write a second CSV with each frame that exceeds the configured long-frame threshold.
• These CSV files remain local and are not included in network metric uploads.

Socket and ZDO transport metrics

• Samples socket state every 5 seconds by default.
• Measures ping, connection quality, send queues, queue headroom, byte rates, ZDO package rates, send timing, and socket pressure.
• Records aggregate ZDO transport values. It does not record ZDO contents, prefab data, individual ZDO fields, or receive/apply events.

Active RPC probes

• Sends a small synthetic probe every 2 seconds by default.
• Measures client-to-server and relayed client round-trip time.
• Records timeouts, server relay time, target peer, payload size, and send-queue state.

Metric storage and upload

• Writes pending socket and RPC probe metrics as compressed JSON Lines files.
• Can upload the files to a compatible ValheimTracer HTTP endpoint during an active server connection.
• Uses a durable, server-issued upload token.
• Deletes a pending file only after its final batch succeeds.
• Keeps failed files for a later retry.
• Supports legacy uncompressed .jsonl pending files.

ServerSync protection

• Blocks clients from sending peer-to-peer ServerSync configuration broadcasts.
• The server controls this setting. It is enabled by default.

Commands

Player chat

!link CODE

Administrator console

ownerward_set_nearest <ownerName> [radius]
ownerward_enable_nearest [true|false] [radius]
ownerward_status_nearest [radius]

serverchest_send <characterName> <itemPrefab> <amount> [quality]
serverchest_send_bulk <characterName> <itemPrefab>:<amount>[:quality] ...
serverchest_status <characterName>
serverchest_find [characterName]

The four Server Chest commands are also registered with ValheimRcon when it is installed on the server.

Siege development commands

dt_mark_siege_portal <siegeId> [radius]
dt_enter_nearest_siege_portal [radius]

These two commands are development tools and are not currently restricted to administrators.

Configuration

The plugin GUID is warpalicious.PraetorisClient. Configure the generated file:

BepInEx/config/warpalicious.PraetorisClient.cfg

PraetorisClient watches this file and reloads changes after approximately one second. Jotunn synchronizes selected server-controlled settings to connected clients.

Important settings include:

Dedicated-server account-link configuration

Clients do not need the bot URL or API key. Set these values only on a server that handles link requests:

export PRAETORISCLIENT_LINK_API_URL="https://your-bot-host.example.com/api/valheim-link"
export PRAETORISCLIENT_BOT_API_KEY="shared-secret"

These environment variables override BotApi.LinkApiUrl and BotApi.ApiKey. PraetorisClient does not load .env files itself. The service that starts the server must export the variables.

Data written by diagnostics

Frame metrics are stored under:

BepInEx/logs/PraetorisClient/FrameMetrics

Pending network metrics and the upload-token cache are stored under:

BepInEx/logs/PraetorisClient/NetworkMetrics

Network metric rows can include the player name, Steam or platform identifiers, peer identifier, world name, world identifier, Valheim version, and installed plugin information. Frame metric rows can include the world name and exact player position.

Integration protocols

Some migrated RPC messages intentionally keep their existing DiscordTools_* names so current server integrations can continue to use them. Newer features use PraetorisClient_* names.

Creative inventory request

Request RPC:

DiscordTools_CreativeInventoryRequest

Response RPC:

DiscordTools_CreativeInventoryResponse

The protocol reports the player identity, normal inventory count, ExtraSlots availability and count, and a duplicate-free combined item count. The server can request detailed item entries when required.

Discord link API

When a player enters !link CODE, the server posts JSON to the configured link endpoint:

{
  "requestId": "6b7b8d9c0f2a4d7ca5f8c37e87b6fd13",
  "code": "PRAE-482913",
  "playerId": "76561198000000000",
  "playerName": "Player",
  "endpoint": "76561198000000000",
  "platformDisplayName": "SteamName",
  "receivedAtUtc": "2026-05-28T18:42:00.0000000Z"
}

The endpoint must return a successful HTTP status when it accepts the code. PraetorisClient shows the plain-text response body to the player. playerId is the server's stable peer identifier and is not guaranteed to be a Steam ID.

Build

Use Valheim 1.0 game assemblies and regenerate their publicized assemblies before building. Older assemblies can produce a DLL that compiles but fails during console-command registration on Valheim 1.0.

dotnet build PraetorisClient.csproj

The built DLL is written to bin/Debug/PraetorisClient.dll.

To build against assemblies copied from a test client, override both paths:

dotnet build PraetorisClient.csproj -c Release \
  -p:VALHEIM_MANAGED=/path/to/Managed \
  -p:PUBLICIZED_PATH=/path/to/Managed/publicized_assemblies

Additional documentation

• Server Chest command guide

0.1.65

• Update custom magic effects and the embedded API integration for Epic Loot 0.14.0.
• Add Ancient-rarity support and adjust Onslaught values and effect selection weights.
• Update ancestral clone construction and attack animation handling.
• Disable custom rune extraction and etching patches; these operations now use Epic Loot behavior, including its extraction cap and no custom destruction chance.
• Declare the JsonDotNET runtime dependency.

0.1.64

• Fix ancestral clone material bounds and restore the player prefab after cloning.

0.1.63

• Updates bundled build references to Epic Loot 0.14.0 and removes the obsolete EpicLoot-UnityLib reference.
• Fixes the rune UI startup error and uses Epic Loot's current rune-enhancement method.

0.1.62

• Fixes rune extraction with Epic Loot 0.14.0 on Valheim 1.0.
• Preserves enhanced rune values and two-decimal rounding.
• Guards missing magic data and invalid effect indices during extraction.

0.1.61

• Updates game API calls for Valheim 1.0.
• Removes the retired creative biome feature.
• Skips optional Epic Loot integration when Epic Loot is absent.
• Fixes ServerChest registration input, delivery, saved inventory, and empty slot display.

0.1.60

• Prevents building inside Hildir dungeons, crypts, troll caves, and the selected Mistlands Dvergr town entrances.
• Applies the no-build flag once when each protected location loads, with a one-time startup pass for locations that were already loaded.
• Leaves Valheim's normal no-build position and radius checks unchanged.

0.1.59

• Fixes Epic Loot treasure-map chests so players can open their chest when it is inside another player's ward radius.
• Keeps Epic Loot's private chest ownership behavior unchanged.
• Updates the Thunderstore Jotunn dependency to 2.29.2.

0.1.58

• Fixes the Cleanse Mead base tooltip so it shows the cleanse status effect text instead of the lingering healing mead text.
• Aligns the Cleanse Mead base with vanilla mead base setup by using the same status effect reference as the finished mead while keeping the base item as a material.

0.1.57

• Adds Cleanse Mead, a fermentable mead that clears active status effects and applies a 120 second cleanse cooldown.
• Adds the Cleanse Mead base recipe at the Mead Ketill using 6 Pukeberries, 1 Fresh Seaweed, and 1 Fragrant Bundle.
• Changes Creature Owner Ward construction to require 10 Core wood.

0.1.55

• Fixes the Retaliation Epic Loot magic effect so sword special attacks no longer leave the player's attack speed slowed afterward.
• Records the Retaliation attack animation when the attack starts, before Valheim consumes the attack trigger.
• Restores the animator's prior speed when Retaliation ends instead of forcing it to 1.0.

0.1.54

• Adds ServerSyncProtection.BlockPeerServerSyncConfigSync, enabled by default, to stop Praetoris clients from publishing ServerSync config packets to other clients.
• Blocks outgoing ServerSync config RPCs generically for methods ending in ConfigSync, covering ServerSync-based mods without targeting a single mod.
• Preserves server-to-client config sync so dedicated servers can still control client configuration normally.

0.1.53

• Fixes normal wood chests after ServerChest use so vanilla chests keep their compact CHEST inventory panel instead of inheriting the ServerChest layout.
• Restores the vanilla wood chest prefab/container shape after registering the custom ServerChest prefab.
• Clears ServerChest inventory ownership tracking when a vanilla chest inventory is restored.

0.1.52

• Restores RPC probe and socket metric HTTP uploads after the client-side trace upload cleanup.
• Sends RPC probe and socket metric rows through the ValheimTracer upload-token path without restoring high-volume RPC/ZDO trace capture.
• Keeps local trace persistence and quit/menu trace flush work removed from the client.

0.1.51

• Fixes ServerChest inventory grid cleanup so opening a ServerChest no longer leaves normal chest inventories visually hidden.
• Restores the shared container grid once after ServerChest compaction instead of doing redundant restore work every frame on normal chests.
• Keeps ServerChest grid compaction scoped to the currently open ServerChest container without raycasts or container caches.

0.1.50

• Keeps RPC probe and socket metrics telemetry for network diagnosis.
• Removes high-volume RPC/ZDO trace capture, local trace persistence, HTTP upload, upload token handling, and quit/menu flush work from the client.
• Keeps the telemetry config surface focused on RpcProbe and SocketMetrics so production clients do less background tracing work.

0.1.49

• Fixes Infusion magic effects so mutually exclusive infusion rolls do not stack incorrectly.
• Fixes PerfectStrike so its damage multiplier uses the magic effect value instead of a hardcoded 200% value.
• Caps Wind Infusion values for legacy gear.
• Removes noisy Leslie magic-effect debug logging.

0.1.48

• Adds ServerChest, a player-registered delivery chest for admin item recovery workflows.
• Adds serverchest_send, serverchest_send_bulk, serverchest_status, and serverchest_find admin commands, including ValheimRcon command registration when ValheimRcon is installed.
• Dynamically expands ServerChest delivery slots for multi-stack item sends and removes empty delivery slots after players claim items.
• Adds ServerChest debug logging and guards client command RPC routing when routed RPC is unavailable.

0.1.47

• Adds new Epic Loot magic effects from Leslie's magic effects branch.
• Adds EpicLootAPI integration into the packaged client DLL for the new magic effect registration path.

0.1.46

• Removes the retired ValheimEvents client telemetry capture and server RPC upload path.
• Keeps ValheimTracer RPC, ZDO, socket metric, and probe telemetry unchanged.

0.1.45

• Fixes Creature Owner Ward placement so nearby players, monsters, and inherited guard-stone helper objects do not incorrectly block valid placement.

0.1.44

• Keeps ValheimTracer HTTP upload tokens durable across game restarts so saved local trace files can upload on a later client launch.
• Removes the cached token expiration check that could prevent delayed trace uploads after the client had been closed for more than the old token lifetime.
• Adds targeted RPC trace upload token request logging for diagnosing missing server token responses.

0.1.43

• Resolves the socket metrics send queue budget from SocketMetrics.SendQueueBudgetBytes, then VBNetTweaks ZDOQueueLimit, then Valheim's vanilla 10240 byte budget.
• Reports socket skip and headroom metrics against the active send queue budget, including VBNetTweaks servers using a 20480 byte queue limit.

0.1.42

• Adds the Creature Owner Ward, a buildable player-configurable ward that can assign nearby monster ZDO ownership to a configured connected player.
• Adds admin console commands for setting, enabling, and inspecting the nearest Creature Owner Ward.
• Adds configurable CreatureOwnerWard.Radius, update interval, and debug logging settings.
• Hardens Creature Owner Ward RPC authorization and runs ownership updates only from the server-side ward tick.

0.1.41

• Separates the four Valheim trace telemetry controls so RPC tracing, ZDO tracing, RPC probes, and socket metrics each use their own feature gate.
• Keeps RPC probes, socket metrics, ZDO trace rows, runtime metadata, clock sync, and HTTP upload support active when their own gates are enabled, even when high-volume RPC tracing is disabled.
• Makes RpcTrace.Enabled, ZdoTrace.Enabled, RpcProbe.Enabled, and SocketMetrics.Enabled server-synced so the server can control connected clients.
• Keeps Measurement.DisableRpcAndZdoTrace as a local client kill switch for trace, probe, socket capture, and upload.

0.1.38

• Adds Ships.DisableBoatWaterImpactDamage, enabled by default, to prevent boats from losing health to Valheim water-impact damage.
• Keeps direct boat damage from weapons, enemies, Ashlands ocean damage, upside-down damage, and other non-water impact sources working normally.

0.1.37

• Adds client socket metric samples to the existing ValheimTracer trace upload stream.
• Adds active client RPC probe participation for client-to-server-to-client latency measurement.
• Rotates local trace gzip files during active gameplay so metric and probe rows become uploadable without waiting for shutdown.
• Fixes HTTP trace upload response handling so uploads complete after reading Content-Length instead of waiting for connection close.

0.1.36

• Stores pending RPC/ZDO trace files locally as .jsonl.gz instead of raw .jsonl to greatly reduce disk usage.
• Keeps upload support for existing legacy .jsonl pending files.
• Streams pending trace files sequentially during HTTP upload instead of repeatedly reopening and skipping through large files.
• Allows uploaded trace files to be deleted while the reader is still open on Windows, preventing duplicate re-uploads after successful upload.

0.1.35

• Replaces broad damage text suppression with targeted low-value environment suppression.
• Suppresses damage text for AoE hits against build pieces and non-player vegetation damage while preserving character combat damage numbers.
• Adds Network.SuppressEnvironmentDamageText, enabled by default, for the new narrower suppression behavior.

0.1.34

• Uploads persisted client RPC/ZDO trace files on the next game launch using a cached HTTP upload token instead of relying on upload during application quit.
• Keeps startup/menu uploads running through server join loading, then defers upload once the player is active in-world.
• Fixes trace worker completion signaling so a late worker callback does not throw if the waiting flush caller already timed out.

0.1.33

• Adds a local-only damage text mode that displays vanilla damage numbers on the client that generated them without broadcasting RPC_DamageText to other peers.
• Adds Network.LocalDamageTextOnly, enabled by default, so vanilla damage text routing can be restored if needed.
• Defers HTTP RPC/ZDO trace upload while the client is actively in-world so gameplay capture does not perform upload work on the main thread.
• Moves trace file writing and outbound ZDO package parsing to background workers while still uploading full RPC and ZDO trace data.
• Adds frame metrics and local measurement toggles for validating trace capture and upload impact.

0.1.31

• Moves HTTP trace uploads off the main game thread to reduce gameplay stutter during trace delivery.
• Reduces RPC trace upload batch size after timeouts so clients recover without repeatedly sending oversized uploads.
• Lowers frame impact from queued trace uploads while keeping local trace files retryable.

0.1.22

• Adds exponential backoff for failed HTTP RPC trace uploads so a short relay or Nexus outage does not retry every frame.

0.1.21

• Enables ZDO tracing by default.
• Sets ZDO revision sampling to capture all revisions by default.
• Removes the default per-second ZDO trace event cap.

0.1.20

• Adds client-side ZDO data tracing for ZDOData package send/receive and per-ZDO revision receive/apply/skip events.
• Adds ZDO tracing filters, sample rate, and per-second caps so production tracing can be scoped without rebuilding the client.
• Emits ZDO trace rows through the existing ValheimTracer HTTP upload path.

0.1.19

• Sends HTTP RPC trace uploads as gzip files with Content-Type: application/gzip instead of marking the request with Content-Encoding: gzip.
• Keeps queued trace files retryable when the relay reports failed to read request body.
• Fixes large queued client trace batches that were rejected by the HTTP relay before Nexus could ingest them.

0.1.18

• Adds RPC trace runtime metadata with game version, PraetorisClient version, and loaded plugin catalog.
• Sends a stable trace runtime ID with each HTTP upload batch so Nexus can link later batches to the same client runtime.
• Emits observed RPC method names and source metadata to improve method-hash cataloging.

0.1.17

• Adds client support for creative zone world terrain, vegetation refreshes, and biome terrain source updates.
• Suppresses creative-zone vegetation drops and skill gain when the server marks the player inside a creative zone.
• Keeps client-side creative state aligned with the server-side terrain and command systems used by valheimCreative 0.2.34.

0.1.9

• Includes Steam ID, platform user ID, trace player ID, and player name in RPC trace HTTP upload token requests and trace rows.
• Keeps trace uploads keyed to a stable player identity for DuckDB latency and player analysis.

0.1.8

• Stops repeated HTTP RPC trace upload retries when the receiver reports a configuration or authorization failure.
• Clears stale upload tokens and pauses token requests after receiver rejection while keeping local trace files for later retry.

0.1.7

• Uploads RPC trace files over the ValheimTracer HTTP relay instead of sending bulk trace data through Valheim routed RPC.
• Removes the old routed-RPC trace batch fallback; failed HTTP uploads are logged and local trace files are kept for retry.
• Uses server-issued short-lived upload tokens from ValheimTracer for trace upload authorization.

0.1.6

• Limits RPC trace upload batches so large pending trace files are split into safe routed RPC payloads during logout.
• Uses the configured RPC trace max rows per batch when flushing pending trace files.
• Samples creative biome terrain color from the original world source while applying client-side creative biome overrides.

0.1.5

• Added client-side RPC trace capture for routed RPC send, receive, and handle events.
• Stores trace rows locally and uploads batches on logout or menu quit after server acknowledgement.
• Adds server-synced tracing config so tracing can be disabled without rebuilding the client.

0.1.4

• Added client-side blocking for server-protected creative commands outside the player's active creative zone.
• Receives the protected command policy from valheimCreative so command-prefix ownership stays on the server.
• Removed local PraetorisClient protected-command configuration.

0.1.3

• Added client-side ValheimEvents combat, death, and minimap exploration telemetry.
• Added Jotunn-synced configuration for ValheimEvents telemetry toggles.
• Keeps Discord link, creative inventory, creative biome override, and siege portal client bridge behavior moved out of DiscordTools.