Ark-Unpacker: batch Arknights AssetBundle extraction in Python

Getting the AssetBundles out of an Arknights install

Ark-Unpacker talks to no game server and downloads nothing for you. It works on AssetBundle files that already sit on your disk. Arknights is built on Unity, so its assets ship inside AssetBundle containers with a .ab suffix, and in a few cases a .bin suffix. On Android those containers come from two separate places. The install package supplies one part: you download the .apk from the official site, rename it to .zip, open it with an archive viewer, and extract the assets/AB/Android folder. The hot update supplies the other part, namely the Bundles folder on the device under Android/data/com.hypergryph.arknights/files/Bundles. You copy that folder to a computer over a USB cable and rename it Android(2). Emulator users can use the file sharing feature to copy it instead, and the README mentions ADB as another route. You then copy the contents of Android(2) into Android and let same-named files be overwritten, which is what produces a complete set. The PC route runs through the Hypergryph launcher: install the PC client, run the game, let the in-game hot update finish, then open the game install path. Initial resources sit in StreamingAssets/AB/Windows and updated resources in PersistentData/Bundles. A document at docs/zh/AssetsGuide.md lists what each subdirectory holds, though the README warns that this listing may not be current.

Version-specific decoding and the six exported asset types

Game versions v2.5.04 and above use a special decompression algorithm, and the tool applies that path rather than handing you a generic container reader. Two further distinctions matter when you look through the output. Spine model files are separated by role, covering base construction staff, dynamic portraits and combat characters, so you can find the animated character set without filtering every file yourself. Extracted files can also be placed into directories named after the source AB file, which preserves the grouping the game shipped with. The export type table is small and explicit. Sprite and Texture2D both become PNG images, AudioClip becomes a WAV file, Mesh becomes an OBJ file, and TypeTree becomes a JSON file. TextAsset is the loose end, because the table leaves its export format unspecified, so you cannot learn from the table how a text or byte payload lands on disk. The repository also points at a separate document, docs/zh/TextAssetsDecoding.md, for the decoding principles behind the data files, and the changelog lives in CHANGELOG.md.

Two ways in: an interactive menu beside the executable, or a scripted mode

The simplest documented usage is to place the folders you want to unpack next to the program file, launch it, and follow the prompts of the interactive command line interface. The example layout in the README holds an Android folder, a chararts folder and ArkUnpacker.exe, and the note beside it points out that unpacking the entire directory takes a long time while chararts can be unpacked selectively. The README also documents a direct command line path for users who prefer scripting, and states the rule that decides between the two: a command without a mode argument starts the interactive interface instead. Two files appear in the working directory once the program runs, namely the configuration file ArkUnpackerConfig.json and the log file ArkUnpackerLogs.log. Field descriptions for the configuration live in docs/zh/ConfigFile.md. For unattended use this matters, since the configuration and log are written into the working directory on each start and the destination directory can be recreated rather than merged into.

The argparse surface: five working modes and per-type export flags

The command line interface of the tool is documented as a standard argparse block, and the usage header shows the whole option space at a glance. Five mode values are available, and the help text names each one, so the mapping from letter to purpose is explicit rather than folklore. There is also a grouping switch that writes files into separate directories named by their source AB file, and flags that let you choose which asset categories to export in resolve ab mode, covering images, text or binary files, audio, spine asset files, mesh resources and typetree JSON files. The two USM switches, --no-video and --no-audio, let you skip one stream when extracting cutscene media from Criware USM files. Logging runs from none at level 0 through debug at level 4. The -d switch deletes an existing destination directory first, which is convenient for repeatable jobs and destructive for anyone who points -o at the wrong folder.

usage: ArkUnpacker [-h] [-v] [-m {ab,cb,fb,sp,cu}] [-i INPUT] [-o OUTPUT] [-d]
                   [--image] [--text] [--audio] [--spine] [--mesh] [--typetree] [-g]
                   [--no-video] [--no-audio] [-l {0,1,2,3,4}]

  -m {ab,cb,fb,sp,cu}, --mode {ab,cb,fb,sp,cu}
                        working mode, ab=resolve-ab, cb=combine-image, fb=decode-flatbuffers, sp=resolve-spine, cu=resolve-usm
  -i INPUT, --input INPUT
                        source file or directory path
  -o OUTPUT, --output OUTPUT
                        destination directory path
  -d, -delete           delete the existed destination directory first

Channel merging, FlatBuffers decoding, and where the output lands

Arknights ships many images as an RGB channel image paired with a separate Alpha channel image, so a second mode exists purely to merge those pairs. The custom image merge mode takes a path, combines the RGB and Alpha images found there, and writes the merged result to a directory you choose. The one-click mode does both halves in one pass: it unpacks the files in the program directory and merges the images, exporting unpacked files to an Unpacked_xxxx folder and merged images to a Combined_xxxx folder. The FlatBuffers decode mode is the third of the data oriented modes, decoding data files in a given directory and exporting the decoded output elsewhere. The Spine mode is the fourth, unpacking assets and exporting the Spine animation character models it finds. The fifth handles Criware USM files, which usually hold cutscene animation, and extracts the video and audio streams from them. The README points readers to a separate document for the FlatBuffers decoding principles, to docs/zh/ArkModelsRepoKit.md for the ArkModels extraction and sorting feature, and to docs/zh/ArkVoiceRepoKit.md for the ArkVoice tool, both of which it labels as custom features.

Where the one-click mode misleads you, and what the hardware demands

Three constraints are easy to trip over. First, the one-click mode does not unpack AB files sitting directly in the program directory, only files inside subfolders, so an AB file dropped in the wrong place is silently skipped. Second, the README warns against pointing that same one-click mode at a complete game resource directory, because it takes a long time and consumes a lot of system resources, and recommends working on selected folders or using the custom modes instead. Third, the multiprocessing strategy adapts itself to the number of CPU cores, and the tool asks for a machine with decent CPU and disk performance, so a slow machine produces a slow run rather than a failure. The one-click path also writes into folders named Unpacked_xxxx and Combined_xxxx inside the working directory, which makes repeated runs accumulate separate output trees. On Windows there are quirks worth knowing: clicking the console window with the left button enters text selection mode and pauses the program, clicking with the right button pastes text or leaves that mode, and dropping a file into the window pastes its path.

A hand-rolled script against the same dependency set

The dependency list in pyproject.toml names the pieces a custom pipeline would need: UnityPy for Unity asset containers, spine-asset for Spine data, flatbuffers for the binary schema format, Pillow and numpy for image work, psutil for system inspection, pycryptodome for the cryptographic parts, bson, pydub-ng for audio handling, rich for the console interface and wannacri for Criware containers. Ark-Unpacker is, in effect, that script with the game specific knowledge already wired in: the special decompression path for versions v2.5.04 and above, the FlatBuffers schemas checked into src/fbs/CN, the distinction between the three kinds of Spine character models, and the output conventions. The practical difference is not capability but effort and upkeep. A team that already ships its own UnityPy pipeline can skip the executable entirely and keep control of naming and retention, at the cost of reimplementing the parts tied to how this one game packages its assets. The upstream tool wins when you want the game specific behaviour without maintaining it, and loses when you need your own output layout, your own scheduling and a toolchain that is not waiting to be retired.

requires-python = ">=3.10,<3.13"
dependencies = [
    "bson (~=0.5)",
    "flatbuffers (~=25.12)",
    "numpy (~=2.2)",
    "Pillow (~=11.3)",
    "psutil (~=7.2)",
    "pycryptodome (~=3.22)",
    "pydub-ng (~=0.1)",
    "rich (~=15.0)",
    "spine-asset (~=1.1)",
    "UnityPy (~=1.25)",
    "wannacri (~=0.3)"
]

ArkStudio is the destination, and BSD-3-Clause is the licence

The README opens with a notice about the end of updates. The project is being upgraded and migrated to ArkStudio, which the author describes as an integrated asset management platform for Arknights still in development, and once it is finished the current project will stop updating because its lifecycle ends. That notice sits above the feature list, which tells you how to read the release history: v5.0.1 on 2026-06-16, v5.1.0 on 2026-08-02 and v5.2.0 on 2026-09-29, with the last push on 2026-09-29 also matching the newest release. The licence is BSD-3-Clause, and the README states that anyone may use it. That is a permissive licence, so using the tool internally, or building on the code, carries no copyleft obligation to publish changes, though the licence file itself governs the detail. The source tree is a Poetry project with package-mode disabled, an entry point at Main.py and a Build.py script, with pyinstaller pinned in the development dependencies for the Windows executable. Contributor guidance is in docs/zh/ForDevelopers.md.

Editorial conclusion

Ark-Unpacker suits Windows users who want to inspect Arknights assets they already own and who can accept a project that is being folded into ArkStudio. It does not suit Linux or macOS users expecting a working release binary, nor anyone who needs a stable long term toolchain for a shipping pipeline, because the README states the current project will stop updating once ArkStudio is finished. Before adopting it, check that your Python version falls inside the >=3.10,<3.13 range in pyproject.toml, confirm the release build runs on 64-bit Windows, and read the CHANGELOG.md to see what changed in the v5.2.0 release dated 2026-09-29, which was also the last push.

Frequently asked questions

Official sources

1. isHarryh/Ark-Unpacker on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases