Minecraft 简易补丁工具

一个用 Rust 编写的 Minecraft 模组同步工具，可以根据配置文件自动下载缺失 Minecraft 模组、禁用/删除多余的文件。 本质上是一个文件同步工具。

功能特性

• 配置文件解析：支持 TOML 格式的配置文件，定义模组下载规则
• 锚点搜索：智能搜索锚点文件/文件夹以定位工作目录
• 多种匹配策略：支持多种文件匹配方式：文件名、mod_id/version、正则表达式
• JAR 文件解析：能读取 JAR 文件内部的 META-INF/mods.toml 以提取模组信息
• 镜像模式：可选择性地删除或禁用不在配置列表中的文件
• .disabled 文件：自动检测并恢复被禁用的模组文件
• 配置文件生成：根据规则自动生成配置文件
• SHA256计算：通过命令行参数调用计算文件SHA256功能
• HTTP/3 QUIC 支持：可选择使用 QUIC 协议进行更快的下载
• 自更新功能：支持程序自动更新，通过配置文件中的 self_update_url 字段指定更新源
• 进度条显示：批量下载时显示多进度条，实时展示进度
• SHA256校验：支持文件完整性校验，确保下载文件的安全性
• 多线程：多线程计算 SHA256 和多线程下载，很快。

Why is this？

目前拥有的更新方案，有着以下几个不便之处：

1. 更新选择不够灵活

   • 对于 rsync、robocopy 等同步方案，往往只能选中整个文件夹。开启镜像模式后，目标文件夹中不符合源文件夹的文件将被剔除。但有时，我们不需- 对整个文件夹进行操作。如 config 文件夹中，只需要对某个或某些特定的文件进行更新。

   • 对于 HMCL 提供的整合包更新功能，需要在整合包发布的时候就写好相关的数据，URL不可变，并非即插即用。

2. 对客户端有要求，可能依赖运行环境

   • 用户的运行环境上，可能缺少各种运行库，如 git python powershell 5/7

     用 Java 对于 Minecraft 用户来说可能是更好的选择，可惜我不会 Java（哭

3. 对服务端有要求，可能需要额外架设服务

本程序：

• 使用 Rust 编写，静态链接依赖库，无需外置依赖
• 即插即用，只需将二进制文件和 toml 文件发布给用户
• 服务端仅需支持 HTTP 文件下载服务
• 支持在 toml 文件中预设的“文件组”中进行文件验证、文件禁用或删除
• 支持批量生成文件的 sha256，甚至 jar 文件的 mod-id 和 mod-version
• 支持为每个文件设置下载 URL
• 支持 HTTP/3 QUIC UDP 协议作为客户端

  主要用于特殊的网络环境……

使用方法

使用源码运行：

cargo run
# 如果你需要附加额外参数
cargo run -- <在这里附加参数>

使用二进制文件运行：

# 直接双击启动会加载同目录下的 mc_simple_patcher.toml
mc_simple_patcher.exe
# 使用debug参数输出更多信息
mc_simple_patcher.exe -d

CLI Usage

A simple file sync&patch tool, with addtional support to Minecraft mod

Usage: mc_simple_patcher.exe [OPTIONS] [COMMAND]

Commands:
  generate  从TOML文件生成配置文件
  help      Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>  配置文件路径 [default: mc_simple_patcher.toml]
  -d, --debug            启用调试模式
  -s, --sha256 <FILE>    SHA256模式：计算指定文件的SHA256哈希值
  -q, --quiet            安静模式，不输出log、不提示点击继续
  -h, --help             Print help
  -V, --version          Print version

其中，-c, --config <CONFIG> 参数可以接受 HTTP(S) 网络地址。若以 http(s):// 开头，程序将优先进行 toml 下载。

典型使用流程

TODO

配置

程序基本逻辑

在配置文件中，需要更新的文件规则被分为若干组（表数组 groups）。对于每个组，程序进行逻辑：

1. 定位 anchor 文件，以此为基准。当玩家将本程序放置在 folder/.minecraft/versions/folder/mods 中的任意文件夹时，有优化搜索算法。因此，建议玩家将此程序放置在 mods 目录、其父目录，或和启动器放置在一起。
2. 相对于 anchor 目录，定位工作目录 root，在此目录下搜索文件。
3. 如果 recursive = true，文件搜索范围将扩大到子目录。
4. 开始搜索文件，将记录所有符合 pattern 的文件。
5. 对于每个 groups.files：
   1. 如果记录的文件中没有匹配到的文件，则该文件需要获取。
   2. 如果有 <filename>.disabled，且满足条件，就去掉扩展名，恢复该文件。
   3. 否则，通过 url 下载文件。
6. 检查完成后，对于记录中未能匹配到的文件，如果 mirror = true，则需要对该文件进行处理：
   1. 如果 delete = false，则在该文件名后增加 .disabled。
   2. 否则，删除该文件。

下载逻辑

对于 metadata、self_update_url 下载操作，将检查服务端的 <filename>.sha256：

• 对于 metadata（也就是 toml 文件的 url 下载地址）
  • 如果服务端没有 <filename>.sha256，则始终下载。
  • 如果服务端有，则首先计算本地 sha256。如果和服务端比对一致，则跳过下载。
• 对于 self_update_url（也就是程序自身的 exe 文件的 url 下载地址）
  • 如果服务端没有 <filename>.sha256，则始终跳过下载。
  • 如果服务端有，则首先计算本地 sha256。
    • 如果和服务端比对一致，则跳过下载。
    • 如果和服务端不一致，则下载到临时文件夹，然后结束程序、替换本体。

对于所有下载操作：

• 如果服务端有 <filename>.gz，则下载该文件，之后解压覆盖本地的 <filename>
• 如果服务端没有 gz 文件，则正常下载。

配置文件生成 - 子命令 generate

主要用于从现有的 mods 文件夹生成配置文件列表，批量生成 name mod_id sha256 等参数。

指定输入的TOML文件，根据其中的规则扫描目录并生成配置文件，生成的配置将保存为 <input>-generated.toml

mc_simple_patcher.exe generate <input.toml>

预计行为是 [[generate]] 之外的内容将被原样保留到生成出来的 <input>-generated.toml 中。

关于生成配置如何写，请查阅 示例文件 generate.toml

生成结束后，将在同目录额外生成该 toml 的 .sha256文件 和自身可执行文件的 .sha256文件。

配置文件格式

关于如何书写配置文件，请查阅 示例文件 example.toml

网络配置

使用 [network] 部分来配置网络相关选项：

# [可选] 整个 network 键都是可选的
[network]
# 是否强制切换到 HTTP/3 quic，只走 UDP 协议，默认为 false
quic = false
# 是否忽略证书错误，默认为 false
ignore_invalid_cert = true
# 下载超时时间，默认 15 秒
timeout = 10
# 下载遇到错误时重试次数，默认 3 次
retry = 5

• quic: 启用 HTTP/3 协议进行下载（默认为 false）
• ignore_invalid_cert: 忽略 SSL 证书错误（默认为 true）

自更新配置

使用 self_update_url 字段来配置程序自更新：

[self_update]
# 自更新地址，如果指定，程序启动时会检查 <URL>.sha256
# 如果 sha256 和自身不同则开始更新自身
# 下载时将总是检查 <filename>.<ext>.gz 文件是否存在，如果存在则优先下载
url = "http://example.com/mc_simple_patcher.exe"

配置格式适用版本号 >= 0.2.5 && version >= 1

当配置了此字段后，程序启动时会自动检查并下载新版本，替换当前可执行文件。

# [可选] 使用补丁方式自更新
[[self_update.patches]]
# <必须> BSDIFF4-format 补丁 URL 路径
url_patch = "https://example.com/mc_simple_patcher.exe.v0.2.5.patch"
# <必须> 源文件的 SHA256 哈希值（64 字符十六进制字符串）
sha256_src = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
# [可选] 补丁后是否保留源文件。默认为 true
# 如果保留，则其将被重命名为 <filename>.backup
keep_src = true

当配置了此字段后，程序启动时会自动检查：

1. 如果当前文件的 sha256 == sha256_src，则下载该补丁。
2. 下载补丁之后，对当前文件进行 bsdiff patch

Bsdiff Patch 功能 v0.2.7 后可用。

预计典型游戏文件结构

FOLDER/
├── ...
├── Plain Craft Launcher 2.exe  # PCL 启动器
└── .minecraft/
    ├── ...
    └── versions/
        ├── Minecraft version 1
        |   ├── ...
        |   ├── Minecraft version 1.jar
        |   ├── config/
        |   └── mods/
        |       ├── ...
        |       └── *.jar
        ├── MC ver.2
        |   ├── ...
        |   ├── MC ver.2.jar
        |   ├── config/
        |   └── mods/
        |       ├── ...
        |       └── *.jar
        └── ...
    

后言

十分感谢您能看到这里！我是 Rust 初学者，写这个耗费了我很多的精力。AI也帮了我很多，但我也坚持对代码进行检查、重构和优化，确保我的代码质量不过低。

如果各位觉得我的项目有用，希望能点个 Star，如果有任何问题、bug、反馈、希望新增的feature，或者是针对于代码风格、程序结构、流程优化的建议，也非常高兴如果您能提起issue！再次感谢！