Skip to main content

Instruction

Lost-MSth6/8/26About 4 min

Preparation

Note

This project has no special dependencies. You only need to install Python 3 correctly.

Script Download

You can directly download the main.py file from the Arcaea-Bundler project repository. For ease of use, this project has remained a single-file script so far.

Files for Debundling

You need to prepare the content bundle file *.cb itself and its corresponding metadata file *.json. The suffixes have no special effect and are only easier for humans to distinguish.

If you want to debundle official content bundles, you can obtain download links by requesting the /<Game API Prefix>/game/content_bundle endpoint of the official API. This will not be described in detail here.

Files for Bundling

Bundling requires a folder whose content and folder structure must be consistent with the assets folder. It must contain songs/songlist, songs/packlist, and songs/unlocks. See the detailed description for more information.

Warning

Do not place the output files inside the input folder. The bundler creates output files before traversing the input folder. If the output path is inside the input folder, the generated .cb or .json files may be bundled again.

Usage

You can use python main.py -h to view the general script help, python main.py d -h to view debundler help, and python main.py b -h to view bundler help.

Debundling

Use the following command:

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

This debundles a pair of content bundle and metadata. input.cb is the relative path of the content bundle, input.json is the relative path of the corresponding metadata, and output_dir is the relative path of the output folder.

For multipart content bundles, such as input_0.cb, input_1.cb, and so on, omit the _0, _1, and other numeric suffixes in the input. The program will automatically recognize and process them. Of course, these part files must be in the same folder and follow the naming rule.

Bundling

Use the following command:

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

This bundles the folder input_dir. output_file_name is the file name of the output content bundle and metadata with fixed suffixes, app_version is the specified client version number, and bundle_version is the version number of this content bundle.

Multipart content bundles are used by default. The generated content bundles are named output_file_name_0.cb, output_file_name_1.cb, and so on by default, and the metadata is named output_file_name.json. You can set -dp to disable further size-based splitting. In that case, output_file_name_0.cb is still generated, but all content is written into this single part file.

When you bundle a folder for the first time, specify version information. Use -av to specify the client version number for this package, and -bv to specify the package version number. After the first time, the program records past metadata in the old metadata file metadata.oldjson, and the next bundle of this folder will automatically generate the version number. This also means that later bundles of this folder only include changed items instead of a full integration. When it is not the first bundle and old metadata can be found, you can use the simplified command:

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

This automatically generates the next content bundle version number and reuses the previous client version number. The automatic rule is: if the previous version number has no more than three segments, append .1; if it already has more than three segments, increment the last segment by one. For example, the next version of 6.14.1 will be 6.14.1.1, and the next version of 6.14.1.1 will be 6.14.1.2. You can also use -av and -bv to override the default version information. In addition, -pbv can specify the parent version number in the metadata, and defaults to the latest version number in the old metadata.

You can delete metadata.oldjson to reset the version record. After that, the next first bundle will be treated as a full integration. You can also directly modify metadata.oldjson to adjust the version record. Furthermore, you can use -om to specify a file name for old metadata. The value of -om does not need the .oldjson suffix. For example, -om old/metadata corresponds to the actual record file input_dir/old/metadata.oldjson.

The bundle input folder is equivalent to the assets folder and must contain songs/songlist, songs/packlist, and songs/unlocks.

Detailed Parameter Description

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

Common Parameters

  • -h, --help: displays help information. The debundler and bundler have different help information.
  • -v, --version: displays version information.
  • -V, --verbose: enables verbose output mode and displays more logs.

Debundling d

python main.py debundle [-h] -i INPUT -m METADATA [-o OUTPUT] [-V]
  • d, debundle: selects debundling mode.
  • -i, --input: specifies the input content bundle file path. If the content bundle is split into parts, omit the _0, _1, and other numeric suffixes in the input. The program will automatically recognize and process them.
  • -m, --metadata: specifies the input metadata file path.
  • -o, --output: specifies the output folder path. The output folder must be empty or absent, and the program will create it automatically.

Bundling 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: selects bundling mode.
  • -i, --input: specifies the input folder path, which must contain songs/songlist, songs/packlist, and songs/unlocks.
  • -o, --output: specifies the output content bundle file name. The .cb suffix will be automatically added and is fixed.
  • -m, --metadata: specifies the output metadata JSON file name. If not given, it will have the same name as the content bundle file, with only the suffix changed. The .json suffix will be automatically added and is fixed.
  • -om, --old_metadata: specifies the old metadata file name used for incremental updates. The path is relative to the input folder, and the .oldjson suffix will be automatically added and is fixed.
  • -dp, --disable_parts: disables size-based multipart splitting and generates a single part file *_0.cb.
  • --max_part_size: specifies the maximum size of each content bundle part in bytes. The default is 104857600, which is 100 MB.
  • -av, --app_version: specifies the client version number used in metadata.
  • -bv, --bundle_version: specifies the content bundle version number used in metadata.
  • -pbv, --previous_bundle_version: specifies the previous content bundle version number used in metadata.

Common Notes

  • The debundler only restores files in the added field of metadata. For an incremental package, if you want to restore complete resources, start from the parent version resources and apply removed and added in version order.
  • The bundler will not overwrite existing output files. If a .json, *_0.cb, or later part file with the same name already exists, move or rename it first.
  • If -av and -bv are not specified during the first bundle, the corresponding version fields in metadata will be empty and cannot be directly provided to the server.
  • The folder containing the record file specified by -om needs to already exist. The program only creates output directories for content bundles and metadata.
Copyright © 2026 Lost-MSth