PRODUCTION MSX & Z80 COMPRESSOR · PROVEN IN SHIPPING GAMES

Pack MSX graphics and data.
Get matching Z80 code.

Drop any binary file, BMP, PNG, or Screen 5–8 image. Every compression route is verified byte-for-byte in your browser, complete with ready-to-assemble Z80 unpackers and a one-click MSX ROM builder—proven in recent projects including Digger and the new Illusion City ROM.

Screen 5–8 & Linear VRAMByte-Exact Round-Trip ProofInterrupt-Safe (EI) Z80RAM & In-Place TailASCII8/16 · Konami · SCCLocal WebMSX ROMs
AT A GLANCE
Buffered Screen 5–8326 B Z80 (363 B dynamic)1–16 KB RAM
Direct Screen 5–8827 B Z80 (892 B dynamic)ZERO STAGING RAM
RAM Unpackers138–161 B Z80 (Normal & Tail)SHARED Z80 CORE
Cartridge MappersASCII8/16, Konami, SCCAUTO BANK READ

See the Help & format guide for format header IDs and bitwise specifications.

CBS v5.3 · v5.4 · v5.5 · v5.6 compression lab

v5.4 versus v5.3, v5.2 and v4.3

Your file stays local
This is a build-time choice. Packed CB5 files carry no mapper bits.
HL advances linearly in unpaged ROMThe compact original LD A,(HL) reader is retained.
Drop binary, BMP, PNG, SC5–SC8 or CB5 dataContinuous-data comparison or recommended Screen 5–8 direct-VRAM compression · maximum 65,536 packed bytes
No file handy? Try a verified MSX sample:
One linear byte stream tested with v5.4, v5.3, v5.2 formats 0 and 2, and CBS v4.3
5 selected · open Advanced Geometry & Codec Tuning below to customize individual codecs or search window.
Advanced Geometry & Codec Tuning
The same window is used for both v5.2 formats.
v5.4 + v5.3 + v5.2 + v5.2 near + v4.3Adaptive Near LZ (v5.4) · State-Flow LZ (v5.3) · Compact Pair LZ (v5.2) · Compact Pair Near LZ (v5.2) · Historical Baseline (v4.3)
Compressors to run
5 selected · only these searches will run

Recommended runs the four active CBS formats; Select all also adds the slower v4.3 comparison.

Ready-to-assemble Z80 unpacker

Z80 Decruncher Source Generator

326 bytes
cbs_v55_screen5_fixed_buffered_z80.asm · 1–16 KB reusable buffer (8 KB recommended)
; =====================================================================
; CBS Cruncher v5.5 - Screen 5-8 reusable-buffer decruncher v1.3
; =====================================================================
; Build: fixed Screen 5, standard VDP ports (326 bytes)
; Ports: standard MSX VDP ports (99h control, 9Bh indirect register).
;
; Decrunches a C3h v5.5 image or a C4h sequence of independent v5.5 chunks.
; Every EOS uploads the completed RAM chunk with HMMC. C4h then advances Y and
; reuses the same caller-selected buffer until the complete image is restored.
; The packed C3h/C4h stream format and the call contract are unchanged from
; v1.2; v1.2 remains available as cbs_v55_screen58_buffered_v12_z80.asm.
;
; v1.3 changes (measured on openMSX, Panasonic FS-A1WSX, sprites enabled):
;   - HMMC upload uses OTIR (about 23 T-states per byte instead of 43).
;   - The upload sends exactly width x lines bytes; v1.2 could send up to
;     255 surplus bytes per chunk after the HMMC command had completed.
;   - Every control bit is fetched inline with ADD A,A / CALL Z,refill, so
;     only one bit in eight pays for a subroutine call.
;   - Interrupts stay enabled during parsing AND during the HMMC upload, so
;     music drivers keep running: the longest gap between serviced
;     interrupts is one frame (16.7 ms on 60 Hz), against up to 216 ms
;     with v1.2.
;   - About 28% faster than v1.2 on average over 25 test images (21% to
;     33% on real game artwork); the VRAM result was verified for each one.
;
; Interrupt & Stack Safety:
;   - Interrupts are disabled only for the short VDP register and status
;     register sequences; parsing, LDIR copies and the OTIR upload run with
;     interrupts enabled. The decoder returns with interrupts enabled.
;   - The interrupt handler (BIOS plus any music driver) must not change
;     VDP register R#17 or write to the indirect register port while an
;     image is being decrunched. Standard PSG, FM and SCC players do not.
;   - Never uses SP as a data pointer or reads below SP.
;   - Preserves the alternate register set (AF', BC', DE', HL').
;
; Input:
;   HL = CBS image container (C3h or C4h)
;   DE = packed destination coordinate (D = packed X, E = Y)
;   IX = start of the selected 1/2/4/8/16 KB reusable RAM buffer
;   A  = call route (bits 3-2 = VRAM command page 0-3, bits 1-0 = source)
;
; Public entry point:
;   CBS_DECRUNCH    normal image-decompression entry
; =====================================================================
CBS_DECRUNCH:

CBS_V52_SCREEN58_RAM_TO_VRAM:
	AND	0Ch
	RRCA
	RRCA
	LD	B,D			; B = packed X
	LD	D,A			; DE = (page << 8) | Y
	LD	(CBS_V52_VRAM_DY),DE

	EX	DE,HL			; DE = container
	LD	L,B
	LD	H,00h
	ADD	HL,HL		; Screen 5: two pixels per byte
	LD	(CBS_V52_VRAM_DX),HL
	EX	DE,HL			; HL = container

	LD	A,(HL)			; C3h or C4h
	INC	HL
	CP	C4h
	LD	A,(HL)			; packed width (0 = 256)
	INC	HL
	LD	C,01h			; 1 chunk for C3h
	JR	NZ,CBS_V52_VRAM_HEADER_READY
	INC	HL			; skip C4h total height
	LD	C,(HL)			; C4h chunk count
	INC	HL
CBS_V52_VRAM_HEADER_READY:
	EX	DE,HL
	DEC	A
	LD	L,A
	LD	H,00h
	INC	HL			; HL = 16-bit byte width (1..256)
	LD	(CBS_V52_VRAM_ROW_WIDTH+1),HL
	ADD	HL,HL		; Screen 5: two pixels per byte
	LD	A,H
	AND	01h			; command NX wraps 512 dots to 000h
	LD	H,A
	LD	(CBS_V52_VRAM_NX),HL
	EX	DE,HL
	LD	A,C
	LD	(CBS_V52_VRAM_CHUNKS+1),A

CBS_V52_VRAM_CHUNK_START:
	LD	A,(HL)			; chunk line count (0 = 256)
	INC	HL
	DEC	A
	LD	C,A
	LD	B,00h
	INC	BC
	LD	(CBS_V52_VRAM_NY),BC

	PUSH	IX
	POP	DE			; DE = start of reusable RAM buffer
	LD	A,80h			; sentinel control-bit reservoir
	LD	BC,FFFFh		; default negative offset = -1
	PUSH	BC			; persistent last offset on stack

; ---------------------------------------------------------------------
; v5.5 line-aware parser. Control bits are fetched inline:
;   ADD A,A / CALL Z,CBS_V52_VRAM_RELOAD  ->  Carry = next bit
; ---------------------------------------------------------------------
CBS_V52_VRAM_ROW_START:
	CALL	CBS_V52_VRAM_GET_GAMMA
	JR	CBS_V52_VRAM_COPY_LITERALS

CBS_V52_VRAM_AFTER_LITERAL:
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	JR	C,CBS_V52_VRAM_NEW_OFFSET
	CALL	CBS_V52_VRAM_GET_GAMMA_EOS

CBS_V52_VRAM_COPY_MATCH:
	EX	(SP),HL			; HL = offset, stack = packed pointer
	PUSH	HL
	ADD	HL,DE			; HL = RAM match source
	LDIR
	POP	HL			; negative offset
	EX	(SP),HL			; restore packed pointer and offset

CBS_V52_VRAM_AFTER_MATCH:
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	JR	C,CBS_V52_VRAM_NEW_OFFSET
	CALL	CBS_V52_VRAM_GET_GAMMA_EOS

CBS_V52_VRAM_COPY_LITERALS:
	LDIR
	JR	CBS_V52_VRAM_AFTER_LITERAL

; ---------------------------------------------------------------------
; New offset: selector 0 = whole-line distance, selector 1 = compact general.
; ---------------------------------------------------------------------
CBS_V52_VRAM_NEW_OFFSET:
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	JR	C,CBS_V52_VRAM_GENERAL_OFFSET

CBS_V52_VRAM_ROW_OFFSET:
	CALL	CBS_V52_VRAM_GET_NEG_GAMMA
	INC	BC			; C = negative row count (FFh = -1, etc.)
	PUSH	DE
	PUSH	HL
CBS_V52_VRAM_ROW_WIDTH:
	LD	DE,0000h		; patched 16-bit packed width (1..256)
	LD	HL,0000h
CBS_V52_VRAM_MULTIPLY:
	OR	A
	SBC	HL,DE
	INC	C
	JR	NZ,CBS_V52_VRAM_MULTIPLY
	LD	B,H
	LD	C,L			; BC = negative byte distance
	POP	HL
	POP	DE
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	JR	CBS_V52_VRAM_STORE_OFFSET

CBS_V52_VRAM_GENERAL_OFFSET:
	CALL	CBS_V52_VRAM_GET_NEG_GAMMA
	INC	BC
	RR	B
	LD	B,C
	LD	C,(HL)
	INC	HL
	RR	B
	RR	C			; BC = negative distance, CF = 1st len bit

CBS_V52_VRAM_STORE_OFFSET:
	EX	(SP),HL
	POP	HL
	PUSH	BC
	LD	BC,0001h
	CALL	NC,CBS_V52_VRAM_GAMMA_LOOP
	INC	BC
	JR	CBS_V52_VRAM_COPY_MATCH

; ---------------------------------------------------------------------
; Upload completed RAM chunk at IX via 11-byte R36..R46 HMMC block.
; Only the register latch sequences run with interrupts disabled.
; ---------------------------------------------------------------------
CBS_V52_VRAM_FINISHED:
	POP	BC			; discard persistent last offset
	PUSH	HL			; preserve next packed chunk pointer

	PUSH	IX
	POP	HL
	LD	A,(HL)
	INC	HL
	LD	(CBS_V52_VRAM_CLR),A	; seed R44 with first pixel byte
	EX	DE,HL			; DE = IX + 1

	DI				; atomic VDP register setup
	LD	HL,CBS_V52_VRAM_COMMAND_DATA
CBS_V52_PORT_CONTROL:
	LD	C,99h			; patched once from BIOS VDP.DW
	LD	A,24h
	OUT	(C),A
	LD	A,91h			; R#17 = 36 with auto-increment
	OUT	(C),A
	INC	C
	INC	C			; C = indirect register port
	LD	B,0Bh			; emit R36..R46 (starts HMMC)
	OTIR

	DEC	C
	DEC	C			; C = control port
	LD	A,44 + 80h		; R#17 = 44 without auto-increment
	OUT	(C),A
	LD	A,91h
	OUT	(C),A
	INC	C
	INC	C			; C = indirect register port
	EI				; upload continues with interrupts enabled

	EX	DE,HL			; HL = IX + 1
	LD	A,(CBS_V52_VRAM_NY)
	LD	D,A			; D = line counter (0 = 256)
	LD	A,(CBS_V52_VRAM_ROW_WIDTH+1)
	LD	E,A			; E = row width (0 = 256)
	DEC	A
	LD	B,A			; first row: R44 already holds byte 0
CBS_V52_VRAM_COPY:
	OTIR				; interruptible block output
	LD	B,E
	DEC	D
	JR	NZ,CBS_V52_VRAM_COPY

	DEC	C
	DEC	C			; C = control port
	DI				; atomic status register selection
	LD	A,02h			; select status register 2
	OUT	(C),A
	LD	A,8Fh
	OUT	(C),A
CBS_V52_VRAM_EXIT_WAIT:
	IN	A,(C)
	RRCA				; Carry = CE
	JR	C,CBS_V52_VRAM_EXIT_WAIT
	XOR	A			; restore status register 0
	OUT	(C),A
	LD	A,8Fh
	OUT	(C),A
	EI

	LD	HL,CBS_V52_VRAM_DY
	LD	A,(CBS_V52_VRAM_NY)
	ADD	A,(HL)
	LD	(HL),A			; advance destination Y
	POP	HL			; next chunk header after this EOS
CBS_V52_VRAM_CHUNKS:
	LD	A,00h
	DEC	A
	RET	Z
	LD	(CBS_V52_VRAM_CHUNKS+1),A
	JP	CBS_V52_VRAM_CHUNK_START

; ---------------------------------------------------------------------
; Interlaced gamma readers and the shared bit-reservoir refill.
; ---------------------------------------------------------------------
CBS_V52_VRAM_GET_GAMMA_EOS:
	LD	BC,0001h
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	JR	NC,CBS_V52_VRAM_GAMMA_LOOP
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	RET	NC
	POP	BC			; discard caller return address
	JR	CBS_V52_VRAM_FINISHED

CBS_V52_VRAM_GET_GAMMA:
	LD	BC,0001h
	JR	CBS_V52_VRAM_GAMMA_ENTRY

CBS_V52_VRAM_GET_NEG_GAMMA:
	LD	BC,FFFEh
CBS_V52_VRAM_GAMMA_ENTRY:
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	RET	C
CBS_V52_VRAM_GAMMA_LOOP:
	ADD	A,A
	CALL	Z,CBS_V52_VRAM_RELOAD
	RL	C
	RL	B
	JR	CBS_V52_VRAM_GAMMA_ENTRY

CBS_V52_VRAM_RELOAD:
	LD	A,(HL)			; sentinel left: load the next 8 bits
	INC	HL
	RLA				; Carry = bit 7, sentinel enters bit 0
	RET

; ---------------------------------------------------------------------
; Writable R36-R46 HMMC parameter block (11 bytes).
; ---------------------------------------------------------------------
CBS_V52_VRAM_COMMAND_DATA:
CBS_V52_VRAM_DX:
	DW	0
CBS_V52_VRAM_DY:
	DW	0
CBS_V52_VRAM_NX:
	DW	0
CBS_V52_VRAM_NY:
	DW	0
CBS_V52_VRAM_CLR:
	DB	0			; R44: seeded with 1st byte of buffer
	DB	00h			; R45: ARG = 0
	DB	F0h			; R46: CMD = HMMC
Windows · macOS · Linux

The same compressor from a Python command line

The downloadable package uses the same compiled engine and parameters as this page. It handles continuous data, Screen 5–8 images, native BMP/PNG import, SC5–SC8 BSAVE files, CB5 decrunching, RAM-tail output, linear VRAM and one-image MSX test ROMs.

CBS Cruncher v5.6 CLI · release 10

Cross-platform compressor plus the practical Z80 source set

Continuous data
python cbs_cruncher.py game.bin
python cbs_cruncher.py game.bin --ram-tail
Screen image + test ROM
python cbs_cruncher.py picture.png --mode 7 --rom
python cbs_cruncher.py tiles.bin --linear-vram-screen 5 --rom

Requires Python 3.10+ and Node.js 22+. Pillow is needed only for BMP/PNG input. The website-only multi-image demonstration ROM remains intentionally separate from the CLI.

Production-proven · shipping in real MSX projects

Proven in recent releases including Digger and the new Illusion City ROM

CBS Cruncher is a thoroughly tested production toolkit, not a beta prototype. Every compression route below is verified byte-for-byte and proven in active MSX game releases and translations—including Digger and the new version of the Illusion City ROM.

01Continuous RAM

Code, maps, text and arbitrary bytes

Compact pair v5.2, combined state-flow v5.3/v5.4 and the v4.3 baseline, with matching RAM decrunchers.

02Measured RAM-tail

Reuse the destination block

Safe files use in-place tail mode and relocate themselves with LDDR before forward expansion.

03Screen 5–8

Buffered or direct VRAM

v5.3, v5.4 and line-aware v5.5 share paired payloads; change the destination without recompressing.

04Linear VRAM

Tiles, fonts and pattern data

v5.3/v5.4 linear VRAM mode follows physical Screen line width without forcing rectangle geometry.

05Cartridge ROM input

Five mapper families

One mapped Screen 5–8 decoder mixes buffered and direct images across ASCII8, ASCII16, ASCII16-X, Konami and Konami SCC banks.

06Shipping games

Proven in Digger & Illusion City ROM

Field-tested on real MSX2/MSX2+ hardware and cartridge releases, backed by instant single-image and multi-screen WebMSX verification.

Future expansion

Optional MSX Memory Mapper RAM destination

Linear RAM, in-place RAM-tail, Screen 5–8 buffered/direct VRAM and five cartridge-ROM mappers are complete and shipping in games today. Future extensions add direct unpacking into selected MSX Memory Mapper RAM segments when upcoming projects call for it.

Future extensions
1996 → 2026 · reconstructed from sources and project records

How CBS Cruncher grew into v5.6

A Motorola 68000 cruncher and tiny Z80 decruncher became a verified browser tool, a family of RAM/VRAM writers and a real MSX ROM builder.

V5.5 BUFFERED DECODER V1.3

About 28% faster, and the music keeps playing

The buffered Screen 5–8 decoder v1.3 uploads each chunk with OTIR, sends exactly the bytes HMMC needs, reads control bits inline and keeps interrupts enabled while it parses and uploads. Over 25 openMSX test images it is about 28% faster than v1.2 (21–33% on real game artwork), every restored VRAM image was verified, and the longest gap between serviced interrupts fell from 216 ms to one 60 Hz frame. It is 363 bytes with dynamic init (326 B fixed Screen 5/7); the packed format and entry points are unchanged, and the 358-byte v1.2 remains available as a classic download.

MEASURED INTEGRATION GUIDE

Decoder cost, RAM cost and speed become one practical choice

The Help page now starts with the compact v5.5 route, publishes exact shipped decruncher sizes, and compares reusable 1, 2, 4, 8 and 16 KB windows on a verified 24 KB Screen 5 image. The 8 KB window is recommended as the usual balance—not a universal winner—while v5.6 is presented as the stronger directional compressor with a larger decoder. The older tile-grid experiment remains available at the end as research rather than the default workflow.

V5.5 REUSABLE BUFFER

Large Screen 5–8 images no longer need one full-image RAM stage

The v5.5 chunked container divides an image into complete-row, EOS-terminated streams sized for the game's selected 1–16 KB buffer. One CBS_DECRUNCH call expands every chunk, uploads it with HMMC, advances Y and reuses the same RAM automatically. The shared v5.5 buffered decoder, now v1.3, is 326–363 bytes (326 B fixed Screen 5/7, 363-byte buffered decoder with dynamic init); measured examples showed a substantial display-speed advantage over Direct while allowing each project to trade RAM against packed size.

THE ORIGINAL

CBS Cruncher is written for the Amiga

The 68000 cruncher produces CBS v3. Its small Z80 decruncher originated on the ZX Spectrum and also works on MSX. A ROM-reading MSX version was later developed during the Romancia translation while the executable decoder still ran from RAM.

RECOVERY + FORMAT DESIGN

The surviving sources become a verified browser tool

We restored v3 and v4.3, reproduced the Romancia result, replaced the unsafe four-byte overlap assumption with exact measurement, imported BMP/PNG pixels, and developed the v5.2 compact formats with a documented three-byte header and optimized Z80 RAM core.

LEARNING FROM ZX0

One excellent decoder changes our direction

ZX0's state flow, interlaced Elias coding, last offset on the stack, EX (SP),HL copying and impossible-offset EOS guided v5.3 and v5.4. CBS kept its own headers, offsets, adaptive-near choice and destination system.

DIRECT VRAM + ROM BANKS

Large pictures stop requiring a full RAM buffer

CPU literals, HMMM matches and HMMV fills made direct Screen 5–8 output practical. Five cartridge mapper readers, palettes, RAM decoder relocation, F500h controller code and ordered multi-image ROMs followed.

V5.5 INTEGRATION RELEASE

The experimental pieces become one usable system

v5.3/v5.4 gained one combined RAM decoder; v5.5 line offsets joined buffered and direct image routes; linear VRAM mode was added; measured RAM-tail relocation was added; the Python CLI gained matching outputs; and the website was divided into a focused compressor plus this complete integration guide.

ONE MAPPED IMAGE DECODER

Buffered and direct pictures share the same ROM

The five cartridge-mapper builds gained a shared consecutive-bank reader and an optional mixed destination dispatcher. Direct-only lists now keep the smaller direct decoder; lists containing buffered streams automatically receive the combined RAM-stage/HMMC and direct-VRAM decoder. Machine ports, the initial Screen mode and an unchanged palette are initialized once before playback, while later setup runs only for a real mode or palette transition. The buffered uploader now waits for final HMMC completion before returning, and demo ROMs disable sprites to prevent artifacts while freeing VDP bandwidth.

V5.6 DIRECTIONAL IMAGE RELEASE

Screen 5 images gain directional reconstruction and rolling buffers

v5.6 searches horizontal and vertical traversal orders in both directions, keeps the smallest permitted v5.5-based stream, and reconstructs exact plus horizontally, vertically and two-axis-mirrored rectangles in place with VDP commands. One Screen 5 decoder accepts all four orders. Its VDP ports are patched once from the BIOS, register writes are inlined, unnecessary address helpers and command waits were removed, interrupts remain enabled outside short VDP latch sequences, and compatible HMMM work is coalesced.

The optimized Direct decoder is 2,078 bytes and expands a complete 32 KB tile-image benchmark in 7.831 seconds, faster than the measured v5.4 and v5.5 Direct routes. Optional 1–16 KB rolling builds use the identical packed file and are 2,639 bytes; they currently help horizontal delivery most. v5.5 remains the compact line-aware alternative: its 326–363-byte buffered decoder v1.3 (326 B fixed Screen 5/7, 363 B dynamic) automatically expands independent EOS-terminated chunks through one reusable caller-selected buffer and advances Y internally. The earlier version restored the same test in roughly 2.5–2.8 seconds depending on the chosen split; those timings predate the latest optimizations.

LOCAL WEBMSX + CLI RELEASE 9

Long mapper ROMs run without an address-length limit

A dedicated local WebMSX player replaced ROM-sized Base64 launch URLs. The browser now transfers complete cartridges directly between local tabs, preserving Japanese MSX2 NTSC, palette and mapper selection without uploading the ROM. The Python CLI was regenerated from the same engine, given reproducible packaging and tested across every continuous codec, buffered/direct images, linear VRAM, RAM-tail, BSAVE handling and all five mapped-ROM readers.

COMPACT TABLE-DRIVEN ROM PLAYER

Large image lists stop consuming the F500h controller area

The multi-image builder replaced per-picture playback code with one shared loop and a compact RAM table containing Screen mode, VRAM page, mapper bank, packed address, palette and clear-command references. The HMMV clear now sends an eleven-byte VDP command block with OTIR, identical mode/black-colour blocks are reused, and a new public CBS_WAIT_VDP decoder entry owns VDP-command waiting. A ten-image mixed ASCII16 player now occupies only 643 bytes at F500h, including its table, palettes and clear parameters.

The Help & format guide contains the byte layout, calling conventions, worked examples and remaining roadmap.