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.
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
; 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.
; D0-D3/A0-A1/CCR change; D4-D7/A2-A6 survive.
menu_navigation_init:
clr.b SELECTED
clr.b OPTION_COUNT
clr.b ENABLED
clr.b DELTA
clr.b MOVED
clr.b VALID
rts
menu_navigation_step:
clr.b MOVED
clr.b VALID
moveq #0,d0
move.b OPTION_COUNT,d0
beq.s menu_done
cmp.b #8,d0
bhi.s menu_done
moveq #0,d1
move.b SELECTED,d1
cmp.b d0,d1
bhs.s menu_done
move.b DELTA,d2
beq.s menu_still
cmp.b #1,d2
beq.s menu_start
cmp.b #255,d2
bne.s menu_done
menu_start:
move.b #1,VALID
subq.w #1,d0
menu_search:
cmp.b #1,d2
bne.s menu_previous
addq.b #1,d1
cmp.b OPTION_COUNT,d1
blo.s menu_test
moveq #0,d1
bra.s menu_test
menu_previous:
tst.b d1
bne.s menu_dec
move.b OPTION_COUNT,d1
menu_dec:
subq.b #1,d1
menu_test:
moveq #0,d3
move.b ENABLED,d3
btst d1,d3
bne.s menu_found
dbra d0,menu_search
rts
menu_found:
cmp.b SELECTED,d1
beq.s menu_done
move.b d1,SELECTED
move.b #1,MOVED
rts
menu_still:
move.b #1,VALID
menu_done:
rts
component_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.
D0–D3/A0–A1/CCR may change; D4–D7/A2–A6 survive. A direct BSR/JSR needs four 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 bootable caller takes over Copper/bitplane/interrupt/DMA resources and explicitly disarms all eight sprites. It does not restore Workbench. These are caller presentation choices, not dependencies of the reusable helper.
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
section code,code_c
CUSTOM = 0
BROKEN = 0
COYOTE_STEPS = 4
BUFFER_STEPS = 4
TEXT_CAP = 8
PROPERTY_COUNT = 16
STREAM_BYTES = 13
CRC_POLY = 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
SELECTED: dc.b 0
OPTION_COUNT: dc.b 0
ENABLED: dc.b 0
DELTA: dc.b 0
MOVED: dc.b 0
VALID: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XPLAYTOOLS00",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0A separate client retaining state between calls
preview_rules:
ifne CUSTOM
move.b #2,SELECTED
move.b #3,OPTION_COUNT
move.b #7,ENABLED
move.b #255,DELTA
ifne BROKEN
move.b DELTA,d0
add.b d0,SELECTED
move.b #1,MOVED
move.b #1,VALID
else
bsr checked_step
endif
bsr emit_state
else
move.b #2,SELECTED
move.b #3,OPTION_COUNT
move.b #5,ENABLED
move.b #1,DELTA
ifne BROKEN
move.b DELTA,d0
add.b d0,SELECTED
move.b #1,MOVED
move.b #1,VALID
else
bsr checked_step
endif
bsr emit_state
endif
rtsThe 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
section code,code_c
CUSTOM = 1
BROKEN = 0
COYOTE_STEPS = 2
BUFFER_STEPS = 2
TEXT_CAP = 4
PROPERTY_COUNT = 16
STREAM_BYTES = 13
CRC_POLY = 49
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
SELECTED: dc.b 0
OPTION_COUNT: dc.b 0
ENABLED: dc.b 0
DELTA: dc.b 0
MOVED: dc.b 0
VALID: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XPLAYTOOLS00",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0The 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
section code,code_c
CUSTOM = 0
BROKEN = 1
COYOTE_STEPS = 4
BUFFER_STEPS = 4
TEXT_CAP = 8
PROPERTY_COUNT = 16
STREAM_BYTES = 13
CRC_POLY = 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
SELECTED: dc.b 0
OPTION_COUNT: dc.b 0
ENABLED: dc.b 0
DELTA: dc.b 0
MOVED: dc.b 0
VALID: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XPLAYTOOLS00",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0
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 178 code bytes, 0 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 A500 OCS PAL with Kickstart 1.3 and an OFS cold-boot disk; Asm198x 0.0.72 and Emu198x 0.44.2, with Build198x 0.2.9 for disk mastering. 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.