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.
• AzuCraftyBoxes and Protective Wards are optional. When both are present, PraetorisClient prevents unpermitted players from using protected chest contents through AzuCraftyBoxes.

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.
• Lets a ship creator set, change, or clear a helm password with alternate use at the helm.
• Requires the password each time a player takes control of a protected ship. Passengers can still board the ship.
• Stores a salted password verifier in the ship ZDO. Destroying the ship removes the password with the ZDO.
• 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.

Surtling boat motor

• Lets the current ship driver press Left Shift to enable or disable an extra motor force.
• Consumes one Surtling Core from the ship inventory for five minutes of active motor use by default.
• Applies the motor force while rowing, reversing, or sailing. The force does not depend on wind direction.
• Shows the configured fuel item over the ship wind indicator. A red icon means that the motor is enabled but has no fuel.
• Synchronizes the enabled state and remaining fuel through the ship's network data.
• Requires PraetorisClient on the server and each client that can own ship physics.

Personal chest storage

• Expands the personal chest inventory to five columns and two rows.
• Gives personal chests the same 10 inventory slots as wooden chests.

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.

Ward count

Hover over a vanilla ward to see Your wards: current / limit. The count is for your current character in this world, including wards outside the loaded area. Removing a ward reduces the count. Creature Owner Wards and Network Wards do not count toward this limit.

The server supplies the count and limit. The display refreshes every two seconds while hovering and shows unavailable if no recent server response exists. Install this version on both the server and clients. Protective Wards hover instructions and status text remain visible above the count.

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.101

• Allow everyone to gather loose flint, branches, and stones inside Protective Wards. Other pickables and ward protections are unchanged.

0.1.100

• Append active alternate biome names to the biome label beside the small minimap. The local [Minimap] ShowAlternateBiomeName setting defaults to true.
• Align alternate biome labels to the top so wrapped lines extend down inside the minimap border. Preserve the normal label alignment when no alternate name is shown.

0.1.99

• Fix tombstone access in local games and for the host of a multiplayer game. Reset locally delivered message data before reading requests and access decisions.

0.1.98

• Move the Server Guide button below Repair and use the same button style, with a clearer book icon.

0.1.97

• Add Extra Shots for crossbows and Dundr: Mythic grants one extra shot before reloading, and Ancient grants two. The effect is not available at lower rarities.

0.1.96

• Queue Adrenaline Echo activations and release them one at a time, with a 0.35-second delay before each Echo.
• Allow adrenaline gained from an Echo to queue more Echoes when it fills the adrenaline bar.
• Before releasing a queued Echo, check that the player is alive and still has the same weapon and Echo trinket equipped.

0.1.95

• Replace the Blood Oath legendary set with a Unique shardstone, available from Epic through Ancient rarity through shard loot and upgrades.
• Socketing Blood Oath into equipped gear reduces current health to 1 and blocks natural health regeneration. Maximum health is unchanged; potions and life steal still heal normally.
• Removing the shardstone or unequipping its item restores natural regeneration. Activating it again reduces health to 1. Healed health is preserved across saves and rejoining while the effect remains active.
• Automatically mark your ordinary wards on both maps with a shield icon, including disabled and distant wards. Load existing pins on spawn and update them through placement and destruction events without periodic polling.
• Keep ward pins separate from saved manual pins and cartography-table sharing. Install matching versions on the server and clients.

0.1.94

• Add the Blood Oath legendary set: Vestments for chest armor and Leggings for leg armor.
• Equipping both pieces reduces current health to 1 and blocks natural health regeneration. Maximum health is unchanged; potions and life steal still heal normally.
• Removing either piece restores natural regeneration. Completing the set again reduces health to 1. Healed health is preserved across saves and rejoining while the set remains equipped.

0.1.93

• Make group access to tombstones a creator opt-in. The local [Tombstones] AllowGroupTombstoneAccess setting defaults to false and is not synchronized by the server.
• Check the creator's choice in the existing group confirmation RPC. The server must permit group access, and both players must be connected and in the same group. Changes apply on the next interaction.
• Keep creator access and the separate admin exception. Add no periodic network messages.
• Install matching versions on the server and all clients. Older creator clients do not check the new opt-in setting.

0.1.92

• Restrict tombstone access to the creator by default. Admins and confirmed members of the creator's Groups group can also access it. Each exception has a server setting.
• Check permissions when players open, take all, or stack items. The feature sends no periodic network messages.
• Install matching versions on the server and clients. Remove the old Expand World Prefabs tombstone restriction script before enabling these overrides.
• When using ValheimRcon with Groups, disable its solo chat relay and restart the server, or install the group membership fix from ValheimRcon PR #9.

0.1.91

• Add Molten Cores as preferred boat fuel when both core types are in storage. Show the active fuel icon.
• Molten fuel force values: reverse 2.0, rowing 1.02, half sail 1.4, full sail 2.0. Each core supplies 300 seconds of active motor use.
• Preserve the active fuel type when ship control changes or the world reloads. Keep existing Surtling fuel values.

0.1.90

• Add an optional server-controlled setting for free departures from one MWL shipping port. Travel to that port retains its normal gold cost. The feature is disabled by default.
• Add shippingport_free guid|set|clear|status administrator commands. Open the port panel and use shippingport_free set to select that port. The selection survives restarts and port name changes.
• Install matching versions on the server and clients to use this feature.

0.1.89

• Update the required Epic Loot version to 0.14.13 and Jotunn version to 2.30.2.

0.1.88

• Hide boss spawn announcements, including Eikthyr and the Elder. The server setting is enabled by default and locked against client overrides.
• Restrict player-built boat steering and storage to the builder and players who entered its password. Saved access survives password changes and restarts.
• Add an optional spawn island vanilla ward restriction. It defaults to disabled. Generate and review the boundary once per world before enabling it.
• Install matching versions on the server and clients.

0.1.87

• Enter a boat password once per character. Saved access covers both the helm and storage and remains until the boat is destroyed, including after password changes and server restarts.
• Save creator access when setting a boat password. Reject unauthorized storage requests.
• Remove the duplicate ship ownership patch and let NetworkPerformanceSystem handle helm ownership.
• Refresh Server Chest contents before withdrawals so deliveries received while the chest is open are not overwritten. Require a new selection if a delivery replaces a selected item.
• Install matching versions on the server and clients.
• Known NPS limitation: transferring ownership to the player steering can hide another player's open boat chest panel, including on boats without passwords. Release the helm and reopen storage; saved access is retained.

0.1.86

• Remove the Server Chest 64-slot limit and add scrolling rows as deliveries arrive.
• Preserve large chest saves beyond the game's row-coordinate limit.
• Refresh deliveries while the chest is open.
• Return clear send/status errors when chest contents cannot load, without overwriting stored data.
• Install matching versions on server and clients. Older versions cannot read saves above 2,048 stacks. Very large inventories still use more memory and take longer to render.

0.1.85

• Limit each player to one Server Chest per world, including unloaded areas.
• Register new Server Chests automatically for item delivery from server admins.
• Use the Dvergr treasure chest appearance. Build with 10 Wood near a Workbench.
• Disable inherited treasure loot, treasure-discovery statistics, and empty-chest destruction.

0.1.84

• Add Adrenaline Echo, a Unique trinket shardstone available at Epic, Legendary, Mythic, and Ancient tiers.
• When the trinket activates its full-adrenaline effect, trigger the equipped weapon's projectile area impact at the player's position. Staff of Embers creates an explosion around the player with its Epic Loot damage effects.
• Require a weapon whose own projectile has area damage. The effect costs no durability, stamina, health, or eitr.

0.1.82

• Save the builder's character name on newly built ships and carts so their owner labels work when the builder is offline or far away, including after a server restart.
• Keep the existing name lookup for ships and carts built before this update. Saved names reflect the character name at construction time.

0.1.81

• Limit each player to a configurable number of vanilla wards. The default limit is 5. Existing wards remain when the limit is reduced.
• Show your world-wide ward count and the server limit when you hover over a ward, while preserving Protective Wards hover text.
• Install this version on both the server and clients to use the ward count display.

0.1.80

• Recreate the Ancestral Slam prefab after logging out and joining a world again.
• Restrict Ancestral Slam triggers to hits with a supported combat skill.

0.1.79

• Remove the Withering Bomb from the live package. The feature remains in development on a separate feature branch.

0.1.78

• Restrict Effect Duration magic-effect rolls to supported status-effect staves, including the Staff of Protection, and to trinkets.
• Move the Server Guide icon away from the crafting-station level display and fix its crafting-window input handling.
• Hide Epic Loot's configuration-choice window on the main menu.
• Add the Withering Bomb, which prevents enemy health regeneration for a configurable duration. Craft three at a Black Forge with 1 Bilebag, 1 Sap, and 3 Resin.
• Update the required Jotunn version to 2.30.1.