===============================================================================
CBS CRUNCHER v5.5 COMMAND-LINE PACKAGE
===============================================================================

CBS Cruncher v5.5 (c) Max Iwamoto Aug.02. 2026
1996 version (c) Code Busters (Amiga version by Max Iwamoto & Rst7).

This package runs the same compression engine and parameters as the CBS
Cruncher v5 website on Windows, macOS and Linux.


REQUIREMENTS
-------------------------------------------------------------------------------

  Python 3.10 or newer
  Node.js 22 or newer
  Pillow only when loading BMP or PNG files

Install the optional image-import dependencies from this folder:

  python install_dependencies.py

The installer uses the same Python interpreter that launches it and installs
the packages listed in requirements.txt. At present the only extra Python
package is Pillow; raw binary and SC5-SC8 input need no third-party packages.

Node.js executes the bundled compiled compression engine. No TypeScript source
or build tools are required.


WINDOWS INSTALLATION
-------------------------------------------------------------------------------

1. Install the current Node.js LTS release (version 22 or newer).

   Download the Windows Installer (.msi) from:

     https://nodejs.org/en/download

   Or install the LTS release from PowerShell with Windows Package Manager:

     winget install OpenJS.NodeJS.LTS

2. Close and reopen PowerShell, then verify the installation:

     node --version
     npm --version

   The Node.js version must begin with v22 or a higher number.

3. From this extracted CLI folder, install the Python image dependencies:

     python install_dependencies.py

4. Confirm that the CLI starts:

     python cbs_cruncher.py --help

On macOS or Linux, install a Node.js 22-or-newer LTS build using the official
download page or your system's Node.js version manager, then run steps 3 and 4.


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

Run the recommended continuous-data compressors:

  python cbs_cruncher.py game.bin

Run every continuous-data comparison, including CBS v4.3:

  python cbs_cruncher.py game.bin --compressors all

Compress raw Screen 7 data with v5.3, v5.4 and v5.5:

  python cbs_cruncher.py picture.sc7 --mode 7 --width 248 --height 224 --window 2048

SC5, SC6, SC7 and SC8 files may be either raw packed screen bytes or standard
MSX BSAVE files. A valid BSAVE file begins with FEh followed by little-endian
start, end and execution addresses. Its seven-byte container is verified and
removed automatically; only the screen payload is compressed.

Import BMP or PNG pixels and generate one direct-VRAM 16 KB test ROM:

  python cbs_cruncher.py picture.png --mode 7 --delivery direct --rom

Route ordinary continuous data directly into Screen 5 VRAM (42h/4Ah):

  python cbs_cruncher.py tiles.bin --compressors v54,v53 --linear-vram-screen 5 --rom

Also emit every selected linear v5 stream that can safely expand from the
tail of its own RAM destination block (01h/41h/49h/81h):

  python cbs_cruncher.py game.bin --ram-tail

The compressor measures the closest approach between output and unread packed
input. Unsafe candidates remain available as normal RAM streams but are not
written as RAM-tail files.

Generate an ASCII16-X mapped-ROM direct-VRAM test:

  python cbs_cruncher.py picture.bmp --mode 7 --rom --source mapped-rom --mapper ascii16x

Generate a mapped-ROM buffered test with the same mixed mapper decoder:

  python cbs_cruncher.py picture.bmp --mode 7 --delivery buffer --rom --source mapped-rom --mapper ascii16

Place the compressed stream at a specific mapped-ROM page:

  python cbs_cruncher.py picture.sc7 --mode 7 --rom --source mapped-rom --mapper ascii16 --start-bank 3

Page 0 is reserved for the controller and decruncher. Page 1 is the default.

Decompress a stream. The .cb5 extension selects this automatically:

  python cbs_cruncher.py picture.v55.direct.cb5

Show every command-line option:

  python cbs_cruncher.py --help


WHAT THE PACKAGE CAN GENERATE
-------------------------------------------------------------------------------

Continuous data:

  v5.2 compact
  v5.2 near
  v5.3 state flow
  v5.4 adaptive near
  CBS v4.3 comparison
  v5.3/v5.4 linear-VRAM destination for Screen 5-8 tiles, fonts and patterns
  Measured-safe v5.2/v5.3/v5.4 RAM-tail destination files

Screen 5, 6, 7 and 8 data:

  v5.3 image stream
  v5.4 image stream
  v5.5 line-aware image stream
  Buffered or direct-VRAM destination header
  One-image normal ROM test
  One-image mapped-ROM test

Mapped test ROMs reserve page 0 for code, default packed data to page 1 and
use a minimum 128 KB cartridge size for broad emulator compatibility.

Supported mapped-ROM readers:

  ASCII8
  ASCII16
  ASCII16-X
  Konami
  Konami SCC

The website-only multi-image demonstration ROM is intentionally not included.


ASSEMBLY SOURCES
-------------------------------------------------------------------------------

The asm directory contains the complete source set so every command-line output can
be integrated without returning to the website.

Only the source matching each selected continuous compressor is needed for
ordinary RAM output:

  cbs_v43_z80_v01.asm
      Original v4.3 RAM core plus a wrapper for the exact one- or two-block
      .cb5 file generated by the website and this command-line package.

  cbs_v52_z80_v05.asm
      Combined v5.2 compact + near RAM decruncher, including RAM-tail entry.

  cbs_v53_v54_z80_v01.asm
      Combined v5.3 + v5.4 state-flow RAM decruncher, including RAM-tail entry.

Add these two only when Screen 5-8 images are used:

  cbs_v52_screen58_vram_z80_v01.asm
      Universal buffered v5.3 + v5.4 + v5.5 Screen 5-8 decruncher.

  cbs_v5354_screen58_direct_vram_z80_v01.asm
      Universal linear/rectangle direct-VRAM v5.3 + v5.4 + v5.5 Screen 5-8
      decruncher. It accepts 42h/4Ah continuous streams and 45h/4Dh/C5h images.
      Call CBS_INIT_MSX exactly once before the first decrunch. It reads the
      BIOS VDP ports for MSX-standard portability. A separate eight-byte area
      handles tiny matches, leaving the initializer intact across multi-image
      sessions. CBS_INIT_SCREEN is needed only when the Screen mode changes.

For a mapped-ROM project that mixes buffered and direct images, add exactly one
matching mixed mapper source:

  cbs_v535455_screen58_mixed_ascii8_z80.asm
  cbs_v535455_screen58_mixed_ascii16_z80.asm
  cbs_v535455_screen58_mixed_ascii16x_z80.asm
  cbs_v535455_screen58_mixed_konami_z80.asm
  cbs_v535455_screen58_mixed_konami-scc_z80.asm

The smaller direct-only mapper sources remain available when a game never uses
the 24 KB RAM-stage/HMMC route:

  cbs_v535455_screen58_direct_ascii8_z80.asm
  cbs_v535455_screen58_direct_ascii16_z80.asm
  cbs_v535455_screen58_direct_ascii16x_z80.asm
  cbs_v535455_screen58_direct_konami_z80.asm
  cbs_v535455_screen58_direct_konami-scc_z80.asm

Therefore, a real game normally uses only its selected RAM source and one image
or mapper source. The alternatives are included only so the archive covers every
supported configuration.


DIRECTORY CONTENTS
-------------------------------------------------------------------------------

  cbs_cruncher.py       Python command-line frontend
  cbs_engine.mjs        Compiled byte-identical website compressor engine
  README.txt            This file
  asm\                  Z80 integration sources
  decoders\             Assembled binaries used by one-image test ROMs


NOTES
-------------------------------------------------------------------------------

  Search-window values and compressor names match the website.

  BMP and PNG containers are removed before compression. Only prepared packed
  screen bytes are stored in the CB5 stream.

  Valid seven-byte MSX BSAVE headers are also removed automatically from SC5,
  SC6, SC7 and SC8 files. A malformed FEh header is reported as an error.

  Every generated stream is decrunched and compared with its prepared input
  before it is reported as verified.

  The assembly sources are designed to execute from writable RAM, including
  mapped-ROM versions that read packed data from consecutive cartridge banks.

  The supplied direct and mixed image sources keep the one-time VDP-port
  initializer for full MSX compatibility. A project guaranteed to use standard
  98h-9Bh ports may hard-code those operands and omit the initializer.

===============================================================================
CBS Cruncher - original Amiga compressor, 1996
Command-line package - v5.5 release 9
===============================================================================
