CBS Cruncher Python - Command-Line Edition
===========================================

Version: 4.3
Platforms: Windows, macOS and Linux
Requirement: Python 3.9 or newer
Dependencies: None

COMPLETE WEBSITE PACKAGE
------------------------

The package downloaded from maxiwamoto.me also includes:

  decrunchers/cbs-decrunch-ram-readable.asm
      Compact ZX Spectrum/MSX routine for packed data in writable RAM.

  decrunchers/cbs-decrunch-rom-readable.asm
      General MSX routine for packed data in ROM or RAM. The routine itself
      must execute from writable RAM.

This is a command-line port of the CBS Cruncher browser engines:

  * v3   - original 1996 greedy CBS algorithm
  * v4.3 - experimental aligned-cost algorithm with five distance scales

It also decrunches CBS PCK files. The output format is compatible with the
existing ZX Spectrum/MSX RAM-source decruncher and the general MSX ROM-source
decruncher developed during the Romancia translation.


QUICK START
-----------

Compress with v4.3:

  Windows:
    py cbscrunch.py game.bin

  macOS / Linux:
    python3 cbscrunch.py game.bin

The default output is game.pck.

Compress with the original v3 algorithm:

    python cbscrunch.py compress game.bin --engine v3

Create both versions:

    python cbscrunch.py compress game.bin --engine both

This creates:

    game.v3.pck
    game.v43.pck

Decrunch:

    python cbscrunch.py packed.pck

A .PCK extension automatically selects decrunch mode. You can also write:

    python cbscrunch.py decompress packed.pck


OPTIONS
-------

  -e, --engine v3|v4.3|both
      Select the encoder. The default is v4.3.

  -o, --output FILE
      Select the output filename.

      With --engine both, this is treated as the base name and the program adds
      .v3.pck and .v43.pck.

  -t, --threshold NUMBER
      Set the v4.3 minimum length for matches at distance 16384 or farther.
      The default is 4.

  -j, --jobs NUMBER
      Set how many v4.3 distance-scale trials may run in parallel. The default
      uses up to five CPU cores. Use --jobs 1 for sequential operation.

  -f, --force
      Overwrite an existing output file.

  -q, --quiet
      Suppress progress and result details.

  -h, --help
      Show all commands and options.


EXAMPLES
--------

    python cbscrunch.py intro.bin
    python cbscrunch.py intro.bin -e v3 -o intro-v3.pck
    python cbscrunch.py compress intro.bin -e both
    python cbscrunch.py decompress intro.pck -o intro-restored.bin
    python cbscrunch.py INTRO.PCK -o INTRO.BIN


RAM SAFETY
----------

Every compressed result is decrunched and compared byte-for-byte with the
original input.

The tool also reports whether the packed result is safe for the original
end-aligned RAM-source Z80 decrunch layout. If it reports "unsafe", the PCK
stream still round-trips correctly, but it must be read from ROM or from a
separate buffer instead of being placed at the end of its destination buffer.

The general ROM-source decruncher may read packed data from ROM or RAM, but the
decruncher routine itself must execute from writable RAM.

V4.3 evaluates five complete distance-scale trials. On files of 2 KB or larger,
the command-line tool runs these trials in parallel by default to reduce
compression time. This affects speed only; the selected PCK bytes remain
identical to the browser v4.3 encoder.


FORMAT LIMITS
-------------

Minimum input: 5 bytes
Maximum input: 65,280 bytes (0xFF00)

The last four original bytes are stored at the beginning of the PCK file, as in
the original CBS format.
