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.
; A/X/flags change; Y and decimal mode survive. D=0 for binary arithmetic.
text_entry_buffer_init:
lda #0
sta LENGTH
sta STATUS
sta KEY
sta MODE
sta BUF0
sta BUF1
sta BUF2
sta BUF3
sta BUF4
sta BUF5
sta BUF6
sta BUF7
rts
text_entry_buffer_step:
lda #0
sta STATUS
lda MODE
cmp #2
beq text_clear
lda LENGTH
cmp #TEXT_CAP
bcc text_mode
beq text_mode
jmp text_bad
text_mode:
lda MODE
beq text_append
cmp #1
bne text_bad
ldx LENGTH
beq text_done
dex
stx LENGTH
lda #0
sta BUF0,x
jmp text_changed
text_append:
lda KEY
cmp #32
bcc text_bad_key
cmp #127
bcs text_bad_key
ldx LENGTH
cpx #TEXT_CAP
bcs text_done
sta BUF0,x
inc LENGTH
text_changed:
lda #1
sta STATUS
text_done:
rts
text_bad_key:
lda #2
sta STATUS
rts
text_bad:
lda #3
sta STATUS
rts
text_clear:
ldx #7
lda #0
text_clear_loop:
sta BUF0,x
dex
bpl text_clear_loop
sta LENGTH
jmp 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.
A/X/flags may change; Y and decimal mode survive. Clear decimal mode before binary arithmetic; the caller uses CLD. 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 cartridge owns its background/font and test RAM layout. Its bounded packet, preview and completion marker fit below the end of the NES’s 2 KiB internal RAM. The helper itself owns no PPU, DMA or audio registers.
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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
LENGTH=$80
STATUS=$81
KEY=$82
MODE=$83
BUF0=$84
BUF1=$85
BUF2=$86
BUF3=$87
BUF4=$88
BUF5=$89
BUF6=$8a
BUF7=$8b
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0A separate client retaining state between calls
preview_rules:
.if CUSTOM
lda #0
sta MODE
lda #65
sta KEY
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_0_custom
lda LENGTH
bne bad_text_regular_0_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_0_custom
bad_text_regular_0_custom:
jsr checked_step
bad_text_done_0_custom:
.else
jsr checked_step
.endif
jsr emit_state
lda #66
sta KEY
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_1_custom
lda LENGTH
bne bad_text_regular_1_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_1_custom
bad_text_regular_1_custom:
jsr checked_step
bad_text_done_1_custom:
.else
jsr checked_step
.endif
jsr emit_state
lda #1
sta MODE
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_2_custom
lda LENGTH
bne bad_text_regular_2_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_2_custom
bad_text_regular_2_custom:
jsr checked_step
bad_text_done_2_custom:
.else
jsr checked_step
.endif
jsr emit_state
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_3_custom
lda LENGTH
bne bad_text_regular_3_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_3_custom
bad_text_regular_3_custom:
jsr checked_step
bad_text_done_3_custom:
.else
jsr checked_step
.endif
jsr emit_state
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_4_custom
lda LENGTH
bne bad_text_regular_4_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_4_custom
bad_text_regular_4_custom:
jsr checked_step
bad_text_done_4_custom:
.else
jsr checked_step
.endif
jsr emit_state
lda #0
sta MODE
lda #67
sta KEY
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_5_custom
lda LENGTH
bne bad_text_regular_5_custom
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_5_custom
bad_text_regular_5_custom:
jsr checked_step
bad_text_done_5_custom:
.else
jsr checked_step
.endif
jsr emit_state
.else
lda #0
sta MODE
lda #65
sta KEY
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_0
lda LENGTH
bne bad_text_regular_0
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_0
bad_text_regular_0:
jsr checked_step
bad_text_done_0:
.else
jsr checked_step
.endif
jsr emit_state
lda #66
sta KEY
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_1
lda LENGTH
bne bad_text_regular_1
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_1
bad_text_regular_1:
jsr checked_step
bad_text_done_1:
.else
jsr checked_step
.endif
jsr emit_state
lda #1
sta MODE
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_2
lda LENGTH
bne bad_text_regular_2
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_2
bad_text_regular_2:
jsr checked_step
bad_text_done_2:
.else
jsr checked_step
.endif
jsr emit_state
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_3
lda LENGTH
bne bad_text_regular_3
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_3
bad_text_regular_3:
jsr checked_step
bad_text_done_3:
.else
jsr checked_step
.endif
jsr emit_state
.if BROKEN
lda MODE
cmp #1
bne bad_text_regular_4
lda LENGTH
bne bad_text_regular_4
dec LENGTH
lda #1
sta STATUS
jmp bad_text_done_4
bad_text_regular_4:
jsr checked_step
bad_text_done_4:
.else
jsr checked_step
.endif
jsr 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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
LENGTH=$80
STATUS=$81
KEY=$82
MODE=$83
BUF0=$84
BUF1=$85
BUF2=$86
BUF3=$87
BUF4=$88
BUF5=$89
BUF6=$8a
BUF7=$8b
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
LENGTH=$80
STATUS=$81
KEY=$82
MODE=$83
BUF0=$84
BUF1=$85
BUF2=$86
BUF3=$87
BUF4=$88
BUF5=$89
BUF6=$8a
BUF7=$8b
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,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 119 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 NTSC mapper-0 NES cartridge, CHR-ROM diagnostic font, NMI/DMC disabled; 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.