From dropped file
to working Z80 code.

Start with v5.5 and an 8 KB reusable buffer

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.

Image decruncher size at a glance

Illusion City Screen 5 example

The 256×192 IC14_v02.bmp screen contains 24,576 raw bytes. Every buffer choice below uses the same 476-byte C4h decoder and passed exact VRAM verification on the Panasonic FS-A1WSX openMSX profile. The recommended 8 KB route produced 5,201 packed bytes in 1.640 seconds.

The comparable v5.5 Direct stream uses 4,915 packed bytes and a 1,398-byte decoder but takes 3.721 seconds. There is no universal winner: choose 1–4 KB when RAM is scarce or speed dominates, 8 KB for the usual balance, and 16 KB when the smallest packed file matters most. The selected window may differ for every asset in the same game.

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.

Choose the best traversal, then rebuild repeated rectangles in VRAM

v5.6 treats a Screen image as two-dimensional data. The compressor can test horizontal rows in both directions and vertical columns in both directions, then keeps the smallest permitted result. You may restrict the search to Horizontal or Vertical when build time matters. The chosen base uses the proven v5.5 line-aware grammar; CBM1 then appends reconstruction commands for exact, horizontally mirrored, vertically mirrored and two-axis-mirrored 8-pixel-aligned rectangles.

Direct and rolling builds use the same call

    CALL    CBS_INIT_MSX

    LD      A,5
    CALL    CBS_INIT_SCREEN

    LD      HL,PACKED_CBM1
    LD      DE,0000h            ; packed X=0, Y=0
    XOR     A                   ; destination page 0
    CALL    CBS_DECRUNCH

The current Direct decoder is 2,078 bytes; each selectable rolling build is 2,639 bytes plus its caller-reserved 1, 2, 4, 8 or 16 KB RAM window. On a complete 32 KB tile-image benchmark, Direct restored exact VRAM in 7.831 seconds on the Panasonic FS-A1WSX openMSX profile and was faster than the measured v5.4 and v5.5 Direct routes. Rolling delivery currently benefits horizontal streams most; vertical streams should be compared against Direct before committing RAM.

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?

Reuse a selected v5.5 buffer for a larger image

Choose the RAM budget when compressing. The compressor fits as many complete Screen rows as possible in each independent v5.5 stream and writes a C4h container. EOS ends each chunk naturally; the decoder uploads it, advances Y through the alternate register set and reuses IX.

    LD      HL,PACKED_C4_IMAGE   ; internally chunked for chosen buffer
    LD      DE,0000h            ; packed X=0, Y=0
    LD      IX,8000h            ; reusable 1/2/4/8/16 KB stage
    XOR     A                   ; destination page 0
    CALL    CBS_DECRUNCH
    EI

In that 32 KB test, the 16 KB C4h payload is 11,726 bytes; its 1 KB speed-first form is 14,554 bytes. Burai's earlier four-stream proof totals 7,897 packed bytes. Every timed run was checked against the expected VRAM bytes on a Panasonic FS-A1WSX openMSX profile. These are practical measurements, not a guarantee for every image: sparse chunks can be dominated by setup time, so benchmark the intended split points.

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. Experimental CBT1 follow-up.Revisit its 2,481-byte Screen 5 decoder and possible Screen 6–8 backends only if measured assets justify the extra code.
4. Optional hybrid image path.Destination 4 remains reserved for row/chunk history or another mixed strategy only if measured game data justifies its code.
5. 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.

Tile-grid research retained for comparison

The current backend supports Screen 5 tile grids and the shared E000h/E003h/E006h/E009h calling convention. Screen 6–8 hardware backends and mapped-ROM input remain unfinished. For normal tilesets, platforms and bitmap objects, try v5.5 8 KB first and compare the complete packed-data-plus-decruncher footprint before selecting CBT1.