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.
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.
See the Help & format guide for format header IDs and bitwise specifications.
; ===================================================================== ; 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
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.
python cbs_cruncher.py game.bin
python cbs_cruncher.py game.bin --ram-tailpython cbs_cruncher.py picture.png --mode 7 --rom
python cbs_cruncher.py tiles.bin --linear-vram-screen 5 --romRequires 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.
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.
Compact pair v5.2, combined state-flow v5.3/v5.4 and the v4.3 baseline, with matching RAM decrunchers.
Safe files use in-place tail mode and relocate themselves with LDDR before forward expansion.
v5.3, v5.4 and line-aware v5.5 share paired payloads; change the destination without recompressing.
v5.3/v5.4 linear VRAM mode follows physical Screen line width without forcing rectangle geometry.
One mapped Screen 5–8 decoder mixes buffered and direct images across ASCII8, ASCII16, ASCII16-X, Konami and Konami SCC banks.
Field-tested on real MSX2/MSX2+ hardware and cartridge releases, backed by instant single-image and multi-screen WebMSX verification.
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.
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.
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.
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.
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 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.
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.
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.
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.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.
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 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.
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.
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.