拼布

)

)  

每个模组都为 Hytale 添加了自己的一部分。当两个部分需要修改同一资源时，问题就出现了。

Patchwork 让模组作者能够在现有 JSON 资源中进行针对性修改，而无需随模组附带完整的替换文件。添加一个字段、合并配置、插入新行为、移除过时内容，或根据已安装的其他模组进行条件适配——所有这一切都无需改动原始资源。

你的补丁会随模组一起发布。Patchwork 会收集所有适用的补丁，将它们分层应用于当前加载的资源之上，并通过生成的资源包发布最终结果。

原始文件保持原样不动。

---

只修补你需要的部分

无需复制整个资源来修改一小部分，只需描述修改本身即可：

{
  "Id": "MyMod_EnableFollowing",
  "Target": "Server/NPC/Roles/Creature/Mammal/Cow.json",
  "When": {
    "ModInstalled": "ExampleAuthor:ExampleMod"
  },
  "Operations": [
    {
      "Id": "EnableFollowing",
      "Op": "Merge",
      "Path": "/Parameters",
      "Value": {
        "CanFollow": {
          "Value": true
        }
      }
    }
  ]
}

这个补丁仅在安装了指定模组时才会修改牛。Patchwork 会解析目标资源的当前版本，执行请求的操作，并在运行时生成最终的资源。

无需附带覆盖文件。无需手动维护的副本。当集成不需要时，不会产生任何更改。

精确路径与显式目标通配符

参见资源选择指南。

Target 和 Targets 接受精确的资源路径或以 glob: 开头的显式选择器：

{
  "Target": "glob:Server/NPC/**/*.json",
  "Operations": [{"Op": "Replace", "Path": "/Enabled", "Value": true}]
}

只有带前缀的选择器才会被当作模式。* 匹配单个路径段内的内容，** 跨越零个或多个路径段，? 匹配单个字符。原始通配符和正则表达式不会被解析。展开过程使用一个不可变的原始资源快照，排除 Patchwork 生成的资源包，对匹配结果去重，并以确定性的顺序排列。选择器未匹配任何内容时会产生警告，而不会凭空创建资源。

冲突诊断与目标局部策略

参见可选更改与冲突报告。

Patchwork 会报告来自不同定义在相同目标路径和效果类型上的成功效果之间的重叠。报告会区分同包/跨包范围以及冗余相同/实质性重叠，而不会暴露写入的值或指纹。/patchwork status 显示有界的摘要计数；/patchwork conflicts 列出脱敏的行，/patchwork conflicts <精确目标> 则对报告进行筛选。

中性定义可以选择一个根级 ConflictPolicy：Report（默认）应用并报告重叠，Allow 应用但抑制由该定义引入的行，Reject 仅停止受影响的特定目标，而无关目标继续正常运行。在常规重新加载期间，被拒绝的目标在可用时会保留先前发布的生成字节。策略属于确定性顺序中较晚的定义；它不是所有权、锁定、权限或授权。

---

为模组集成而设计

Patchwork 专为需要协作而又不紧密耦合的模组而构建。

可用于：

• 在安装了另一个模组时添加可选行为。
• 根据你模组中的配置设置更改资源。
• 扩展资源而不替换周围的所有内容。
• 将一项更改应用于多个相关资源。
• 创建仅在相关时激活的兼容层。
• 适配特定的模组或游戏版本。
• 在应用更改前检查资源、字段或配置值是否存在。
• 从另一个已安装模组的已注册数据目录读取受支持的 JSON 配置。
• 即使可选依赖缺失，也保持你的基础资源有效。

一个补丁可以独立存在，可以同时使用多个条件，也可以一次针对多个资源。条件可以使用 All、Any 和 Not 组合，使集成可以根据需要变得精细或灵活。

---

用于精确更改的精简语言

参见核心操作指南。

Patchwork 支持核心 JSON 操作：

• Add（添加） — 添加新字段或数组条目。
• Merge（合并） — 将对象混合到现有部分中。
• Replace（替换） — 更改已存在的值。
• Remove（移除） — 移除现有字段或条目。
• Insert（插入） — 在数组的指定元素之前、之后、开头或结尾插入条目。
• 匹配与跨资源合并 — 使用递归匹配器选择对象条目，或从另一个精确资源合并数据而不修改源文件。

插入操作可以定位稳定的锚点，而不是依赖脆弱的数组索引。它们还可以检测其内容是否已存在，使补丁可以安全地重新生成而不会重复条目。

如果无法完成必需的操作，Patchwork 会拒绝该目标，而不会发布半个应用状态的资源。清晰的诊断信息会指出补丁、操作、目标和原因。

高级操作

参见数组与匹配操作。

当简单的添加、合并或插入不够用时，Patchwork 还提供了四种不限定格式的操作，用于常见的集成任务：

• MergeMatching（合并匹配项） — 在数组中查找匹配的对象条目，然后将新字段深度合并到每个匹配项中。
• UpsertMatching（更新或插入匹配项） — 合并到匹配条目中，如果没有匹配项则插入一个新对象。
• OverlayFromAsset（从资源覆盖） — 将整个精确路径源资源深度合并到当前目标上。源值优先，而目标中不相关的字段保持不变。
• MergeObjectFromAsset（从资源合并对象） — 将另一个精确路径源资源中选定的一个对象深度合并到目标中的现有对象中。

匹配使用与其他数组操作相同的递归对象匹配器，并且两个跨资源操作都读取原始生成快照。它们从不修改其源资源，不接受 glob: 源，并且当源仅存在于某些模组设置中时，可以使用 Required: false 使其成为可选。

---

设计上支持条件化

参见条件：仅在需要时应用。

兼容性补丁应该只在其有意义时出现。

Patchwork 可以基于以下条件更改：

• 已安装的模组
• 模组、游戏或服务器版本
• 资源存在或缺失
• 目标资源是否存在
• 资源内的 JSON 字段和值
• 存储在另一个已安装 Java 模组的已注册数据目录中的 JSON 配置
• 条件的嵌套组合

这允许模组直接附带其集成，而不是要求服务器所有者下载并安排一组单独的兼容包。

Patchwork 对其他模组数据的访问是只读的，并且仅限于已注册的模组数据目录。它不能使用绝对路径或逃逸到文件系统中无关的部分。

---

一个 Patchwork，无论它以何种方式到来

参见如何嵌入 Patchwork。

Patchwork 既可以作为独立模组使用，也可以作为可嵌入的 Java 运行时使用。

模组作者可以将 Patchwork 声明为依赖项，或直接嵌入它，这样他们的补丁就能继续工作，而无需服务器所有者手动安装另一个 jar 文件。

如果多个模组都带有自己的副本，Patchwork 会选择恰好一个活动运行时：

1. 最新的兼容版本胜出。
2. 如果版本相同，则优先选择独立安装。
3. 所有其他副本保持被动状态。

只有被选中的运行时才会扫描补丁、生成资源、注册命令并执行后台工作。嵌入的副本仍然可以贡献集成，而不会创建重复的补丁系统。

---

为共存而构建

Patchwork 从不编辑属于 Hytale 或其他模组的源文件。它会在自己的运行时资源包中生成修补后的副本，从而保留底层原始材料。

补丁以稳定、确定的顺序应用。多个模组可以为同一目标贡献更改，失败的目标会被排除在生成的输出之外，而不会以部分修改的状态发布。

某些资源类型可以实时更新，而其他资源类型可能需要重启。Patchwork 通过其状态和重新加载工具如实报告这种区别。

---

Tamework 兼容性

Patchwork 最初是 Alec's Tamework 内部的通用资源修补器。

独立版本保留了现有的补丁格式，并在安装 Tamework 时继续识别 Server/Tamework/Patches 下的旧版补丁。新的集成应使用中立位置：

Server/Patchwork/Patches

Tamework 可以嵌入 Patchwork 并贡献其自己的宏和重新加载行为，而核心修补系统对每个模组都有用——不仅仅是 Tamework 的扩展。

---

面向服务器所有者

参见服务器所有者指南。

Patchwork 的大部分功能旨在静默工作。

当模组将 Patchwork 列为必需依赖时，安装独立的 jar 文件。如果模组已经嵌入了兼容版本，则除非该模组的文档另有说明，否则无需额外安装。

Patchwork 会自动防止重复运行时执行重复工作。

管理工具可在以下位置使用：

/patchwork

这些工具提供补丁状态、诊断、显式重新生成以及故障排查时的自测功能。它们需要 patchwork.admin 权限，并默认属于 hytale:Admin 组。

---

创作与技术细节

独立插件将 Server/Patchwork/Patches/**/*.json 注册为原生的 Hytale 资源类型。Hytale 的资源编辑器 可以发现、创建、结构化编辑、验证并保存 Patchwork 使用的相同可移植定义。

参见字段参考和兼容性与版本指南。

生成依赖索引记录了定义文件、具体的目标展开结果、精确的跨资源来源以及 glob 稳定前缀。被选中的运行时使用它来将相关的目录包编辑去重为一次自动重新生成过程；Patchwork 生成的输出被排除在外，因此不会反馈回自身。存档包和未注册的模组数据更改仍需要手动或重启驱动。参见重新加载与生成文件。

对于受监控的 Hytale 服务器存储，Patchwork 仅在 Hytale 报告了预期的生成提供程序和资源路径后，才调用目标 hot-reloaded。常见、自定义、未知、禁用监控或未确认的路径仍需要重启；仅写入生成文件永远不会被视为实时重新加载。

Patchwork 1.2.1 支持以下安装模式：

• 将 patchwork-standalone-1.2.1.jar 作为 Hytale 服务器模组安装。
• 将 com.alechilles:patchwork-runtime:1.2.1 嵌入到另一个 Java 插件中。

有关完整的技术细节，请参阅补丁结构、操作、嵌入 Patchwork以及兼容性与版本。

---

让模组协同工作

一个好的兼容层应该感觉像是设计的一部分。

Patchwork 为模组作者提供了一种共享的方式，可以在 Hytale 资源上分层应用聚焦的、有条件的更改——无需复制整个文件、强制硬依赖或破坏彼此的工作。

带来你自己的部分。Patchwork 将帮助你将其拼接起来。

---

来源： https://github.com/Alechilles/Patchwork

文档： https://wiki.hytalemodding.dev/mod/patchwork

面向模组作者： 补丁定义应放置在 Server/Patchwork/Patches/**/*.json 下

Patchwork 在 Patchwork 源代码可用许可证 1.0 下以源代码可用形式提供。