Praetoris Client

A BepInEx client companion mod for Praetoris gameplay and account-linking features that should not live in DiscordTools.

Features

• In-game Discord link command:

  !link CODE
  

• Creative inventory bridge RPC for server-side mods that need a trusted client inventory count.
• Creative biome, terrain, vegetation, drop suppression, and skill suppression bridges for server-side creative zones.
• Siege portal client bridge RPC for server-side siege portal handling.
• Client-side RPC trace capture with HTTP upload to the ValheimTracer relay using short-lived server-issued tokens.

The moved RPC names intentionally keep their existing DiscordTools_* wire names so current server-side integrations can keep using the same requests.

Build

dotnet build PraetorisClient.csproj

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

Configuration

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

BepInEx/config/warpalicious.PraetorisClient.cfg

Clients do not need the bot URL or API key for local-only features. The Discord link server endpoint and key belong on the dedicated server if PraetorisClient handles link requests there.

Preferred dedicated-server setup:

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

Keep real endpoint and API key values in a local .env file or server environment. .env files are ignored by git; .env.example documents the required variable names without secrets.

Creative Inventory RPC

PraetorisClient registers a client-side request RPC:

DiscordTools_CreativeInventoryRequest

Request package:

int    protocolVersion = 1
string requestId
ZDOID  characterId
bool   includeItems

The client answers the sender with:

DiscordTools_CreativeInventoryResponse

Response package:

int    protocolVersion = 1
string requestId
ZDOID  characterId
bool   available
string error
long   playerId
string playerName
int    playerInventoryCount
bool   extraSlotsLoaded
bool   extraSlotsAvailable
int    extraSlotsCount
int    totalUniqueCount
int    itemEntryCount

Each item entry then writes:

string source
string prefabName
string sharedName
int    stack
int    quality
bool   equipped
int    gridX
int    gridY

totalUniqueCount is the value to enforce for empty-inventory checks. Item entries can include both player and extraSlots views of the same item for debugging. Shudnal ExtraSlots is read through its public ExtraSlots.API.GetAllExtraSlotsItems() method when the mod is loaded.

Creative Biome Override RPC

PraetorisClient registers a client-side biome override RPC:

DiscordTools_CreativeBiomeOverride

Request package:

int     protocolVersion = 1
int     zoneCount
string  zoneId
bool    enabled
Vector3 center
float   radius
int     biome
bool    suppressSpawns

The client applies enabled zones by overriding WorldGenerator.GetBiome, Heightmap.GetBiome, and biome color lookups inside the radius. Disabled zones are removed, and affected heightmaps plus clutter are refreshed. Client-side natural and event spawn points are blocked inside enabled creative biome override zones.

Link API

When a player enters !link CODE, the dedicated server posts JSON to LinkApiUrl:

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

The endpoint should return 2xx when the code is accepted. A plain-text response body is shown to the player in chat.

RPC Trace Upload

PraetorisClient can capture routed RPC trace rows locally and upload compressed JSONL batches to the ValheimTracer HTTP relay. The server issues short-lived upload tokens over small Valheim RPC messages. Bulk trace data is not sent through Valheim routed RPC. If HTTP upload fails, the client logs the failure and keeps the local trace file for a later retry.

Trace rows and upload token requests include Steam ID, platform user ID, trace player ID, and player name when available so server-side storage can group traces by player.

Server-synced config controls whether tracing is enabled and whether HTTP upload is preferred.

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.