用户数据扩展 - JSON 模组加载器

用户数据扩展 - JSON 模组加载器

一个基于JSON的《怪物猎人:荒野》USER数据模组加载器。无需替换原生USER文件即可修改字段和添加条目,减少整文件模组冲突,使数据驱动的模组更易于创建、维护和分享。

[size=6][b]User Data Extension[/b][/size]
[b]编辑你需要的数据。保持原生文件不变。[/b]

UserDataExtension(UDE)是一个基于 JSON 的《怪物猎人:荒野》USER 数据模组加载器。它允许模组在不分发完整替换 USER 文件的情况下,修改字段、调整数值,并向现有游戏数据添加条目。

每个模组不再替换整个资源,而是只描述它需要的更改。UDE 将这些更改应用到游戏加载的数据上,从而让相互兼容的修改可以共享同一个资源。

[b]对玩家而言,UDE 是基于 JSON 的数据模组的共享前置。对模组作者而言,它是创建、审查和分发定向数据更改的更简单方式。[/b]

[size=5][b]为什么使用 UDE?[/b][/size]

[size=4][b]减少整文件冲突[/b][/size]
当两个传统模组替换同一个 USER 文件时,通常一个替换会覆盖另一个——即使它们修改的是完全不同的字段。

使用 UDE,一个模组可以调整某个参数,而另一个模组可以向同一个已加载的资源添加独立条目。兼容的更改可以共存,无需为每一种模组组合单独提供预先合并的 USER。

[b]UDE 减少整文件替换冲突;它并不能消除所有冲突。[/b]修改同一字段、复用条目 ID 或需要不兼容规则的模组仍需要协调。

[size=4][b]不替换原生 USER 文件[/b][/size]
UDE 在内存中修改已加载的数据。它不会重写磁盘上的原始 USER 文件,小幅参数更改也无需附带整个游戏资源。

未更改的字段和记录继续来自游戏实际加载的资源。

[size=4][b]游戏更新后维护更少[/b][/size]
完整的替换 USER 在游戏更新后可能携带过时的表副本。定向的 UDE 配置则描述预期的更改,更容易保留当前游戏数据中无关的新增内容和修复。

[b]配置并非自动免疫更新。[/b]资源路径、类型、字段、ID 或其含义的更改可能需要更新和测试。

[size=4][b]可读的 JSON 而非二进制编辑[/b][/size]
使用普通文本编辑器创建和编辑配置。字段名、操作和值以纯文本形式可见,使更改更易于理解、比较、版本控制和分享。

对于受支持的数据类更改,[b]你的模组只需要 JSON 配置——无需单独的模组专属 DLL。[/b]

[size=4][b]在 USER 初始化之前应用更改[/b][/size]
借助 Class Injector 的早期加载支持,UDE 在原生 USER 数据解码之后、其 onLoad 初始化之前应用配置。后续的原生初始化可以读取修改后的值,而无需在资源已经初始化之后才应用每一项更改。

[size=5][b]主要功能[/b][/size]
[list]
[][b]字段编辑:[/b]为受支持的字段和集合元素赋值。[/]
[][b]数值运算:[/b]加、减、乘、除,以及应用最小值或最大值运算。[/]
[][b]集合扩展:[/b]向受支持的数组和 List 追加条目,并基于标识进行重复处理。[/]
[][b]定向选择:[/b]使用受支持的键或索引定位嵌套字段和记录。[/]
[][b]结构化数据:[/b]填充受支持的强类型对象和资源引用。[/]
[][b]多模组组织:[/b]将每个模组的配置保存在各自的组中。[/]
[][b]定义的加载顺序和来源感知日志:[/b]追踪是哪项配置应用了更改。[/]
[][b]便于脚本编写:[/b]从检查过的数据生成配置,而不是重复二进制编辑器的工作。[/]
[/list][size=5][b]面向玩家[/b][/size]
[b]UDE 本身不会改变游戏玩法。[/b]当另一个模组将其列为前置时安装它,然后安装该模组的 JSON 配置。

[size=4][b]前置要求与安装[/b][/size]
[list=1]
[]安装兼容的 [url=https://github.com/kassent/REClassInjector]RE Class Injector[/url] 运行时。其 hid.dll 需要放在 MonsterHunterWilds.exe 旁边。[/]
[]将 UDE 发布包解压到游戏目录,保留包含的文件夹结构。[/]
[]将 UserDataExtension.dll 和 UserDataExtension.toml 一起放在 reframework/plugins/ 中。[/]
[]将每个依赖模组的 JSON 文件安装到 reframework/data/UserDataExtension/ 下其各自的组中。[/]
[]完全退出并重新启动游戏。[/]
[/list][code]MonsterHunterWilds/
|-- MonsterHunterWilds.exe
|-- hid.dll
|-- reframework/
    |-- plugins/
    |   |-- UserDataExtension.dll
    |   |-- UserDataExtension.toml
    |-- data/
        |-- UserDataExtension/
            |-- 20_ExampleMod/
                |-- 10_changes.json[/code][b]JSON 文件必须直接位于组文件夹内。[/b]UserDataExtension 根目录中的散放 JSON 文件以及更深层子文件夹中的文件不会被自动发现。

如果另一个包已经提供了 hid.dll,在替换该文件之前请检查其兼容性。

[size=4][b]更新与移除配置[/b][/size]
配置在启动时收集。添加、编辑或移除 JSON 文件后需完全重启;重新加载 Lua 并不足够。

要移除某个数据模组,请移除其自身的配置和相关文件,然后重启。当其他模组仍依赖共享运行时时,请保持其安装。

[size=5][b]示例:修改水枪手势[/b][/size]
水枪手势的弹药容量和射程是 PlayerGlobalParam.user 中的字段。

UDE 配置可以更改:
[list]
[]弹药容量:[b]3 发至 255 发[/b]。[/]
[]射程参数:[b]40 米至 80 米[/b]。[/]
[/list]只需声明这两个字段;其余参数来自已加载的资源。255 发的容量并非真正无限弹药。

将此示例保存为:
[code]reframework/data/UserDataExtension/20_WaterGunGesture/10_water_gun.json[/code][code]{
  "format": "UserDataExtension/v1",
  "extensions": [
    {
      "target": "GameDesign/Player/ActionData/Common/GlobalParam/PlayerGlobalParam.user",
      "patches": [
        {
          "app.user_data.PlayerGlobalParam": {
            "_GestureWaterGunMaxAmmo": { "op": "set", "value": 255 },
            "_GestureWaterGun_Range": { "op": "set", "value": 80.0 }
          }
        }
      ]
    }
  ]
}[/code]对于此示例,请禁用任何对同一 PlayerGlobalParam USER 的完整替换,以便编辑以原生游戏数据为基准。

[url=https://github.com/dtlnor/MHWs-in-json/blob/main/natives/STM/GameDesign/Player/ActionData/Common/GlobalParam/PlayerGlobalParam.user.3.json]在 MHWs-in-json 中查看原始参数数据[/url]

[size=5][b]面向模组作者[/b][/size]
当你的模组修改现有 USER 中的少量字段,或需要向共享表添加独立条目时,请使用 UDE。

[b]开发者指南和配置参考:[/b]
[url=https://github.com/kassent/UserDataExtension]GitHub 上的 UserDataExtension——英文和中文指南[/url]

这些指南涵盖配置结构、字段路径、操作、加载顺序、冲突处理、故障排除,以及一个完整的水枪示例。

[size=4][b]从公开 JSON 数据开始[/b][/size]
[url=https://github.com/dtlnor/MHWs-in-json]MHWs-in-json[/url] 提供导出的游戏数据,可帮助你识别资源路径、根类型、字段和现有条目。

找到资源,检查相关字段,然后仅用 UDE 的配置格式表达你预期的更改。开发者指南包含分步查找流程和 Python 配置生成器。

[b]数据库导出是参考数据,不是可直接安装的 UDE 配置。[/b]在编写更改之前,请对照你的目标游戏版本检查数据库。

[size=5][b]兼容性说明[/b][/size]
[list]
[]使用与你的游戏版本匹配的 Class Injector 和 UDE 发布版本。[/]
[]独立的字段更改可以共存;对同一字段的竞争写入仍取决于加载顺序。[/]
[]为每个模组设置唯一的组和文件路径,以免模组管理器替换另一个模组的配置。[/]
[]完整的 USER 替换可能改变 UDE 接收到的基准数据;请显式测试此类组合。[/]
[]UDE 编辑数据。新模型、动画、组件和游戏系统仍需要各自的资源或实现。[/]
[]新的托管类型由 Class Injector 提供,仅靠 UDE JSON 无法定义。[/]
[/list][size=5][b]故障排除与报告[/b][/size]
如果更改没有出现,请完全重启,进入加载目标资源的功能,并检查 logs/UserDataExtension.log 中的配置注册、Applied 条目或错误信息。

报告问题时,请包含你的游戏版本、UDE 和 Class Injector 版本、相关的 JSON 配置和日志、影响同一资源的其他模组,以及复现步骤。