Entering a player name needs more than appending characters. Full buffers must refuse another byte, Backspace at the start must stay at zero, and the caller must know how many characters are real.
Include, initialise and call
Reserve LENGTH, STATUS, KEY, MODE, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7 as 12 contiguous private bytes in that order. Include the helper once. Call text_entry_buffer_init at the intended reset boundary: it clears every named byte, including input fields. Set the starting values afterwards, then call text_entry_buffer_step for each intended service.
Initialise once, translate the machine’s input into a logical key/action, then call step. Draw exactly LENGTH bytes. This is a counted buffer, not a promise of a zero terminator when full. The helper does not scan a keyboard, wait for input or implement key repeat.
The buffer reserves BUF0–BUF7. LENGTH is the number of live bytes. MODE 0 appends KEY only when it is ASCII 32–126 and room remains; MODE 1 removes the last byte and clears that slot; MODE 2 clears all eight slots and length, even if the old length is corrupt. STATUS is 1 for a change/clear, 0 for full append or empty Backspace, 2 for a rejected character, and 3 for an invalid mode/length. Apart from clear, LENGTH above TEXT_CAP rejects without touching the buffer. The maintained capacities are eight and four.
Reusable initialisation and service
; SPDX-License-Identifier: MIT
; A Counted Text-entry Buffer. Contiguous private bytes: LENGTH, STATUS, KEY, MODE, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7.
; 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.
text_entry_buffer_init:
clr.b LENGTH
clr.b STATUS
clr.b KEY
clr.b MODE
clr.b BUF0
clr.b BUF1
clr.b BUF2
clr.b BUF3
clr.b BUF4
clr.b BUF5
clr.b BUF6
clr.b BUF7
rts
text_entry_buffer_step:
clr.b STATUS
cmp.b #2,MODE
beq.w text_clear
cmp.b #TEXT_CAP,LENGTH
bhi.s text_bad
tst.b MODE
beq.s text_append
cmp.b #1,MODE
bne.s text_bad
tst.b LENGTH
beq.s text_done
subq.b #1,LENGTH
moveq #0,d0
move.b LENGTH,d0
lea BUF0,a0
clr.b 0(a0,d0.w)
bra.s text_changed
text_append:
move.b KEY,d1
cmp.b #32,d1
blo.s text_bad_key
cmp.b #126,d1
bhi.s text_bad_key
cmp.b #TEXT_CAP,LENGTH
bhs.s text_done
moveq #0,d0
move.b LENGTH,d0
lea BUF0,a0
move.b d1,0(a0,d0.w)
addq.b #1,LENGTH
text_changed:
move.b #1,STATUS
text_done:
rts
text_bad_key:
move.b #2,STATUS
rts
text_bad:
move.b #3,STATUS
rts
text_clear:
lea BUF0,a0
moveq #7,d0
text_clear_loop:
clr.b (a0)+
dbra d0,text_clear_loop
clr.b LENGTH
bra.s text_changed
component_end:State, registers and ownership
Four control/input/output bytes followed by eight reserved character bytes. KEY and MODE survive. Appending preserves inactive slots; Backspace clears the removed slot, and clear empties all eight. The custom smaller capacity retains eight-byte storage and changes accepted length, not the allocation.
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 text_entry_buffer_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:
LENGTH: dc.b 0
STATUS: dc.b 0
KEY: dc.b 0
MODE: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: 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 #0,MODE
move.b #65,KEY
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_0_custom
tst.b LENGTH
bne.s bad_text_regular_0_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_0_custom
bad_text_regular_0_custom:
bsr checked_step
bad_text_done_0_custom:
else
bsr checked_step
endif
bsr emit_state
move.b #66,KEY
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_1_custom
tst.b LENGTH
bne.s bad_text_regular_1_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_1_custom
bad_text_regular_1_custom:
bsr checked_step
bad_text_done_1_custom:
else
bsr checked_step
endif
bsr emit_state
move.b #1,MODE
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_2_custom
tst.b LENGTH
bne.s bad_text_regular_2_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_2_custom
bad_text_regular_2_custom:
bsr checked_step
bad_text_done_2_custom:
else
bsr checked_step
endif
bsr emit_state
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_3_custom
tst.b LENGTH
bne.s bad_text_regular_3_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_3_custom
bad_text_regular_3_custom:
bsr checked_step
bad_text_done_3_custom:
else
bsr checked_step
endif
bsr emit_state
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_4_custom
tst.b LENGTH
bne.s bad_text_regular_4_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_4_custom
bad_text_regular_4_custom:
bsr checked_step
bad_text_done_4_custom:
else
bsr checked_step
endif
bsr emit_state
move.b #0,MODE
move.b #67,KEY
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_5_custom
tst.b LENGTH
bne.s bad_text_regular_5_custom
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_5_custom
bad_text_regular_5_custom:
bsr checked_step
bad_text_done_5_custom:
else
bsr checked_step
endif
bsr emit_state
else
move.b #0,MODE
move.b #65,KEY
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_0
tst.b LENGTH
bne.s bad_text_regular_0
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_0
bad_text_regular_0:
bsr checked_step
bad_text_done_0:
else
bsr checked_step
endif
bsr emit_state
move.b #66,KEY
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_1
tst.b LENGTH
bne.s bad_text_regular_1
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_1
bad_text_regular_1:
bsr checked_step
bad_text_done_1:
else
bsr checked_step
endif
bsr emit_state
move.b #1,MODE
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_2
tst.b LENGTH
bne.s bad_text_regular_2
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_2
bad_text_regular_2:
bsr checked_step
bad_text_done_2:
else
bsr checked_step
endif
bsr emit_state
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_3
tst.b LENGTH
bne.s bad_text_regular_3
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_3
bad_text_regular_3:
bsr checked_step
bad_text_done_3:
else
bsr checked_step
endif
bsr emit_state
ifne BROKEN
cmp.b #1,MODE
bne.s bad_text_regular_4
tst.b LENGTH
bne.s bad_text_regular_4
subq.b #1,LENGTH
move.b #1,STATUS
bra.s bad_text_done_4
bad_text_regular_4:
bsr checked_step
bad_text_done_4:
else
bsr checked_step
endif
bsr emit_state
endif
rtsThe display fields are LENGTH, STATUS, KEY, MODE, BUF0, BUF1, BUF2, BUF3; later state bytes are retained in the full packet. Each is one hexadecimal byte. The normal row is 00 00 42 01 00 00 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 custom build lowers TEXT_CAP from eight to four and its client appends C after clearing the two-character example with Backspace. It finishes with the one-character name C. Boundary cases also exercise full/invalid lengths under the smaller capacity.
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:
LENGTH: dc.b 0
STATUS: dc.b 0
KEY: dc.b 0
MODE: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: 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 01 43 00 43 00 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 decrements an empty length on Backspace. Zero wraps to 255, making the supposed name length exceed the entire buffer. Keep zero at zero; subsequent operations on a corrupt length must reject or explicitly clear it.
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:
LENGTH: dc.b 0
STATUS: dc.b 0
KEY: dc.b 0
MODE: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: 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 246 code bytes, 0 immutable data bytes and 12 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.
Append and Backspace touch at most one slot. Clear touches the eight reserved slots. Bounds and key checks are part of the implementation; removing them creates a different trust contract and can corrupt neighbouring state.
Cursor movement, insertion in the middle, key mapping, accented characters and Unicode require additional rules and often more storage. ASCII here is an interchange choice; C64 screen codes and NES tile numbers need a presentation mapping. Do not scan past the counted span looking for a terminator.
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.