ModSync

ModSync

早期开发阶段 - 此插件正处于非常早期的开发阶段。使用风险自负。开发工作持续进行中——反馈和Bug报告请保持友善！

一款用于 Hytale 专用服务器的服务端Mod管理插件，可让您通过游戏内或控制台命令轻松地添加、安装、更新和移除Mod。

特性

• 多来源支持 - CurseForge（需API密钥）、CFWidget（无需API密钥时的CurseForge回退方案）和 Modtale（Alpha版，需API密钥）。更多来源待添加。
• 一键式安装 - 一次性安装所有管理的Mod
• 完整的Mod生命周期 - 通过命令添加、安装、更新、移除Mod
• 更新管理 - 检查更新、升级单个Mod或一次性升级所有Mod
• 发布通道 - 选择Release、Beta或Alpha版本（全局设置+单个Mod设置）
• 导入现有Mod - 扫描并导入未被管理的Mod，支持自动匹配
• 持久化追踪 - 您的Mod列表会保存下来，在服务器重启后仍然保留。像Mod包一样与朋友分享您的列表！
• 自我升级 - 通过GitHub Releases更新ModSync自身
• 控制台支持 - 所有命令均可从游戏内和服务器控制台执行

快速开始

1. 从此处或 GitHub-Releases 下载 modsync-<version>.jar
2. 放入服务器的 mods/ 文件夹
3. 启动服务器
4. （可选）设置您的 CurseForge API 密钥：/modsync config key curseforge <key>
5. 添加Mod：/modsync add <a href="https://curseforge.com/hytale/mods/example">https://curseforge.com/hytale/mods/example</a>

从 CurseForge Console 或 Modtale API Docs 获取您的API密钥

注意： 没有API密钥时，ModSync会使用CFWidget作为CurseForge URL的回退方案。CFWidget支持基于URL的查询，但不支持基于搜索的导入匹配。 注意： Modtale支持处于实验性/Alpha阶段，需要API密钥。

命令

命令	描述
/modsync add <url>	通过CurseForge URL添加Mod
/modsync list	显示所有已管理Mod及其安装状态
/modsync install	从列表中安装所有Mod
/modsync install <name>	安装指定Mod
/modsync remove <name>	按名称、slug或标识符移除Mod
/modsync remove all	移除所有Mod
/modsync check	检查可用更新
/modsync upgrade	升级所有已安装Mod
/modsync upgrade <name>	升级指定Mod
/modsync scan	列出mods文件夹中未被管理的Mod
/modsync import	自动匹配并导入所有未被管理的Mod
/modsync import <target>	自动匹配并导入指定Mod
/modsync import <target> --url=<url>	通过指定CurseForge URL导入
/modsync config	显示所有配置设置
/modsync config channel <value>	设置默认发布通道
/modsync config key <provider> <key>	设置提供商的API密钥
/modsync config welcome <on/off>	启用或禁用管理员欢迎消息
/modsync setchannel <mod> <channel>	设置单个Mod的发布通道
/modsync selfupgrade	检查ModSync插件更新
/modsync selfupgrade apply	下载并安装最新版ModSync
/modsync status	显示当前配置和版本
/modsync reload	从磁盘重新加载配置

提示： 对于名称中包含空格的Mod，请使用引号：/modsync install "My Mod"

发布通道

控制安装和更新时考虑哪些发布类型：

通道	包含的版本
release	仅稳定版（默认）
beta	Beta版和稳定版
alpha	所有版本，包括Alpha版

/modsync config channel beta       # 设置全局默认值
/modsync setchannel MyMod alpha    # 覆盖指定Mod的通道
/modsync setchannel MyMod default  # 移除覆盖，使用全局设置

自动回退： 如果某个Mod在您配置的通道上没有可用的发布版本（例如，只有Beta版，但您设置的是Release），ModSync会自动回退到Beta版，然后是Alpha版。系统会显示一条警告，告知您使用的是哪种版本类型。

工作原理

安装Mod

/modsync add 和 /modsync install 命令

当您安装一个Mod时，插件会：

1. 通过URL将Mod添加到管理列表中
2. 从Mod源下载Mod并验证其清单
3. 根据CurseForge分类检测插件类型（常规插件或早期插件）
4. 保存到相应文件夹：
   • 常规插件 → mods/
   • 早期/引导插件 → earlyplugins/（可配置）
5. 将Mod注册到已安装Mod注册表中

注意： 需要重启服务器才能加载新安装的Mod。

移除Mod

/modsync remove 命令

当您移除一个Mod时，插件会：

1. 如果Mod当前已加载，则卸载它
2. 尝试删除Mod文件
3. 如果文件被锁定（Windows），则将其排入下次重启时的删除队列。安装引导插件以在重启时处理删除操作。

注意： 如果文件被锁定（Windows），会将其排入下次重启时的删除队列。引导插件会在服务器加载Mod之前处理排队的删除操作。

检查和安装升级

/modsync check 命令：

显示哪些Mod有可用更新，并附上版本对比（例如 1.0.1 -> 1.0.2）。

/modsync upgrade 命令：

升级所有已安装的Mod或指定Mod。

注意： 需要重启服务器才能加载升级后的Mod。

导入现有Mod

使用 /modsync scan 查找未被管理的Mod，然后使用 /modsync import 通过自动匹配将其纳入ModSync的管理之下。

注意： 导入和扫描功能目前需要CurseForge API密钥才能进行自动匹配。CFWidget和Modtale不支持基于搜索的导入。

引导插件（可选）

在Windows上，JAR文件在被JVM加载时会被锁定。这会阻止在升级过程中删除旧的Mod版本。

引导插件是一个早期插件，它在常规插件加载之前运行：

1. 读取 pending_deletions.json
2. 在文件被加载之前删除排队的文件
3. 然后继续常规插件加载

安装（仅在您遇到删除问题时）：

1. 从 modsync-bootstrap 下载
2. 放入 earlyplugins/ 文件夹
3. 使用 --early-plugins --accept-early-plugins 标志启动服务器

注意： 在Linux专用服务器上，文件锁定通常不是问题，通常不需要引导插件。

文件位置

所有数据存储在 mods/Onyxmoon_ModSync/ 中：

• config.json - API密钥和设置
• mods.json - 您精选的Mod列表（可在服务器之间共享）
• mods.lock.json - 安装状态（特定于机器，不可共享）
• pending_deletions.json - 排入重启时删除队列的文件（仅在存在被锁定文件且需要引导插件时）

重要说明

• 需要服务器重启 - 目前，无法通过Mod API触发服务器重启。安装、升级或移除Mod后，您必须手动重启服务器。如果您服务器配置了自动重启，可以使用 /stop 命令来触发重启。
• Mod分发 - 只有在作者在其CurseForge项目设置中启用了"允许Mod分发"时，才能下载Mod。
• 提供商回退 - 如果没有CurseForge API密钥，ModSync会使用CFWidget，它支持URL查询但不支持搜索。
• 文件锁定（Windows）：JAR文件在加载时会被锁定。引导插件会在重启时处理删除操作。
• 支持的来源：支持CurseForge、Modtale（Alpha版）和CFWidget。CFWidget使用公共小部件API，不需要API密钥，但不支持基于搜索的导入。
• 管理员欢迎消息 - 通过 config.json 中的 disableAdminWelcomeMessage: true 禁用管理员欢迎消息。

支持

• GitHub Issues
• 更新日志