Code Like It's 198x

Wrap and Skip Menu Options on Spectrum

A menu should wrap cleanly at either end and skip options the player cannot choose.

A menu should wrap cleanly at either end and skip options the player cannot choose. Keep the selection rule separate from drawing and key-repeat timing, and the same menu can work with a keyboard, joystick or controller.

Spectrum shows the working diagnostic row 00 03 05 01 01 01 00 00.
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 SELECTED, OPTION_COUNT, ENABLED, DELTA, MOVED, VALID as 6 contiguous private bytes in that order. Include the helper once. Call menu_navigation_init at the intended reset boundary: it clears every named byte, including input fields. Set the starting values afterwards, then call menu_navigation_step for each intended service.

Initialise once, set the option count, mask and starting selection, then offer one navigation action at a time. Use the existing input-repeat routine to decide when held input should produce another action. Resolve opposed directions before supplying DELTA. A disabled starting selection can move to an enabled candidate; the routine does not draw or activate the option.

OPTION_COUNT is 1–8 and SELECTED must be a valid index below it. ENABLED is a bit mask: bit zero enables option zero, and bits above the count are ignored. DELTA is 1 forward, 255 backward or zero for no movement. Invalid count/index/delta preserves selection and clears VALID/MOVED. A valid call sets VALID and searches at most OPTION_COUNT candidates, wrapping and choosing the first enabled option. With none enabled it leaves the selection unchanged; MOVED reports an actual selection change.

Reusable initialisation and service

component.inc
; SPDX-License-Identifier: MIT
; Wrap and Skip Menu Options. Contiguous private bytes: SELECTED, OPTION_COUNT, ENABLED, DELTA, MOVED, VALID.
; init clears all fields; set inputs afterwards. No I/O, waits or IRQ ownership.
; AF/BC/DE/HL change; IX/IY survive.
menu_navigation_init:
    xor a
    ld (SELECTED),a
    ld (OPTION_COUNT),a
    ld (ENABLED),a
    ld (DELTA),a
    ld (MOVED),a
    ld (VALID),a
    ret
menu_navigation_step:
    xor a
    ld (MOVED),a
    ld (VALID),a
    ld a,(OPTION_COUNT)
    or a
    ret z
    cp 9
    ret nc
    ld b,a
    ld a,(SELECTED)
    cp b
    ret nc
    ld c,a
    ld a,(DELTA)
    or a
    jr z,menu_still
    cp 1
    jr z,menu_start
    cp 255
    ret nz
menu_start:
    ld a,1
    ld (VALID),a
menu_search:
    ld a,(DELTA)
    cp 1
    jr nz,menu_previous
    inc c
    ld a,(OPTION_COUNT)
    cp c
    jr nz,menu_test
    ld c,0
    jr menu_test
menu_previous:
    ld a,c
    or a
    jr nz,menu_dec
    ld a,(OPTION_COUNT)
    ld c,a
menu_dec:
    dec c
menu_test:
    ld e,c
    ld d,0
    ld hl,menu_masks
    add hl,de
    ld a,(ENABLED)
    and (hl)
    jr nz,menu_found
    djnz menu_search
    ret
menu_found:
    ld a,(SELECTED)
    cp c
    ret z
    ld a,c
    ld (SELECTED),a
    ld a,1
    ld (MOVED),a
    ret
menu_still:
    ld a,1
    ld (VALID),a
    ret
component_end:

Caller-owned immutable lookup/encoded data

data.inc
data_start:
menu_masks:
    defb 1,2,4,8,16,32,64,128
data_end:

State, registers and ownership

Six bytes, including the caller’s direction input and the replaced MOVED/VALID flags. A no-movement DELTA does not repair a disabled selected option. A valid count/layout is separate from the question of whether an option is currently enabled.

AF/BC/DE/HL may change; IX/IY survive. A direct CALL needs two return-address stack bytes.

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 menu_navigation_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:
SELECTED: defb 0
OPTION_COUNT: defb 0
ENABLED: defb 0
DELTA: defb 0
MOVED: defb 0
VALID: 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,2
    ld (SELECTED),a
    ld a,3
    ld (OPTION_COUNT),a
    ld a,7
    ld (ENABLED),a
    ld a,255
    ld (DELTA),a
    if BROKEN
    ld a,(DELTA)
    ld b,a
    ld a,(SELECTED)
    add a,b
    ld (SELECTED),a
    ld a,1
    ld (MOVED),a
    ld a,1
    ld (VALID),a
    else
    call checked_step
    endif
    call emit_state
    else
    ld a,2
    ld (SELECTED),a
    ld a,3
    ld (OPTION_COUNT),a
    ld a,5
    ld (ENABLED),a
    ld a,1
    ld (DELTA),a
    if BROKEN
    ld a,(DELTA)
    ld b,a
    ld a,(SELECTED)
    add a,b
    ld (SELECTED),a
    ld a,1
    ld (MOVED),a
    ld a,1
    ld (VALID),a
    else
    call checked_step
    endif
    call emit_state
    endif
    ret

The display fields are SELECTED, OPTION_COUNT, ENABLED, DELTA, MOVED, VALID; remaining display fields are zero. Each is one hexadecimal byte. The normal row is 00 03 05 01 01 01 00 00. 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 example starts at option two in a three-option menu with only options zero and two enabled, then wraps forward to zero. The custom caller enables all three and requests a backward move, selecting option one.

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:
SELECTED: defb 0
OPTION_COUNT: defb 0
ENABLED: defb 0
DELTA: defb 0
MOVED: defb 0
VALID: 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 01 03 07 FF 01 01 00 00. 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 simply adds DELTA to SELECTED. Moving forward from the last index two produces invalid index three, because byte wrap is not menu wrap. Bound the index by the option count and search the enabled candidates.

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:
SELECTED: defb 0
OPTION_COUNT: defb 0
ENABLED: defb 0
DELTA: defb 0
MOVED: defb 0
VALID: 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 03 03 05 01 01 01 00 00.
The wrong client completes with 03 03 05 01 01 01 00 00. 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 124 code bytes, 8 immutable data bytes and 6 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.

At most eight candidate tests. The 6502/Z80 examples use an eight-byte mask table; 68000 tests a register bit directly and needs no table. Keeping a count bounds the search even when every option is disabled.

More than eight options need a larger availability structure and wider or bounded indices. Two-dimensional layouts need an explicit neighbour/navigation policy. Selection and activation should remain distinct, especially when a key that opened a menu is still held.

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.