条件配置同步

条件配置同步

条件配置同步是《英灵神殿》模组的共享基础库。它本身不添加游戏内容、物品、UI或配置选项。当其他模组将其列为依赖项时，请安装它。

该软件包提供集中式配置同步、版本检查、服务器端策略覆盖、受保护锁定以及同步运行时值。将此逻辑保留在一个独立的依赖项中意味着，可以通过更新此软件包来发布修复，而无需重新构建每个使用它的模组。

这是一个独立的同步选项，面向需要按设置项分别控制所有权策略、隐藏设置项控制以及扩展运行时值行为的模组作者。Jotunn 和 ServerSync 仍是各自独立的库，拥有各自的使用场景和开发路线。

玩家

通常，模组管理器会自动将条件配置同步作为依赖项安装。在任何已启用的模组依赖它时，请保持其安装状态。

这个包：

• 做 不 替换、修改或拦截 服务器同步 被其他模组使用；
• 做 不 迁移或修改属于其他模组的配置；
• 可以与Jotunn及使用以下内容的模组同时运行： 服务器同步;
• 只处理明确针对条件配置同步构建的模组。
  

单独安装此包不会产生任何游戏效果。

包裹内容

雷暴商店包含：

• ConditionalConfigSync.Plugin.dll - BepInEx 引导程序已注册为 _shudnal.条件配置同步;
• ConditionalConfigSync.dll - 供依赖模组使用的公共 API 和同步运行时；
• ConditionalConfigSync.xml - 面向IDE和模组作者的IntelliSense文档；
• SHA256SUMS.txt - 两个发布版 DLL 文件的 SHA-256 哈希值。
  

两个 DLL 文件必须一起保留安装。XML 和文档文件在运行时是可选的，但对开发、验证和重新分发很有用。

兼容性

条件配置同步使用其自有的BepInEx和Harmony标识符：

_shudnal.条件配置同步

它不会修补、替换或禁用Jotunn同步或 服务器同步这些库可以在同一进程中并存，因为每个模组会继续使用其编译时所依赖的同步库。

嵌入或IL重打包 ConditionalConfigSync.dll 将模组嵌入另一个模组的行为不受支持。内嵌副本会拒绝初始化并报告明确错误。请改用独立的Thunderstore依赖项。

服务器管理员

默认行为

每个已注册的设置都有三种归属模式之一，由模组作者选择：

• 始终服务器控制 始终从服务器同步，且无法通过策略释放。模组作者应将其用于共享机制和同步状态，这些机制和状态必须在服务器和每个客户端上使用相同的有效值。典型示例包括游戏规则、世界状态生成、共享事件、网络可见计算，以及当各端不一致时会出故障的功能开关；
• 条件 使用模组定义的服务器/客户端默认值，并可能被服务器策略覆盖。当管理员可以在一个共享服务器值和每个客户端行为之间合理选择时，这很合适；
• 始终客户端控制 始终是各客户端本地的，无法通过同步策略强制同步。它用于表现、本地UI、控制及其他不参与共享机制的行为。
  

模组还可以注册一个锁定设置，用于控制普通客户端是否可以发布对服务器控制设置的更改。隐藏状态策略是独立的，并且在任何所有权模式下都可能对兼容的配置管理器隐藏设置。

策略文件创建于 BepInEx/配置/shudnal.ConditionalConfigSync 在服务器上。现有文件在服务器启动期间、文件监视器启用之前同步读取。读取会重试直到文件元数据稳定，因此常见的编辑器保存方式（如截断/写入/重命名）不会用不完整的快照替换正在使用的策略。之后文件会被监视变更，并且可以在服务器运行时进行编辑。

锁定行为

条件配置同步提供了ServerSync用户熟悉的锁定模型，并为锁定设置本身增加了明确的保护。

当锁定启用时：

• 普通客户端无法发布对服务器控制设置的更改；
• 服务器管理员获得豁免，可以编辑它们；
• 客户端控制的设置保留在本地且可编辑。
  

当锁定被禁用时，如果模组作者启用了未锁定客户端更新，普通客户端可以向服务器控制的设置发布更改。

锁定设置始终受保护：

• 服务器始终控制；
• 它无法通过策略强制由客户端控制；
• 非管理员客户端即使在其余配置已解锁的情况下也无法更改它。
  

这会阻止客户端通过先更改锁定设置来尝试授予自身权限。

同步策略

文件：

BepInEx/config/shudnal.ConditionalConfigSync/ConditionalConfigSync.SyncPolicy.cfg

规则可以针对一个确切的设置或整个配置节：

ModGuid.Section.Key
模组标识.章节

使用 + 强制获取服务器所有权并 - 强制客户端归属：

# 精确设置
+ 作者.模组.通用.伤害倍率
- author.mod.Interface.显示状态面板

# 区块中的每一个条件设置
+ 作者模组.玩法
- author.mod.Interface

规则：

• + 标识符 部队匹配 条件 设置由服务器控制；
• - 标识符 部队匹配 条件 客户端控制的设置；
• 精确设置规则优先于整节规则；
• 没有保留模组作者默认设置的匹配条目；
• 始终由服务器控制 和 始终由客户端控制 忽略同步策略所有权覆盖；
• 格式错误、重复、冲突、未知和被忽略的条目可以通过以下方式报告： 条件配置同步策略验证;
• 强制将受保护的锁定设置设为客户端控制将被忽略。
  

策略只能通过这些文件进行编辑。控制台命令有意只提供重载、验证、状态和转储操作，而不会添加、删除或重写规则。通过文件编辑可以保持完整策略可见、可审查且易于还原。

典型用途：

• 在公共服务器上强制执行原本仅限客户端的游戏选项；
• 从服务器控制中解除一个外观或UI设置的发布；
• 切换整个部分，无需逐一列出每个设置；
• 覆盖一项设置，使其与所在区域的其余设置不同；
• 临时测试不同的归属模型，而无需重建模组。
  

隐藏设置

文件：

BepInEx/config/shudnal.ConditionalConfigSync/ConditionalConfigSync.HiddenConfigs.cfg

每行添加一个精确的设置标识符或整节标识符：

# 精确设置
作者.模组.高级.内部倍率
作者模组.调试.启用详细输出

# 段落中的每一项设置
模组作者：进阶

精确匹配或节匹配会将该项设置标记为在兼容的配置管理器中不可浏览。隐藏是一种呈现策略，而非安全边界：该设置仍然存在，其同步行为由以下项单独控制 同步策略.cfg，它的 配置同步模式，以及锁定状态。

典型用途：

• 在普通配置界面中隐藏高级或危险选项；
• 简化公共服务器的可见设置；
• 用一行代码隐藏整个内部区块；
• 在配置文件中保留诊断选项，但不在管理器中公开显示。
  

调试日志记录

本地调试设置存储在：

BepInEx/config/shudnal.ConditionalConfigSync/ConditionalConfigSync.Debug.cfg

诊断用控制台命令：

条件配置同步_调试
条件配置同步_调试服务器

服务器策略命令：

条件配置同步状态
条件配置同步策略重载
条件配置同步策略校验
条件配置同步策略转储

• 状态 显示已注册的模组、模式数量、生效的服务器控制设置、隐藏设置以及策略文件路径；
• 重新加载政策 在Unity主线程上立即读取并应用两个策略文件；
• 策略验证 报告语法错误、重复项、冲突、未知标识符以及被固定模式忽略的规则；
• 政策转储 写入 条件配置同步.策略转储.txt 带有可直接复制的精确标识符和章节标识符。每个设置后面只跟随其策略模式和默认归属；变量类型被有意省略。
  

调试日志记录支持 基础, 详细，以及 追踪 级别和一个可选的模组名称过滤器。正常启动保持静默；警告和错误无需调试日志即可显示。

模组作者

条件配置同步是一个第三方独立依赖项。不要用 ILRepack 将其嵌入，也不要在各个模组内附带私有副本。

仅供参考：

条件配置同步.dll

然后将独立的 BepInEx 插件声明为硬依赖：

【BepIn依赖(
    _shudnal.条件配置同步
    硬依赖标志的BepIn依赖特性

使用命名空间：

使用ConditionalConfigSync；

公共API保持熟悉的 配置同步 ServerSync 也使用的名称：

内部静态只读配置同步 configSync = 新的配置同步(插件ID)
{
    显示名称 = pluginName,
    当前版本 = 插件版本，
    最低所需版本 = 插件版本，
    模组必需 = 真
};

远程端需要该模组

需要模组 控制是否 拥有模组 远程端也必须安装且兼容。这与 BepInEx 对 Conditional Config Sync 本身的硬依赖是分开的：

• 硬依赖要求 CCS 必须与所属模组安装在同一台机器上；
• 需要模组 需要在连接另一端拥有兼容的所属模组副本。
  

在建立连接之前设置，最好在 配置同步 对象初始化器：

这是C#代码，不是自然语言文本，不支持翻译。请提供游戏内的自然语言文本。
{
    显示名称 = 插件名称，
    当前版本 = 插件版本，
    所需最低版本 = 插件版本,
    需要模组
};

行为是对称的：

• 本地运行模组的一方： 客户端 — 需要模组: 真 — 未安装模组的远端： 服务器 — 结果： 客户端连接被拒绝
• 运行模组的本地端： 服务器 — 需要模组: 真 — 未安装模组的远端： 客户端 — 结果： 服务器拒绝该客户端
• 运行模组的本地端： 客户端或服务器—— 需要模组: 假 — 未安装模组的远端： 远程同伴 — 结果： 允许连接，但此模组实例未与缺失的远程副本同步
  

使用 真 对于服务器权威、世界状态、游戏玩法或其他双边模组。像Seasons这样同步当前季节、日期、设置和运行时状态的模组，必须要求其远程副本。保留默认值 假 仅适用于纯客户端模组或可选集成，且在其他端未安装时仍能正常运作。

当远程副本存在时， 当前版本, 最低要求版本，CCS通信协议用于兼容性检查。延迟注册或 请求完全同步() 不重复连接准入，因此配置 需要模组 正在创建 配置同步 副本。

在一次调用中注册现有的 BepInEx 条目及其模式：

配置项<float> 伤害 = Config.Bind(
    玩法
    伤害倍率
    1f，
    "服务器玩法设置");

添加配置项(
    伤害，
    始终由服务器控制);

使用 始终由服务器控制 当该设置控制的是结果必须在服务器和所有客户端之间保持一致的通用机制时。不要将此类设置保留 条件 仅仅为了通过策略使其可配置：允许一个客户端恢复本地值，就可能导致共享计算、事件、状态转换或网络可见行为出现分歧。

或者在一次调用中绑定并注册：

同步配置项<bool> showPanel = configSync.AddConfigEntry(
    配置，
    界面
    显示状态面板，
    真,
    新的配置说明（“本地 UI 设置”），
    始终由客户端控制);

对于策略控制的设置，请在注册后指定默认所有权，而无需分配第二个属性：

已同步配置项<float> scale = configSync.AddConfigEntry(
    配置，
    玩法
    世界比例
    1楼，
    可能通过SyncPolicy重新分配
    配置同步模式.条件模式，
    默认由服务器控制：true）；

兼容性重载仍然可用：

configSync.AddConfigEntry(entry); // 有条件的，默认由服务器控制
configSync.AddConfigEntry(entry, false); // 条件性条目，默认由客户端控制

直接传递模式/默认值可防止出现临时的服务器控制注册状态，并避免初始化期间重复的策略状态转换。

运行时值也可用：

public static readonly CustomSyncedValue<string> mapData =
    新(configSync, "地图数据", "");

使用 自定义同步值<T> 对于状态。相等的赋值会被其比较器抑制。请使用 序列化自定义同步值<T> 对于类似事件的数据，重复的相同负载也必须按顺序传递。

与 DLL 一同发布的 XML 文件直接在 IDE IntelliSense 中记录了公共 API、分配模式、比较器、优先级、版本检查和集成细节。

协议兼容性

条件配置同步使用独立于DLL和包版本的数值线协议版本。

首个公开版本使用协议 1。客户端和服务器必须使用相同的协议版本。只有在引入不兼容的网络格式变更时，协议号才会增加；只要通信协议保持兼容，普通的库更新不需要提升协议版本。

延迟报名与重新同步

网络会话启动后注册的配置和自定义值将自动处理：

• 服务器会批量处理新注册的值，并广播其当前状态；
• 客户端在之后注册值 初始同步完成 请求从服务器进行完全重新同步；
• 同一帧内的多次注册会合并为一次操作。
  

A 配置同步 在正常连接启动窗口之后创建的实例也会注册其RPC处理器，并自动请求其第一个完整包。重建动态注册集的模组可以调用 configSync.RequestFullSync() 明确地返回方法的结果。 假 未连接远程服务器时。

连接准入和模组版本验证仍在瓦尔海姆的正常对等握手期间进行。需要强制版本控制的模组应创建其 配置同步 连接前的实例；延迟重新同步会更新数据，但不会追溯重复已完成的连接检查。

生命周期与诊断事件

每个 配置同步 实例为需要重建派生运行时状态或提供自身诊断的模组暴露了可选事件：

• 初始同步已完成 在客户端上应用第一个完整服务器包之后；
• 连接重置 在服务器数值被清除且本地备用数值被恢复后；
• 策略状态已变更, 服务器控制变更，以及 隐藏状态已改变 当有效政策发生变化时；
• 锁定状态已变更 当有效锁定或管理员豁免发生变化时；
• 同步被拒 当数据包或传出更新因权限、数据格式错误、队列溢出或20 MiB安全限制而被拒绝时。
  

订阅者异常会被隔离并记录日志，因此单个消费者无法中断其余模组或条目的同步。完整的使用说明包含在 XML 文档中。

为何单独依赖

与嵌入同步源文件或对私有 DLL 进行 ILRepack 相比：

• 所有依赖模组均使用同一份持续维护的实现；
• 修复网络、策略、序列化或安全性问题只需更新此包；
• 避免重复的 Harmony 补丁、监视器、命令和静态注册表；
• 服务器管理员为所有参与的模组获得一个通用策略层；
• 依赖的模组包保持更小更简单。
  

对于 Thunderstore，请将此包添加到模组的依赖项中。请勿将任一 Conditional Config Sync DLL 复制到依赖模组自己的包中。

与ServerSync的功能差异

分配与隔离

• 作为独立的BepInEx硬依赖项提供，而非使用ILRepack嵌入。
• 使用专用的命名空间、BepInEx GUID、Harmony ID、RPC 名称和包格式。
• 不会修改或拦截其他模组使用的ServerSync实例。
• 检测并拒绝不支持的内嵌条件配置同步副本。
  

配置归属与策略

• 在客户端上保留独立的本地和活动服务器值。
• 支持在服务器控制状态和客户端控制状态之间运行时切换。
• 添加三种显式配置模式： 始终服务器控制, 条件，以及 始终由客户端控制.
• 添加服务器端 同步策略.cfg 覆盖精确设置和完整区块。
• 添加精确设置和章节级 隐藏配置.cfg Configuration Manager 可见性规则。
• 随服务器数值一同发送有效配置状态。
  

锁定与管理

• 保持 ServerSync 中熟悉的锁定和管理员豁免模式。
• 即使配置已解锁，也会保护锁定设置本身。
• 拒绝非管理员网络尝试更改受保护的锁。
• 为当前的 Valheim 管理员检查及更清晰的日志使用已连接的对等方身份。
  

自定义同步数值

• 区分类状态 自定义同步值<T> 从事件类 序列化自定义同步值<T>.
• 支持显式 分配本地值, 如果已更改则分配本地值，以及 分配本地值并通知 行为。
• 支持为集合和域类型自定义相等比较器。
• 支持优先级，并保持序列值的顺序。
• 在同步进行期间安全推迟传出更新，而不是丢弃变更。
  

序列化与网络

• 普通 配置项 数值根据本地设置类型使用BepInEx TOML转换。
• 自定义值保留类型化的Valheim包序列化并支持 可序列化参数.
• 使用带长度前缀的条目，以便安全跳过未知的包条目。
• 添加压缩、分片、队列限制、有效载荷限制以及更清晰的故障日志记录。
• 添加独立的数字协议版本，与客户端/服务器精确匹配。
• 支持自动延迟注册和显式完全重新同步。
  

诊断与文档

• 新增稳定/重试策略读取机制，避免部分编辑器写入替换当前生效的策略。
• 当相关会话或启动流程结束时，清理策略监视器、网络缓存、待处理队列、已注册的会话处理器以及 Harmony 所有权。
• 添加按模组接收日志，包含用于单值更新的配置/自定义值名称。
• 包含可选的过滤调试日志记录以及服务器策略状态、重载、验证和转储命令。
• 为重要的公共API成员提供船舶XML智能感知文档和元数据描述。
  

迁移说明

在模组中使用条件配置同步会为该模组选择其同步实现和协议。服务器和客户端应同时更新依赖模组和此依赖项。其他使用ServerSync的已安装模组不受影响。

许可与致谢

原始条件配置同步贡献在以下许可下发布： 无许可证该项目采用ServerSync方法并改编代码作为基础；适用的ServerSync部分仍受其MIT-0条款约束。部分实现和兼容性思路参考了Jotunn。保留的声明可在以下位置查看 第三方声明.md.

安全与隐私

条件配置同步：

• 不含遥测功能，不会向外部服务发送任何数据；
• 不发起任何 HTTP 请求，也不在活动的 Valheim 客户端/服务器会话之外打开任何网络连接；
• 不下载、更新或执行外部程序；
• 不会访问 Windows 注册表，也不附带原生库；
• 仅通过当前服务器与其连接的客户端之间的英灵神殿 RPC 连接进行通信；
• 仅将其策略、调试、转储和诊断文件写入 BepInEx/配置/shudnal.条件配置同步;
• 仅通过反射访问 Valheim 运行时成员，这些成员的可访问性与公开化开发程序集不同；
• 发布未混淆的二进制文件、XML API 文档、源代码以及两个 DLL 文件的 SHA-256 哈希值。
  

链接

• 源仓库
• 请我喝杯咖啡
• Discord