From dropped file
to working Z80 code.

Use the shortest path that matches the asset

1. Drop the source.BIN, PSG and other arbitrary files enter as continuous bytes. BMP, PNG and SC5–SC8 files enter as native image pixels.
2. Check the interpretation.For images, verify Screen mode, packed bytes per line and line count. For raw BIN input, geometry must exactly match the data size.
3. Select compressors.Recommended runs the active formats. Select all also measures the slower v4.3 historical comparison.
4. Run and choose a result.Every candidate is browser-decrunched and compared byte-for-byte before it is offered.
5. Download data and code.Choose RAM, RAM-tail, buffered VRAM, linear VRAM or direct VRAM, then use the matching generated or reference source.

The file type and the data model are separate choices

Continuous data treats every byte as part of one stream. Use it for code, maps, text, sound, Screens 1–4 data and any image whose rows should be joined without a rectangle rule. Image modes preserve row geometry so v5.5 can test whole-line offsets and the generated decoder can write an exact rectangle.

Native BMP/PNG import removes the file header, palette records and row padding, then converts pixels to the selected MSX packing. A valid seven-byte BSAVE header in SC5–SC8 is detected and removed. Changing Screen 5/7 after importing an image does not silently change the imported packed width.

Smallest verified file wins—within the selected routes

One byte selects format, variant and destination

Linear files use bytes 1–2 for the complete packed-file length in little-endian order. Image destinations 3 and 5 instead use byte 1 for packed NX and byte 2 for NY; zero represents 256. CBS v4.3 is separate and keeps its established 24-byte CB5 container.

Literals establish bytes; matches repeat history

A v5.3/v5.4 stream begins with an interlaced-gamma literal length, followed by those literal bytes. After a literal, one control bit selects a previous-offset match (0) or a new offset (1). After a match, 0 returns to literals and 1 selects another new offset. A previous-offset match saves the complete offset code.

Interlaced gamma value

value = 1
while GET_BIT() == 0:
    value = (value << 1) | GET_BIT()
return value

The general distance stores a complemented negative offset. For a positive look-back distance d:

high      = floor((d - 1) / 128) + 1
low       = (d - 1) % 128
packedLow = (127 - low) << 1 | firstLengthControlBit

v5.3 reserves general offset-high 256 as EOS. v5.4 adds one selector before every new distance: 0 codes near distance 1–15, while 1 uses the complete general representation. v5.5 uses its selector for a whole-line distance or the general compact representation.

Sixty bytes become eleven

The verified v5.4 result for ABC repeated twenty times is:

48 0B 00 71 41 42 43 50 3A AA AC

Control bits, literal bytes and offset data share the payload, so the remaining hex bytes do not each correspond to one complete token. The logical sequence is the reliable way to read it.

The low three bits say what the decoder must do

Normal output or measured destination-tail reuse

The combined v5.3/v5.4 RAM decoder accepts the complete three-byte header at HL:

    LD      HL,PACKED_DATA
    LD      DE,OUTPUT_BUFFER
    CALL    CBS_V5354_RAM_TO_RAM

v5.2 uses CBS_V52_RAM_TO_RAM. CBS v4.3 has its own compatible source because its container and token grammar predate v5.

Generic RAM-tail entry

    LD      HL,PACKED_DATA
    LD      DE,OUTPUT_BLOCK
    LD      BC,UNPACKED_SIZE
    CALL    CBS_V5354_RAM_TAIL

The generated per-file wrapper stores the unpacked size as CBS_FILE_RAM_TAIL, so a game normally supplies only HL and DE. The routine copies the packed file backward with LDDR to the end of the destination block, then performs the usual forward expansion.

This is useful when a title screen can temporarily reuse map RAM, or when packed bytes are copied to the end of a buffer before the original content is needed. The compact decoders intentionally do not carry corrupt-stream bounds checks; use them for trusted game-built assets.

One public interface, several delivery backends

The generated image binary exposes three stable entry points:

    CALL    CBS_INIT_MSX

    LD      A,7
    CALL    CBS_INIT_SCREEN

    LD      HL,PACKED_IMAGE
    LD      DE,(PACKED_X << 8) | Y
    LD      A,VRAM_PAGE << 2
    CALL    CBS_DECRUNCH

For image routes, D is the packed X byte and E is Y, making DE = XY. A bits 3–2 select the VRAM page. HL points to the three-byte CBS header. IX is required only by the buffered route and points to its RAM stage.

Which delivery route should I use?

Initialize the VDP interface once

After copying the decoder into writable RAM, call CBS_INIT_MSX once before displaying the first image. It reads the BIOS VDP data-port values from 0006h and 0007h, then patches every immediate CPU-transfer, status and indirect-command port operand. The same decoder therefore works when a machine's VDP ports differ from the standard 98h–9Bh addresses.

The direct backend uses a dedicated eight-byte RAM buffer for non-overlapping matches of one to eight bytes. Larger matches use HMMM, while long offset-one runs may use HMMV. This buffer is decoder working memory; it does not require another initialization. Call CBS_INIT_SCREEN initially and again whenever the Screen mode changes.

Direct matches are divided at destination-row boundaries, source-row boundaries and overlap limits. The one-to-eight-byte scratch threshold and the 64-byte fast-fill threshold belong to the decoder, not the packed format, so they can be tuned without recompressing the image. A size-focused build restricted to the standard VDP ports may hard-code them and omit CBS_INIT_MSX; the supplied source retains portable initialization.

One mapped decoder handles buffered and direct images

The Screen 5–8 generator compiles exactly one reader for ASCII8, ASCII16, ASCII16-X, Konami or Konami SCC. The game supplies HL as the exact address in the mapper window and BC as the initial bank. The reader detects the active window, patches its fast path and advances banks whenever HL reaches the boundary.

The website demonstration keeps page 0 for startup and code, starts packed assets on page 1 by default, runs the decoder at E000h and mapper control at F500h, and leaves 8000h–DFFFh as a 24 KB buffer. Its multi-screen ROM and export table are visualization tools; the CLI intentionally generates only one-image test ROMs. In a mixed ROM, destination 3 expands into the shared 8000h–DFFFh stage and uploads with HMMC; destination 5 reconstructs directly in VRAM. The same E000h/E003h/E006h decoder entries dispatch both routes. For a fair visual comparison, the demo controller sets the border and backdrop to the darkest available palette colour and clears the complete Screen 5–8 VRAM page with HMMV before each image. It waits for the command to finish while restoring status register 0 between CE checks, allowing normal MSX interrupts, and holds the completed black clear for one video frame before starting the decoder. Buffered output appears only after RAM expansion; direct output can be watched as it is reconstructed in VRAM. The harness also disables sprites after each Screen-mode initialization. This prevents stale sprite attributes from appearing over test images and leaves more VDP time available to the decoder.

The website engine without the browser UI

Requirements: Python 3.10+, Node.js 22+, and Pillow only when importing BMP/PNG.

# Recommended continuous-data compressors
python cbs_cruncher.py game.bin

# Include every comparison, including v4.3
python cbs_cruncher.py game.bin --compressors all

# Build a measured RAM-tail result
python cbs_cruncher.py game.bin --ram-tail

# Screen 7 image and a one-image test ROM
python cbs_cruncher.py picture.png --mode 7 --rom

# Linear Screen 5 VRAM data
python cbs_cruncher.py tiles.bin --linear-vram-screen 5 --rom

# Decrunch an existing CB5 file
python cbs_cruncher.py packed.cb5 --decompress

Run python cbs_cruncher.py --help for the exact mapper, geometry, search-window and output switches in the current package.

Most failures are geometry, route or host limits

Finish missing delivery paths only when they solve a real asset

1. MSX Memory Mapper RAM output.Define the destination-6 contract, selected segment/window parameters and safe crossing between RAM segments.
2. Cartridge-ROM to ordinary RAM.The mixed Screen 5–8 reader is complete; a future compact-data route may reuse it for code, maps or other linear RAM destinations.
3. Optional hybrid image path.Destination 4 remains reserved for row/chunk history or another mixed strategy only if measured game data justifies its code.
4. More game validation.Continue code-size and speed tuning against real maps, tiles, fonts and Screen 5–8 assets without changing verified payloads unnecessarily.

Use the smallest source set your game needs

← Return to the compressor or review the dated project history.