用于 Discord 关联、创意服务器桥接、RPC 追踪、套接字指标和 RPC 探测的客户端 Praetoris 工具。

普雷托里斯客户端

PraetorisClient 是共享的客户端与服务端模组，用于实现 Praetoris 专属玩法、创造区、管理以及网络测量功能。

需求与集成

• BepInEx 是必需的。
• 约顿 是必需的。
• 当前版本需要Epic Loot。PraetorisClient在插件启动期间启动其Epic Loot扩展。
• ValheimRcon 是可选的。当服务器上存在该模组时，它会接收服务器宝箱指令。
• Shudnal ExtraSlots 是可选的。当客户端安装该模组时，其物品会被包含在创造模式物品栏报告中。
• VBNetTweaks是可选的。存在时，其 队列上限 提供套接字指标队列预算。
• ValheimTracer 为可选功能。兼容的服务器可以发放令牌并接收上传的网络指标批次。
• AzuCraftyBoxes 和 Protective Wards 是可选模组。当两者同时存在时，PraetorisClient 会阻止未经许可的玩家通过 AzuCraftyBoxes 使用受保护容器的内容。

功能

玩家功能

关联Discord账号

• 进入 !link CODE 在游戏内聊天中输入，将英灵神殿角色关联到Discord。
• 服务器将代码和玩家身份发送到已配置的Praetoris机器人端点。
• 结果显示在游戏聊天中。
• 命令名称可配置。

净化蜂蜜酒

• 添加 蜂蜜酒基底：净化 给蜜酒锅。
• 这个配方需要6个呕吐浆果、1份新鲜海藻和1个芳香捆包。
• 一份蜂蜜酒基发酵成六份净化蜂蜜酒。
• 饮用后立刻移除所有其他生效中的状态效果一次，包括增益和减益效果。
• 蜂蜜酒会留下120秒的冷却效果。

服务器宝箱

• 添加一个可建造的服务器宝箱，用于管理员发放物品。
• 备用交互将箱子标记为当前角色的归属。
• 每位玩家只能注册一个服务器宝箱。
• 每个已登记的宝箱只能属于一名玩家。
• 管理员可以在玩家离线时发放物品。
• 玩家可以取出已交付的物品，但无法将物品放入箱子中。
• 箱子最多支持64个物品槽位，并会在世界中保存其内容。
• 查看 服务器宝箱指令指南 用于递送和查找命令。

生物所有者结界

• 添加一把用10个核心木材制成的锤子 > 杂项部件。
• 该物品将附近敌对生物和首领的网络所有权分配给选定的已连接玩家。
• 它不会驯服生物，也不会提供正常的守护保护。
• 它不包括玩家、已驯服的生物以及玩家控制阵营中的生物。
• 用于切换结界。再次使用可打开所有者名称输入。
• 任何已连接的玩家都可以使用这些守卫控制。它们不限于棋子创建者或管理员。
• 其悬停文本显示其状态、选中的拥有者和半径。
• 默认半径为40米。默认更新间隔为2秒。

世界与显示变化

• 阻止在选定的希尔德地点、墓穴、洞穴和迷雾之地矮人入口处进行建造。
• 防止对船只施加无攻击者的特定水面撞击伤害。其他船只伤害仍然生效。
• 让飞船创建者在舵轮处设置、更改或清除舵轮密码，并可在舵轮处备用。
• 每次玩家控制受保护的飞船时都需要密码。乘客仍然可以登船。
• 在飞船的ZDO中存储加盐密码验证器。摧毁飞船会随ZDO一起移除密码。
• 隐藏建筑部件上的范围伤害数字，以及树木和原木上的非玩家伤害数字。
• 保留玩家战斗伤害数字。此显示选项不会改变伤害。

焦炭船马达

• 让当前飞船驾驶员按左Shift键启用或禁用额外马达推力。
• 默认消耗船库存中的一个焰灵核心，为引擎提供五分钟的动力。
• 划船、倒划或航行时施加马达动力。动力不受风向影响。
• 在飞船风向指示器上显示已配置的燃料物品。红色图标表示引擎已启用但没有燃料。
• 通过飞船的网络数据同步启用状态和剩余燃料。
• 服务器端以及每个可拥有飞船物理效果的客户端都需要 PraetorisClient。

个人储物箱

• 将个人储物箱的容量扩展为五列两行。
• 使个人箱子获得与木箱相同的10个物品栏槽位。

史诗战利品新增内容

禁卫客户端新增七种史诗战利品魔法效果：

• 先祖重击： 高稀有度双手棍召唤一个先祖复制体，在目标附近重复玩家的攻击。
• 擦伤： 格挡威力提升50%，但格挡或招架后会附加生命伤害。护甲可减少此附加伤害，但抗性无法减免。
• 反击： 成功格挡可叠加层数。后续的近战攻击会消耗一层，并提升该攻击连段的攻速。稀有度越高，可叠加的层数越多。
• 灌注： 一个已激活的近战武器技能，可将识别到的火焰、冰霜、闪电、毒素或风效果转化为临时元素伤害或攻击速度加成。其冷却时间为120秒。
• 旋风： 高稀有度双手长柄武器获得快速二次旋击，耐力消耗降低，伤害与硬直数值调整。
• 突击： 对踉跄的敌人使用棍棒连击终结技和攻击，会触发一系列伤害递增的连续终结连击。
• 完美打击： 双手斧获得一个时机窗口，在玩家于正确时机攻击时，可触发下一段连击并提高其伤害。

该模组还会改变史诗战利品符文的行为：

• 提取的符文保留来源物品的效果值，并四舍五入到小数点后两位。
• 蚀刻一个比正常上限至少强10%的符文可能会同时摧毁符文和目标物品。
• 破坏几率根据符文的强度在10%到90%之间变化。
• 迷人的界面会显示红色警告并要求进行二次确认。
• 史诗战利品藏宝图宝箱无视结界访问检查。普通宝箱不受影响。

结界数量

将鼠标悬停在普通守卫上以查看 你的结界：当前 / 上限该计数针对你在本世界中的当前角色，包括已加载区域之外的结界。移除结界会减少计数。生物拥有者结界和网络结界不计入此限制。

服务器提供数量和限制。悬停时显示每两秒刷新一次，并显示 不可用 如果不存在最近的服务器响应。请在服务器和客户端上安装此版本。保护结界悬停说明和状态文本在计数上方保持可见。

创意工坊集成

PraetorisClient 提供 Praetoris 创意服务器系统所需的客户端部分：

• 向服务器报告普通库存和Shudnal ExtraSlots的数量。
• 可包含物品名称、堆叠数量、品质、装备状态、来源背包及格子位置。
• 可以将选定的控制台命令限制在玩家被分配的创意区域内。
• 当玩家处于生效的创造区域内时，阻止技能提升。

这些功能的状态来自服务器远程过程调用（RPC）消息。它们没有本地创意区配置条目。

攻城传送门整合

• 侦测网络数据中带有攻城ID或带有 围攻：<id> 传送门标签。
• 停止普通传送门旅行，并将角色和攻城ID发送至服务器。
• 向玩家显示选定的攻城 ID。
• 需要兼容的服务器端攻城系统才能执行实际的进入或传送。
• 包含两个用于标记和测试附近攻城传送门的开发命令。

网络测量与稳定性

帧时间监控

• 默认每30秒写入一次本地帧率和帧时间摘要。
• 记录平均每秒帧数、平均帧时间、百分位数、最大帧时间和长帧计数。
• 可以写入第二个CSV，记录每个超过配置的长帧阈值的帧。
• 这些CSV文件保留在本地，不会包含在网络指标上传中。

套接字与ZDO传输指标

• 默认每5秒采样一次套接字状态。
• 测量延迟、连接质量、发送队列、队列余量、字节速率、ZDO包速率、发送时序和套接字压力。
• 记录汇总ZDO传输值。它不记录ZDO内容、预制件数据、单个ZDO字段或接收/应用事件。

活跃 RPC 探测

• 默认每2秒发送一个小型合成探测器。
• 测量客户端到服务器以及经中继的客户端往返时间。
• 记录超时、服务器中继时间、目标对等端、负载大小和发送队列状态。

指标存储与上传

• 将待处理的套接字和RPC探测指标写入压缩的JSON Lines文件。
• 可在服务器连接期间将文件上传至兼容的 ValheimTracer HTTP 端点。
• 使用服务器签发的持久上传令牌。
• 仅在其最后一批成功后删除待处理文件。
• 保留失败文件以便稍后重试。
• 支持旧版未压缩格式 .jsonl 待处理文件。

服务器同步保护

• 阻止客户端发送点对点 ServerSync 配置广播。
• 该设置由服务器控制，默认启用。

命令

玩家聊天

!link CODE

管理员控制台

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]

当服务器上安装了 ValheimRcon 时，四个服务器宝箱命令也会随之注册。

攻城开发指令

dt_mark_siege_portal <siegeId> [radius] dt_enter_nearest_siege_portal [radius]

这两个命令是开发工具，目前不限于管理员使用。

配置

插件GUID是 普雷托里斯的扭曲客户端配置生成的文件：

BepInEx/config/warpalicious.PraetorisClient.cfg

PraetorisClient会监视此文件并在大约一秒后重新加载更改。Jotunn会将选定的服务器控制设置同步到已连接的客户端。

重要设置包括：

设置	默认	用途
关联.链接命令	!link	设置游戏内账号关联指令。
网络.关闭环境伤害文本	真	隐藏低价值的环境伤害数字。
船只.禁用船水撞击伤害	真实	防止船只受到落水伤害。
烈焰船.启用	真	启用燃料动力船马达。
浮游艇燃料物品预制件	焦灼核心	设置燃料物品预制体。
每秒燃料物品	300	设置单个燃料物品提供的主动马达秒数。
浮游船.后推	1.5	倒车时设置额外马达力度。
焦焰船.缓速推进	1.02	划船时提供额外动力。
焦焰船.半加速	1.2	半帆时设置额外马达动力。
迅猛艇.全速推进	1.5	满帆时设置额外的马达动力。
苏特林船.切换键	左Shift	设置用于切换电机的本地驱动键。
生物主人结界.半径	40	设置所有者的守卫半径（单位：米）。
生物主人结界.更新间隔秒数	2	设置所有权检查之间的延迟。
帧率指标.已启用	真	启用本地帧时间 CSV 文件。
每帧指标摘要间隔秒数	30	设置帧摘要间隔。
帧指标.长帧阈值毫秒	150	设置长帧阈值。
SocketMetrics.Enabled	真	启用套接字和 ZDO 传输示例。
采样间隔秒数	5	设置套接字采样间隔。
Rpc探针.已启用	真	启用主动网络探测。
RpcProbe.间隔秒数	2	设置探测间隔。
网络指标.Http上传首选	真	允许通过服务器签发的ValheimTracer令牌上传。
禁用网络指标	否	本地覆盖设置，禁用套接字指标和 RPC 探测。
禁用网络指标HTTP上传	假	本地覆盖，将网络指标保留在磁盘上。
服务器同步保护。阻止对等服务器同步配置同步	真	阻止对等端配置广播。
兼容性.保护工匠箱的守卫箱子	真	阻止AzuCraftyBoxes使用受护符保护的箱子内容，该护符不允许本地玩家访问。
守卫石.玩家建造上限	5	设置一名玩家在世界上可以拥有的原版守卫石的最大数量。

专用服务器账号关联配置

客户端不需要机器人网址或API密钥。仅在处理链接请求的服务器上设置这些值：

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

这些环境变量会覆盖 接口链接地址 和 API密钥普雷托里斯客户端无法加载 .env 文件本身。启动服务器的服务必须导出这些变量。

诊断数据已写入

帧指标存储在：

BepInEx/日志/PraetorisClient/帧率指标

待处理的网络指标和上传令牌缓存存储在：

BepInEx/日志/PraetorisClient/网络指标

网络指标行可包含玩家名称、Steam 或平台标识符、对等方标识符、世界名称、世界标识符、Valheim 版本以及已安装插件信息。帧指标行可包含世界名称和精确玩家位置。

集成协议

部分迁移的RPC消息有意保留其现有 Discord工具_* 名称，以便当前服务器集成可以继续使用它们。较新的功能使用 普雷托里斯客户端_* 姓名。

创意物品栏请求

请求 RPC：

创意物品栏请求

响应 RPC：

创意物品栏响应

协议会报告玩家身份、普通物品栏数量、额外槽位可用性及数量，以及去重后的合并物品总数。服务器可在需要时请求详细物品条目。

Discord链接API

当玩家进入 !link CODE，服务器将 JSON 发送到配置的链接端点：

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

当端点接受该代码时，必须返回成功的 HTTP 状态。PraetorisClient 会向玩家显示纯文本响应正文。 玩家ID 是服务器的稳定对等标识符，不保证是 Steam ID。

建造

构建前请使用 Valheim 1.0 游戏程序集并重新生成其公开化程序集。较旧的程序集生成的 DLL 虽然可以编译，但在 Valheim 1.0 的控制台命令注册过程中会失败。

dotnet build PraetorisClient.csproj

生成的DLL被写入到 bin/Debug/PraetorisClient.dll.

要针对从测试客户端复制的程序集进行构建，请覆盖这两个路径：

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

附加文档

• 服务器宝箱指令指南