Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


AC3ES Tools

This is a collection of tools for manipulate games files for the game Ace Combat 3.

You can edit bin containers, TIM files and ACE.BPB/BPH and has a full working Ulz compressor/decompressor!


Now you need Python >= 3.4


The tool has two sub commands, the ulz command for compress/decompress files and info for get details about the ulz and the known iso or bpb of the game.

Ulz command ulz [-h] [--compress FILE] [--ulz-type {0,2}]
                 [--level {1,2,4,8}] [--store-only] [--like-file LIKE_FILE]
                 [--decompress ULZ] [--output-file FILE] [--parents]

optional arguments:
  -h, --help            show this help message and exit
  --compress FILE, -c FILE
                        Compress the file in ulz
  --decompress ULZ, -d ULZ
                        decompress the file in the current directory
  --output-file FILE, -f FILE
                        override output filename
  --parents, -p         Create directories for destination files if they don't
  --keep, -k            prompt before every removal or destructive change

  --ulz-type {0,2}      Define the ulz version to use
  --level {1,2,4,8}, -l {1,2,4,8}
                        Compression levels 1/2/4/8 uses a search buffer
                        1024/2048/4096/8192 bytes long.
  --store-only, -s      Store data on ulz file, needs anyway a compression
  --like-file LIKE_FILE
                        Get compression parameters from file

Bin command bin [-h] [--split BIN_FILE] [--out-directory DIRECTORY]
                    [--out-list DIRECTORY] [--merge FILE_LIST|DIR]
                    [--out-bin FILE_BIN] [--verbose]

optional arguments:
  -h, --help            show this help message and exit
  --split BIN_FILE, -s BIN_FILE
                        Split a bin container
                        Reconstruct a bin file starting from a component list
                        or a directory

bin split:
  --out-directory DIRECTORY, -d DIRECTORY
                        Output directory where to store the bin's components
  --out-list DIRECTORY, -f DIRECTORY
                        Save a components' list to a txt
  --out-bin FILE_BIN, -b FILE_BIN
                        Output bin filename
  --verbose, -v         Print more information while merges

Info command info [-h] FILES [FILES ...]

positional arguments:
  FILES       One or more file to get info

optional arguments:
  -h, --help  show this help message and exit

TIM editing command tim [-h] --source-tim TIM_FILE [--copy-header] [--copy-clut]
                    [--copy-vram] [--set-vram-x X] [--set-vram-y Y]
                    FILES [FILES ...]

positional arguments:
  FILES                 Apply the changes to one or more TIM files

optional arguments:
  -h, --help            show this help message and exit
  --source-tim TIM_FILE, -s TIM_FILE
                        Source TIM
  --copy-header         Copy the entire header data from source
  --copy-clut           Copy CLUT data from source
  --copy-vram           Copy V-RAM coordinates
  --set-vram-x X        Set V-RAM coordinate X
  --set-vram-y Y        Set V-RAM coordinate Y

BPB unpack/repack command bpb [-h] [--unpack DIRECTORY | --pack DIRECTORY]
                    [--bpb ACE.BPB] [--bph ACE.BPH]

optional arguments:
  -h, --help            show this help message and exit
                        Unpack ACE.BPB/BPH to the given directory
                        Pack ACE.BPB and create ACE.BPH from a given directory
  --bpb ACE.BPB         Path for ACE.BPB
  --bph ACE.BPH         Path for ACE.BPH


Compress an image and put the output into the same directory ulz --compress image.tim --ulz-type=2 --level=1

or define another destination ulz --compress jap_0002.tim --ulz-type=2 --level=1 --output-file=mycompress.ulz

Get what parameters use from the original file info BPB/0386/0001/0000.ulz

Work on bin containers bin --split=BPB/0114/0007.bin --out-directory=splitted/0007 --out-list=splitted/0007.txt bin --merge=splitted/0007.txt --out-bin=mod_0007.bin

More parameters are available, just type help for the sub command ulz --help info --help bin --help tim --help bpb --help

Ulz compression type 0 vs type 2

They are basically the same, ulz 0 is meant to decompress faster than ulz 2. In reality doesn't matter, the difference are few lines of ASM inside the ACE.BIN executable.

Ulz type 0 produces files at least 4 bytes bigger than ulz 2, because the compressed data is store a bit different regardless the compression ratio. Read the source code for more details.

They are both based on LZ77 and I compress using the same algorithm. I don't know why they used two nearly identical formats.


2.3.2 Fix copy-header offsets

2.3.1 Add copy-header switch for TIM

2.3 Unpack/repack ACE.BPB and ACE.BPH

2.2 Edit TIM header and CLUT data

2.1 Split and merge bin containers

2.0 Ulz type 0 compression is finally working


  • Orientalcomputer_1
  • IlDucci


Gianluigi "Infrid" Cusimano <>


Compress and decompress ULZ files for Ace Combat 3 game




No packages published