客户端幽灵看门狗 · Valheim: 英灵神殿Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

[size=6]ClientGhostWatchdog[/size]

一个独立的、100% 客户端侧的看门狗模组，供连接到远程/专用 Valheim 服务器的玩家使用，用于防止 [b]"僵尸客户端" / "幽灵连接"[/b] 失同步状态。

[quote]

[!NOTE]

[b]仅客户端：[/b] 此模组安装在你本地的 PC 上。它[b]不[/b]需要安装在服务器上，并且在连接任何专用或社区服务器时都能工作。

[/quote]

[size=5]问题所在[/size]

在专用或远程服务器上游戏时，如果服务器断开了你客户端的连接（例如在每日计划的服务器重启期间、网络故障，或 ISP 超时并伴随 [b]ClosedByPeer[/b] 状态），原版 Valheim 存在一个严重的客户端侧 bug：

[list=1]

[*] [b]ZNet.UpdatePeers()[/b] 忽略了 [b]ZRpc.Update()[/b] 报告的断开连接错误码。

[*] [b]ZSteamSocket.IsConnected()[/b] 只检查指针有效性，即使套接字已关闭仍保持"已连接"状态。

[*] 客户端的 [b]ZNet.m_connectionStatus[/b] 仍保持为 [b]Connected[/b]。

[*] 客户端继续在一个空无一人、失同步的世界中运行，却未意识到自己已被断开连接。在失同步期间建造的任何建筑、移动的物品或执行的操作都会丢失，或导致失同步回滚。

[/list]

[size=5]解决方案[/size]

[b]ClientGhostWatchdog[/b] 在连接到远程服务器时，会在你的游戏客户端上运行一个独立的背景协程：

[list]

[*] [b]无 [b]Game.Update[/b] 开销[/b]：完全通过一个专用的 Unity 协程以实时休眠间隔运行，在 [b]Game.Update[/b] 中执行零次逐帧检查。

[*] [b]在本地世界上禁用[/b]：在单人世界或本地服务器主机上（[b]ZNet.instance.IsServer()[/b]）严格不活动。不启动协程，也不运行检查。

[*] [b]两阶段检测[/b]：

[list]

[*] [b]阶段 1（半程警告）[/b]：当服务器静默时间达到配置超时周期的一半时（例如在默认 30 秒超时下的 15 秒），屏幕中央会显示一个醒目的提示警告玩家：[b]"服务器连接已丢失，正在尝试重新连接... ({0}s)"[/b]。[b]{0}[/b] 占位符会随断开倒计时动态更新。

[*] [b]自动恢复[/b]：如果服务器通信在警告阶段恢复，警告会被关闭，并在屏幕上显示一条确认提示：[b]"服务器连接已恢复。"[/b]

[*] [b]阶段 2（超时与干净登出）[/b]：如果静默时间达到完整超时、服务器套接字关闭或服务器对端掉线，模组会显示 [b]"服务器连接已丢失。正在断开连接..."[/b]，暂停配置的提示延迟（[b]DisconnectDelaySeconds[/b]，默认 5 秒）以便提示可读，然后触发 [b]Game.instance.Logout()[/b]。[/list]

[*] [b]对端被切断与行为不良模组的保护[/b]：捕获第三方模组（如 [b]ServerCharacters[/b] 物品栏同步超时）或网络故障在无引擎登出的情况下导致服务器对端掉线的场景，防止玩家被困在失同步的边缘状态中。

[*] [b]保留原生断开原因[/b]：如果管理员踢出或封禁玩家，或服务器关闭，看门狗会退让给原生 Valheim，允许玩家看到真实的错误对话框，而不是通用的看门狗提示。

[*] [b]传送门与传送挂起防护[/b]：如果玩家卡在无限期传送门失同步中，会在达到可配置上限（[b]TeleportTimeoutSeconds[/b]，默认 30 秒）后恢复健康检查。

[*] [b]保留玩家进度[/b]：调用 [b]Game.instance.Logout()[/b] 确保客户端在返回主菜单前干净地保存其角色档案（[b]SavePlayerProfile(setLogoutPoint: true)[/b]）。

[*] [b]告知玩家[/b]：在主菜单上显示一个信息对话框，告知玩家为何被返回菜单，以及其本地存档已保留。

[*] [b]防御性生命周期与状态安全[/b]：集中式状态机（[b]WatchdogManager[/b]）配合原子化、带 TTL 的断开原因管理（[b]DisconnectReasonManager[/b]），防止跨场景转换时出现陈旧的错误对话框。

[/list]

[line]

[size=5]设计理念与权衡[/size]

此模组有意强制执行[b]故障安全断开策略[/b]：

[list]

[*] [b]为什么是故障安全断开？[/b]：在原版 Valheim 中，抓住一个未确认的死亡连接不放，有丢失宝贵建造、采集或战斗进度的风险。通过 [b]Game.instance.Logout()[/b] 强制干净登出，模组会在失同步恶化之前立即保存玩家的本地物品栏和状态。

[*] [b]处理不稳定的连接[/b]：如果你经常在高延迟卫星连接、波动的蜂窝网络或容易发生数秒丢包的 Wi-Fi 上游戏：

[list]

[*] 增加 [b]TimeoutSeconds[/b]（例如增加到 [b]60[/b] 或 [b]90[/b] 秒）。半程警告会相应缩放（60 秒超时对应 30 秒警告），给你的连接充足时间在触发任何断开之前恢复。

[*] 你也可以将 [b]TimeoutSeconds[/b] 设为 [b]0[/b]，从而在不移除模组的情况下完全禁用看门狗。

[/list][/list]

[line]

[size=5]配置[/size]

配置文件会自动生成在 [b]BepInEx/config/dreamwraith.ClientGhostWatchdog.cfg[/b]：

[b]分区 | 设置项 | 类型 | 默认值 | 描述[/b]

[b]1 - General[/b] | [b]TimeoutSeconds[/b] | [b]float[/b] | [b]30[/b] | 断开连接前的服务器静默总秒数。进行到一半时（例如 15 秒），会显示警告提示。范围：[b]0[/b] 到 [b]300[/b]。设为 [b]0[/b] 以禁用看门狗。

[b]1 - General[/b] | [b]CheckIntervalSeconds[/b] | [b]float[/b] | [b]1.0[/b] | 背景协程中看门狗检查之间的间隔秒数。范围：[b]1.0[/b] 到 [b]5.0[/b]。

[b]1 - General[/b] | [b]TeleportTimeoutSeconds[/b] | [b]float[/b] | [b]30[/b] | 玩家在传送状态下最多可保持的秒数，之后看门狗健康检查会恢复。防止传送门挂起时陷入无限期边缘状态。范围：[b]0[/b] 到 [b]180[/b]。设为 [b]0[/b] 以禁用上限。

[b]2 - On-Screen Notices[/b] | [b]WarningNoticeMessage[/b] | [b]string[/b] | [b]"服务器连接已丢失，正在尝试重新连接... ({0}s)"[/b] | 在半程标记处显示的大型屏幕中央提示。[b]{0}[/b] 会被替换为剩余秒数。

[b]2 - On-Screen Notices[/b] | [b]RecoveredNoticeMessage[/b] | [b]string[/b] | [b]"服务器连接已恢复。"[/b] | 如果连接在超时前恢复，则显示的大型屏幕中央提示。

[b]2 - On-Screen Notices[/b] | [b]DisconnectNoticeMessage[/b] | [b]string[/b] | [b]"服务器连接已丢失。正在断开连接..."[/b] | 达到超时时显示的大型屏幕中央提示。

[b]2 - On-Screen Notices[/b] | [b]DisconnectDelaySeconds[/b] | [b]float[/b] | [b]5.0[/b] | 显示断开提示后、执行登出前等待的秒数，给玩家时间阅读提示。范围：[b]0[/b] 到 [b]30[/b]。设为 [b]0[/b] 以立即登出。

[b]3 - Main Menu Dialog[/b] | [b]ShowDisconnectReason[/b] | [b]bool[/b] | [b]true[/b] | 是否在被此看门狗断开后，在主菜单上显示说明信息。

[b]3 - Main Menu Dialog[/b] | [b]DisconnectMessage[/b] | [b]string[/b] | [b]"服务器连接已丢失（已防止幽灵连接）。进度已在本地保存。"[/b] | 断开连接时在主菜单对话框中显示的自定义消息。

[b]4 - Debug[/b] | [b]EnableDebugLogs[/b] | [b]bool[/b] | [b]false[/b] | 启用后，会在每次看门狗检查 tick、计时器事件、阈值评估和连接生命周期钩子时打印详细的调试日志。

[b]4 - Debug[/b] | [b]DebugSimulateSeverKey[/b] | [b]KeyCode[/b] | [b]None[/b] | 仅调试用：模拟突然的对端断开（ServerCharacters 行为）的按键绑定。需要 EnableDebugLogs 为 true。正常游戏时保持为 None。

[line]

[size=5]安装[/size]

[quote]

[!TIP]

[b]仅客户端：[/b] 通过你的模组管理器（Gale / r2modman / Thunderstore）或手动拖放安装到你的本地 PC。服务器上无需安装任何内容。

[/quote]

[list=1]

[*] 确保你的客户端已安装 [b]BepInExPack Valheim[/b]。

[*] 通过 [b]Gale[/b] / [b]r2modman[/b] 安装，或手动将 [b]ClientGhostWatchdog.dll[/b] 复制到你的 [b]Valheim/BepInEx/plugins/[/b] 文件夹中。

[*] 启动 Valheim 并连接到你的服务器。

[/list]

[line]

[size=5]从源码构建[/size]

该项目使用可移植的 MSBuild 配置，可自动检测标准 Steam 路径。

[code]dotnet build -c Release[/code]

编译后的程序集将放置在 [b]bin/Release/net48/ClientGhostWatchdog.dll[/b]。以 [b]Release[/b] 配置构建时，还会自动将分发 ZIP 打包到 [b]bin/Publish/ClientGhostWatchdog-<Version>.zip[/b]。

[size=4]自定义与 CI 路径[/size]

对于自定义安装或 CI/CD 流水线，你可以使用环境变量或本地 [b].user[/b] 属性文件来指定路径：

[list]

[*] [b]环境变量[/b]：

[list]

[*] [b]VALHEIM_PATH[/b]：你的 Valheim 游戏根目录的绝对路径。

[*] [b]BEPINEX_PATH[/b]：你的 BepInEx [b]core[/b] 文件夹的绝对路径。[/list]

[*] [b]本地用户覆盖[/b]：将 [b]ClientGhostWatchdog.csproj.user.example[/b] 复制到项目根目录的 [b]ClientGhostWatchdog.csproj.user[/b]（此文件被 git 忽略，并由 MSBuild 自动加载）：

[code] <?xml version="1.0" encoding="utf-8"?>

<GamePath>C:\Games\Valheim</GamePath>

<BepInExCorePath>C:\Games\Valheim\BepInEx\core</BepInExCorePath>

</PropertyGroup>

</Project>[/code]

[/list]

[line]

[size=5]打包、发布与发行版[/size]

所有用于发行版管理、打包以及发布到 [b]Thunderstore[/b]、[b]Hexium[/b] 和 [b]Nexus Mods[/b] 的开发者自动化工具，都整合到单一的 PowerShell 7 入口点 [url=.scripts/modtools.ps1].scripts/modtools.ps1[/url]，由共享的 [url=https://github.com/DreamWraith/DW-ValheimModTools][b]DW.ValheimModTools[/b][/url] 模块提供支持：

[list]

[*] [b]发行版管理[/b]：pwsh ./.scripts/modtools.ps1 release 会以 Release 编译、创建模组与源码归档、提取变更日志说明，并使用 gh CLI 发布 GitHub Releases（默认草稿，或使用 -Publish 发布）。

[*] [b]打包与版本号提升[/b]：pwsh ./.scripts/modtools.ps1 package -Bump Patch 会在 ClientGhostWatchdog.csproj 中递增 SemVer、更新 manifest.json，并捆绑分发包。

[*] [b]门户发布[/b]：pwsh ./.scripts/modtools.ps1 publish -Target All 会直接上传到 Thunderstore、Hexium 和 Nexus Mods API。

[*] [b]CI/CD 工作流[/b]：[url=.github/workflows/publish.yml].github/workflows/publish.yml[/url] 提供一个自动化 GitHub Actions 工作流，在每次发布 GitHub Release 时发布到 Thunderstore、Hexium 和 Nexus Mods。

[/list]

有关参数、工作流和密钥配置的详细文档，请参阅 [url=.scripts/README.md].scripts/README.md[/url]。

[size=5]许可证与作者说明[/size]

[list]

[*] 本项目基于 GNU General Public License v3.0 许可 - 详见 [url=LICENSE.md]LICENSE.md[/url] 文件。

[*] [url=https://gist.github.com/dreamwraith/98564f8441dc234bfadd7e2b605c694c][b]关于 Valheim 模组制作的一点个人说明[/b][/url] - 关于开源模组制作、社区包容性和反守门行为的思考。

[*] [url=https://gist.github.com/dreamwraith/77c91d656c842611bf8c40febf8056f2][b]关于 AI、软件工艺以及这段代码为何存在的说明[/b][/url] - 关于软件工艺、人类能动性和工程责任的个人随笔。[/list]

评论