使用说明

预准备

注

本项目无特殊依赖，只需要正确安装 Python 3 即可。

脚本下载

你可以在 Arcaea-Bundler 项目仓库中直接下载文件 main.py。考虑到易用性，本项目至今为止仍然是单文件脚本。

拆包文件准备

你需要准备内容捆绑包本体 *.cb 与其对应的元数据文件 *.json，后缀名并无特殊作用，仅对人类来说更容易分辨。

若你考虑拆解官方捆绑包，可以通过请求官方 API 的 /<Game API Prefix>/game/content_bundle 端点来获取下载链接，在此不会详细说明。

打包文件准备

打包需要提供一个文件夹，其中的内容和文件夹结构必须与 assets 文件夹一致，必须包含文件 songs/songlist、songs/packlist 和 songs/unlocks，请参考详细说明获取更多信息。

注意

输出文件不要放在输入文件夹内部。打包器会先创建输出文件再遍历输入文件夹，如果输出路径位于输入文件夹下，输出中的 .cb 或 .json 文件可能被再次打进捆绑包。

使用

可以使用 python main.py -h 来查看脚本总说明，使用 python main.py d -h 来查看解包器说明，使用 python main.py b -h 来查看打包器说明。

拆包

使用以下命令

python main.py d -i input.cb -m input.json -o output_dir

可解包一对内容捆绑包和元数据，其中 input.cb 是内容捆绑包的相对路径，input.json 是对应的元数据的相对路径，output_dir 是输出文件夹的相对路径。

对于分块内容捆绑包，例如 input_0.cb、input_1.cb 等，输入时忽略后缀中的 _0、_1 等数字即可，程序会自动识别并处理。当然这些分块包必须在同一文件夹中，并且命名规范，则可同样使用上述命令。

打包

使用以下命令

python main.py b -i input_dir -o ./bundle_output/output_file_name -av app_version -bv bundle_version

可对文件夹 input_dir 进行打包，其中 output_file_name 是输出的内容捆绑包和元数据的文件名（后缀固定），app_version 是指定的客户端版本号，bundle_version 是指定的此捆绑包的版本号。

目前默认使用分块内容捆绑包，生成的内容捆绑包默认命名为 output_file_name_0.cb、output_file_name_1.cb 等，元数据命名为 output_file_name.json。你可以通过设置 -dp 关闭按大小继续切分，此时仍会生成 output_file_name_0.cb，只是所有内容都会写入这一个分块文件。

当你第一次打包一个文件夹的时候，请指定版本信息，用 -av 指定此包用于的客户端版本号，用 -bv 指定包的版本号。第一次之后，程序会在元数据记录 metadata.oldjson 中记录下过去的元数据，下次打包这个文件夹的时候就会自动生成版本号了。同时这意味着，往后对于此文件夹的打包只包含其中的改动项，而非全整合。在非第一次打包且能找到元数据记录的情况下，你可以使用简化命令：

python main.py b -i input_dir -o ./bundle_output/output_file_name

这会自动生成下一个内容捆绑包版本号，并沿用之前的客户端版本号。自动生成规则是：如果上一个版本号不超过三段，则在末尾追加 .1；如果已经超过三段，则最后一段加一。例如 6.14.1 的下一个版本会是 6.14.1.1，6.14.1.1 的下一个版本会是 6.14.1.2。你也可以通过 -av 和 -bv 来覆盖默认的版本信息。另外，-pbv 可以指定元数据中的父版本号，默认为元数据记录中最新的版本号。

你可以通过删除 metadata.oldjson 来重置版本记录，之后的第一次打包会被当做全整合来处理。或者你也可以直接修改 metadata.oldjson 来调整版本记录。再进一步地说，你可以使用 -om 来指定一个元数据记录文件名来进行版本记录。-om 的值不需要带 .oldjson 后缀，例如 -om old/metadata 对应的实际记录文件是 input_dir/old/metadata.oldjson。

打包文件夹等同于 assets 文件夹，必须包含文件 songs/songlist、songs/packlist 和 songs/unlocks。

详细参数说明

python main.py [-h] [-v] [-V] {debundle,d,bundle,b} ...

通用参数

• -h、--help：显示帮助信息，在解包器和打包器中有不同的帮助信息。
• -v、--version：显示版本信息。
• -V、--verbose：启用详细输出模式，显示更多的日志信息。

解包 d

python main.py debundle [-h] -i INPUT -m METADATA [-o OUTPUT] [-V]

• d、debundle：选择解包模式。
• -i、--input：指定输入的内容捆绑包文件路径。如果内容捆绑包分块了，则输入时忽略后缀中的 _0、_1 等数字即可，程序会自动识别并处理。
• -m、--metadata：指定输入的元数据文件路径。
• -o、--output：指定输出的文件夹路径。输出文件夹必须是空的或者不存在的，程序会自动创建。

打包 b

python main.py bundle [-h] -i INPUT [-o OUTPUT] [-m METADATA] [-om OLD_METADATA] [-dp]
                      [--max_part_size MAX_PART_SIZE] [-av APP_VERSION] [-bv BUNDLE_VERSION]
                      [-pbv PREVIOUS_BUNDLE_VERSION] [-V]

• b、bundle：选择打包模式。
• -i、--input：指定输入的文件夹路径，必须包含文件 songs/songlist、songs/packlist 和 songs/unlocks。
• -o、--output：指定输出的内容捆绑包文件名。后缀 .cb 会自动添加且固定。
• -m、--metadata：指定输出的元数据 JSON 文件名，如果没有给出，则与内容捆绑包文件名相同（仅后缀不同）。后缀 .json 会自动添加且固定。
• -om、--old_metadata：指定用于增量更新的元数据记录文件名（路径相对于输入文件夹；后缀 .oldjson 会自动添加且固定）。
• -dp、--disable_parts：禁用按大小分块功能，生成单个分块文件 *_0.cb。
• --max_part_size：指定每个分块捆绑包的最大大小，单位为字节（默认值：104857600 = 100MB）。
• -av、--app_version：指定在元数据中使用的客户端版本号。
• -bv、--bundle_version：指定在元数据中使用的内容捆绑包版本号。
• -pbv、--previous_bundle_version：指定在元数据中使用的前一个内容捆绑包版本号。

常见注意事项

• 解包器只会还原元数据 added 字段中的文件。对于增量包来说，如果你想还原完整资源，需要从父版本资源开始，按版本顺序应用 removed 和 added。
• 打包器不会覆盖已经存在的输出文件。如果同名 .json、*_0.cb 或后续分块文件已经存在，请先移动或改名。
• 第一次打包时如果不指定 -av 和 -bv，元数据里的对应版本字段会为空，无法直接提供给服务端使用。
• -om 指向的记录文件所在文件夹需要已经存在，程序只会创建内容捆绑包和元数据的输出目录。