Twiddler

Twiddler is a utility that scans the screen attribute file and replaces every occurrence of one attribute byte with another, allowing colors of already-printed text and graphics to be changed without knowing their original PRINT AT coordinates. The core machine code routine, embedded inside a REM statement at line 2001, is self-relocating: line 2000 calculates its current address dynamically using PEEK 23637 and PEEK 23638 (the PROG system variable), so the routine remains callable even if lines are added or deleted. Two variables, `before` and `after`, are POKEd into the machine code immediately before each RANDOMIZE USR call to specify the source and target attribute bytes. The attribute file at address 22528 (0x5800) spans 768 bytes covering the full 24×32 display; the routine iterates over this region comparing and substituting. A separate introductory loader routine at line 9900 uses its own embedded machine code (in a REM at line 9910) to display a flashing “STOP THE TAPE” banner, also located via the PROG pointer.

---

Program Analysis

Program Structure

The program divides into several distinct functional sections:

1. Lines 10, 9900–9920: Tape-stop alarm subroutine with its own embedded machine code in the REM at line 9910.
2. Lines 50–230: Animated introduction demonstrating the color-rotation effect.
3. Lines 240–330: Tutorial section with live demonstrations of attribute swapping (white↔blue, cyan↔magenta, dull↔bright, white↔black).
4. Lines 350–410: Final menu offering replay or quit.
5. Lines 500–1030: Commented utility stubs including a manual POKE-to-fixed-address variant and attribute calculation helper.
6. Lines 1999–2001: The core relocatable machine code subroutine, embedded in the REM at line 2001.
7. Line 9999: SAVE with autostart.

Machine Code Routine (Line 2001)

The primary machine code is stored inside the REM statement at line 2001. Because a REM occupies a fixed position in the BASIC program area whose actual RAM address shifts whenever lines are added or deleted, line 2000 calculates its current address at runtime:

2000 LET code= PEEK 23637+256* PEEK 23638+6

System variables 23637–23638 hold PROG, the start address of the BASIC program. Adding 6 skips past the line header (2 bytes line number, 2 bytes length, 1 byte REM token, 1 byte space) to reach the first byte of executable machine code. The routine is therefore fully relocatable and requires no fixed load address.

The equivalent routine for a user-chosen fixed address is given in DATA form at line 1020:

Offset	Byte	Z80 Instruction	Purpose
0	62, 0	LD A, 0	Load ‘before’ value (POKEd at offset+1)
2	22, 0	LD D, 0	Load ‘after’ value (POKEd at offset+3)
4	1, 3, 0	LD BC, 3	Byte count low byte (768 = 0x300)
7	33, 0, 88	LD HL, 22528	Start of attribute file (0x5800)
10	190	CP (HL)	Compare attribute with ‘before’
11	32, 1	JR NZ, +1	Skip if no match
13	114	LD (HL), D	Write ‘after’ value
14	35	INC HL	Advance pointer
15	16, 249	DJNZ -7	Loop (uses B as counter)
17	13	DEC C	Decrement high byte of count
18	32, 246	JR NZ, -10	Outer loop
20	201	RET	Return to BASIC

The routine uses a BC-split loop (DJNZ for the low byte, DEC C / JR NZ for the high byte) to iterate all 768 attribute bytes, comparing each against A (‘before’) and replacing matches with D (‘after’).

Attribute Byte Encoding

The attribute byte encodes display properties in a single byte: bits 0–2 = INK color, bits 3–5 = PAPER color, bit 6 = BRIGHT, bit 7 = FLASH. The demo at line 600 shows a convenient technique: set colors with normal BASIC commands, then read PEEK 23693 (the permanent attribute system variable) to obtain the corresponding attribute byte. Several specific values used in the demos:

• 15 = white INK, black PAPER (INK 7, PAPER 0 + BRIGHT 0 = 0b00000111)
• 56 = black INK, white PAPER (INK 0, PAPER 7 = 0b00111000)
• 5 = cyan INK, black PAPER
• 3 = magenta INK, black PAPER
• 70 = BRIGHT + cyan INK, black PAPER
• 64 = FLASH bit set on its own (used to toggle FLASH messages)
• 71 = FLASH off (clearing bit 7)

Tape-Stop Alarm (Lines 9900–9920)

The introductory subroutine uses a second machine code fragment embedded in the REM at line 9910, located via PEEK 23637+256*PEEK 23638+5. It fills the screen with alternating flashing colored stripes spelling “STOP THE TAPE” and calls RANDOMIZE USR woop repeatedly until a key is pressed. The loop at lines 9913–9915 swaps INK and PAPER colors between two variables a and b on each row to produce the alternating stripe effect.

Key BASIC Idioms

• Keypress wait: The pattern IF INKEY$="" THEN GO TO nnn is used throughout to pause execution until a key is pressed, while a preceding IF INKEY$<>"" THEN GO TO nnn flushes any held key first (debounce).
• RANDOMIZE USR: Used in preference to bare USR in a LET statement; the return value is discarded and no error is raised if the routine returns a non-zero value in BC, since RANDOMIZE treats it as a seed.
• Color rotation loop (lines 200, 380): A FOR loop steps the attribute index from 4 to 7 (or 7 to 4), POKEing consecutive palette values into the machine code’s operand bytes to animate a smooth color rotation across the entire screen.
• FOR loop with early exit: IF INKEY$="" THEN NEXT i keeps looping while no key is pressed; falling through exits the FOR loop without triggering a NEXT-without-FOR error, a common ZX Spectrum BASIC technique.

Alternative Fixed-Address Usage (Lines 999–1030)

Lines 999–1030 provide a self-contained alternative for users who want the machine code at a fixed, user-chosen address rather than inside a REM. The DATA at line 1020 contains the identical 21-byte routine; the user POKEs a target address into YourAddress, runs the RESTORE/FOR/READ/POKE loop, and receives back pre-calculated before and after pointer variables. These lines are prefixed with REM : effectively disabling them from the normal flow.

Anomalies and Notes

• Line 395 offers a QUIT option that executes LOAD "" after printing a message; this is intended to load the B-side of the tape rather than a true clean exit.
• The DJNZ inner loop at offset 15 in the machine code uses a displacement of −7 (byte value 249 = 256−7), but the outer DEC C / JR NZ at offset 18 uses −10 (byte value 246 = 256−10). This correctly re-enters at the INC HL instruction to advance past the just-written byte before the next outer iteration begins — the loop structure is intentional and correct.
• Line 325 calls RANDOMIZE USR 3438, a direct call to the ZX Spectrum ROM routine that clears the lower screen, used here to clean up the demo area before printing the “PRESS A KEY” prompt.