Code Like It's 198x

Decode Bounded RLE Data on Spectrum

Repeated tiles or pixels can be stored as a count followed by a value.

Repeated tiles or pixels can be stored as a count followed by a value. Decoding is small, but trusting a damaged run count can overwrite the next object in RAM. This version checks both ends and tells the caller exactly how much output was produced.

Spectrum shows the working diagnostic row 06 00 00 06 08 41 41 41.
A native completed caller shows its state as hexadecimal bytes. The field order below explains the row; the full packet retains every call.

Include, initialise and call

Reserve WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7 as 13 contiguous private bytes in that order. Include the helper once. Call bounded_rle_init at the intended reset boundary: it clears every named byte, including input fields. Set the starting values afterwards, then call bounded_rle_step for each intended service.

Initialise once, set the selected encoded span and available output length, then service. Check ERROR before accepting an asset as complete. On a decoding error the buffer contains a valid decoded prefix of length WRITTEN; it is not rolled back. Bytes after that prefix are preserved. A consumer that wants an all-or-nothing asset should decode into staging memory and commit only on success.

INPUT_START and INPUT_END are byte offsets into caller-owned rle_stream, with INPUT_START ≤ INPUT_END ≤ STREAM_BYTES. OUTPUT_LIMIT is 0–8 for the reserved eight-byte output buffer. Step replaces WRITTEN and ERROR, preserves the input parameters and decodes count/value pairs. ERROR 0 means the selected input span finished; 1 means invalid input/output bounds; 2 means a truncated pair; 3 means a zero run; 4 means output capacity was reached before the selected stream finished. WRITTEN counts only bytes actually stored.

Reusable initialisation and service

component.inc
; SPDX-License-Identifier: MIT
; Decode Bounded RLE Data. Contiguous private bytes: WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7.
; init clears all fields; set inputs afterwards. No I/O, waits or IRQ ownership.
; AF/BC/DE/HL change; IX/IY survive.
bounded_rle_init:
    xor a
    ld (WRITTEN),a
    ld (ERROR),a
    ld (INPUT_START),a
    ld (INPUT_END),a
    ld (OUTPUT_LIMIT),a
    ld (BUF0),a
    ld (BUF1),a
    ld (BUF2),a
    ld (BUF3),a
    ld (BUF4),a
    ld (BUF5),a
    ld (BUF6),a
    ld (BUF7),a
    ret
bounded_rle_step:
    xor a
    ld (WRITTEN),a
    ld (ERROR),a
    ld a,(INPUT_END)
    cp STREAM_BYTES+1
    jr nc,rle_bounds
    ld b,a
    ld a,(INPUT_START)
    cp b
    jr c,rle_check_output
    jr z,rle_check_output
rle_bounds:
    ld a,1
    jr rle_error
rle_check_output:
    ld a,(OUTPUT_LIMIT)
    cp 9
    jr nc,rle_bounds
    ld a,(INPUT_START)
    ld e,a
    ld d,0
    ld hl,rle_stream
    add hl,de
    ld a,(INPUT_END)
    sub e
    ld b,a
    ld de,BUF0
rle_pair:
    ld a,b
    or a
    ret z
    cp 2
    jr c,rle_truncated
    ld a,(hl)
    inc hl
    dec b
    or a
    jr z,rle_zero
    ld c,a
    ld a,(hl)
    inc hl
    dec b
rle_copy:
    push af
    push bc
    ld a,(OUTPUT_LIMIT)
    ld b,a
    ld a,(WRITTEN)
    cp b
    pop bc
    jr nc,rle_full
    pop af
    ld (de),a
    inc de
    push af
    ld a,(WRITTEN)
    inc a
    ld (WRITTEN),a
    pop af
    dec c
    jr nz,rle_copy
    jr rle_pair
rle_full:
    pop af
    ld a,4
    jr rle_error
rle_truncated:
    ld a,2
    jr rle_error
rle_zero:
    ld a,3
rle_error:
    ld (ERROR),a
    ret
component_end:

Caller-owned immutable lookup/encoded data

data.inc
data_start:
rle_stream:
    defb 3,65,2,66,1,67,0,88,5,68,1,69,2
data_end:

State, registers and ownership

Five control/input/output bytes followed by BUF0–BUF7. The sample has thirteen immutable input bytes, including malformed examples. Count zero is rejected; there is no terminator convention or implicit end beyond INPUT_END. A zero-length selected span succeeds with zero output. The routine can stop partway through a run when capacity is exhausted.

AF/BC/DE/HL may change; IX/IY survive. A direct CALL needs two return-address stack bytes. The copy loop temporarily saves AF and BC, adding up to four bytes: allow six stack bytes for the helper call, excluding its caller and interrupts.

The implementation binds fixed symbols and has one mutation owner. Independent users need separate state blocks and scoped/renamed labels, including routine labels; sharing the same bindings means sharing the state. Do not let an interrupt and the main loop mutate the same block without an explicit ownership policy.

The standalone tape program enters at $8000, disables interrupts and owns bitmap/attribute RAM. It does not restore BASIC. Those choices belong to the test program; the helper itself never takes over the display.

A caller you can adapt

The buildable program supplies bindings and include order. Its separate client retains state between calls. checked_step calls the public bounded_rle_step entry and checks register sentinels; emit_state records diagnostics. Your game can call the public entry directly, remove the diagnostics and consume the documented outputs.

Bindings, buildable caller and include order

demo.asm
    org $8000
CUSTOM equ 0
BROKEN equ 0
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
    include "caller.inc"
    include "exercise.inc"
component_start:
    include "component.inc"
    include "data.inc"
    include "cases.inc"
    include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
WRITTEN: defb 0
ERROR: defb 0
INPUT_START: defb 0
INPUT_END: defb 0
OUTPUT_LIMIT: defb 0
BUF0: defb 0
BUF1: defb 0
BUF2: defb 0
BUF3: defb 0
BUF4: defb 0
BUF5: defb 0
BUF6: defb 0
BUF7: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
    end start

A separate client retaining state between calls

exercise.inc, excerpt
preview_rules:
    if CUSTOM
    ld a,0
    ld (INPUT_START),a
    ld a,6
    ld (INPUT_END),a
    ld a,5
    ld (OUTPUT_LIMIT),a
    if BROKEN
    call checked_step
    ld a,(OUTPUT_LIMIT)
    ld (WRITTEN),a
    else
    call checked_step
    endif
    call emit_state
    else
    ld a,0
    ld (INPUT_START),a
    ld a,6
    ld (INPUT_END),a
    ld a,8
    ld (OUTPUT_LIMIT),a
    if BROKEN
    call checked_step
    ld a,(OUTPUT_LIMIT)
    ld (WRITTEN),a
    else
    call checked_step
    endif
    call emit_state
    endif
    ret

The display fields are WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2; later state bytes are retained in the full packet. Each is one hexadecimal byte. The normal row is 06 00 00 06 08 41 41 41. This is a completed state observation, not a recording of an actual character jumping, a camera scrolling or an asset being displayed.

Make it your own

The normal caller decodes the first six input bytes into AAABBC, six output bytes. The custom caller offers only five output slots: AAABB is produced and ERROR 4 reports the unfinished selected stream. Treating capacity as the amount written would hide the normal caller’s two unused slots.

Maintained custom configuration or caller

custom.asm
    org $8000
CUSTOM equ 1
BROKEN equ 0
COYOTE_STEPS equ 2
BUFFER_STEPS equ 2
TEXT_CAP equ 4
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 49
    include "caller.inc"
    include "exercise.inc"
component_start:
    include "component.inc"
    include "data.inc"
    include "cases.inc"
    include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
WRITTEN: defb 0
ERROR: defb 0
INPUT_START: defb 0
INPUT_END: defb 0
OUTPUT_LIMIT: defb 0
BUF0: defb 0
BUF1: defb 0
BUF2: defb 0
BUF3: defb 0
BUF4: defb 0
BUF5: defb 0
BUF6: defb 0
BUF7: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
    end start

The custom row is 05 04 00 06 05 41 41 41. These records qualify the named builds and inputs; another layout, format or input domain needs explicit bounds and fresh execution evidence.

Common mistake and repair

The wrong client replaces WRITTEN with OUTPUT_LIMIT after decoding. The normal six-byte asset is now advertised as eight bytes, including two bytes the decoder never produced. Publish the returned length, and check the returned error; capacity is not output length.

Select the deliberately wrong client

wrong.asm
    org $8000
CUSTOM equ 0
BROKEN equ 1
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
    include "caller.inc"
    include "exercise.inc"
component_start:
    include "component.inc"
    include "data.inc"
    include "cases.inc"
    include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
WRITTEN: defb 0
ERROR: defb 0
INPUT_START: defb 0
INPUT_END: defb 0
OUTPUT_LIMIT: defb 0
BUF0: defb 0
BUF1: defb 0
BUF2: defb 0
BUF3: defb 0
BUF4: defb 0
BUF5: defb 0
BUF6: defb 0
BUF7: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
    end start
Spectrum shows the deliberate fault row 08 00 00 06 08 41 41 41.
The wrong client completes with 08 00 00 06 08 41 41 41. Its code and the explanation above identify the cause; the capture observes the result.

The BROKEN branch is visible in the client. repaired.asm restores the normal selection; its executable matches demo exactly. Spectrum tape filenames may differ while loaded CODE remains identical. The fault is a labelled experiment, not a suggested alternative.

Cost, limits and verification

The measured layout has 155 code bytes, 13 immutable data bytes and 13 private state bytes. Alignment, stack usage, diagnostic tables and display machinery are additional. The extents come from the loaded program’s symbols, not from counting source lines.

Work is bounded by the selected input span and output capacity. Each pair consumes two input bytes; each produced byte advances the output count. The qualified output has at most eight stores, with no allocation or hidden display upload. Compression trades encoded storage against decode work and may make alternating data larger.

This is a local classic count/value codec example, not a new project-wide asset format. Longer assets need an appropriately sized output span and possibly wider offsets, plus independently checked bounds. Packed literals, streaming continuation and precompressed build-tool assets are separate extensions. Do not turn zero runs into an unchecked infinite loop or infer success from a full buffer.

Four native runs use Spectrum 48K with stock ROM tape loading and USR entry; Asm198x 0.0.72 and Emu198x 0.44.2. Each checks 64 boundary/varied/error cases, dirty initialisation and every state of a separate sequential client against an independent integer model. This is not exhaustive coverage of every possible byte combination. Source/tool/firmware hashes, immutable loaded code/data, native startup/completion, preserved-register sentinels, helper/data sizes, screenshot bytes/pixels and exact repair are checked. Deliberately altered observations must fail. Firmware is hashed, never distributed.

Related technique · Maths for Games · The Craft.

Source and native evidence.