A key collected, a door unlocked, a conversation finished: eight yes/no facts fit in one byte. A mask lets you change one fact without erasing its neighbours, or ask whether a group of requirements has been met.
Include, initialise and call
Bind FLAGS, MASK, MODE, ALL_SET as 4 contiguous private bytes in that order. Include the helper once. Call quest_flags_init at the deliberate reset boundary: it clears all named bytes, including inputs. Set your starting values afterwards. Call quest_flags_step when this service is needed.
Initialise once for a fresh world. Assign a power-of-two mask to each independent fact: 1, 2, 4, 8 and so on. Use MODE 0 to query without changing the world. A combined mask such as 12 asks for bits 4 and 8 together; the result means all, not any.
FLAGS stores eight independent bits. MASK selects any subset of them. MODE 1 sets those bits, MODE 2 clears them; other modes only query. After the optional change, ALL_SET is 1 exactly when every bit in MASK is present in FLAGS. An empty mask is satisfied. MASK and MODE survive.
Reusable initialisation and service
; SPDX-License-Identifier: MIT
; Quest and Inventory Flags. Bind these contiguous private bytes: FLAGS, MASK, MODE, ALL_SET.
; init clears the whole block; step uses current inputs. No I/O, waits or IRQ owner.
; AF/BC/DE/HL may change; IX/IY survive.
quest_flags_init:
xor a
ld (FLAGS),a
ld (MASK),a
ld (MODE),a
ld (ALL_SET),a
ret
quest_flags_step:
ld a,(MASK)
ld b,a
ld a,(MODE)
cp 1
jr z,flags_set
cp 2
jr nz,flags_test
ld a,b
cpl
ld b,a
ld a,(FLAGS)
and b
ld (FLAGS),a
jr flags_test
flags_set:
ld a,(FLAGS)
or b
ld (FLAGS),a
flags_test:
xor a
ld (ALL_SET),a
ld a,(MASK)
ld b,a
ld a,(FLAGS)
and b
cp b
ret nz
ld a,1
ld (ALL_SET),a
ret
component_end:State and ownership
FLAGS persists across calls. MASK and MODE are inputs. ALL_SET is replaced on each call and describes the state after any set or clear operation.
AF/BC/DE/HL may change; IX/IY survive. A direct CALL uses two return-address stack bytes.
This implementation has fixed symbol bindings and one mutation owner. Independent users need distinct state blocks and scoped/renamed bindings; including another copy with the same global labels is not sufficient. Sequential queries may reuse a scratch block only after the previous result has been consumed. Do not let an interrupt and the main loop mutate the same block without a separately designed ownership policy.
The standalone tape program starts at $8000, disables interrupts and owns bitmap/attribute RAM. It does not return to BASIC. The helper itself never disables interrupts or touches the display.
A small caller you can adapt
The standalone program includes the helper and a separate client. Its read-only table exercises 96 valid inputs, then this client initialises once and retains state between calls. Replace the supplied input changes with your own game values; the display and packet machinery are diagnostics rather than dependencies of the component.
Buildable caller, bindings and include order
org $8000
CUSTOM equ 0
BROKEN equ 0
SCORE_CAP equ 65535
QUEUE_CAP equ 4
REPEAT_DELAY equ 4
REPEAT_RATE equ 2
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
FLAGS: defb 0
MASK: defb 0
MODE: defb 0
ALL_SET: 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 startA separate client retaining state between calls
preview_rules:
if CUSTOM
ld a,1
ld (FLAGS),a
ld a,16
ld (MASK),a
ld a,1
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
ld a,0
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
ld a,2
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
else
ld a,1
ld (FLAGS),a
ld a,8
ld (MASK),a
ld a,1
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
ld a,0
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
ld a,2
ld (MODE),a
if BROKEN
ld a,3
ld (MASK),a
call checked_step
else
call checked_step
endif
call emit_state
endif
retThe eight display fields follow FLAGS, MASK, MODE, ALL_SET; unused display fields are zero. Each field is a hexadecimal byte. The working row is 01 08 02 00 00 00 00 00. The output is a completed diagnostic state, not a recording of movement, input or sound hardware.
Make it your own
The custom caller moves its example fact from mask 8 to mask 16. It leaves the unrelated mask-1 fact intact. Changing the bit assignment needs matching definitions in every user of that save/world data.
Maintained custom configuration or caller
org $8000
CUSTOM equ 1
BROKEN equ 0
SCORE_CAP equ 999
QUEUE_CAP equ 2
REPEAT_DELAY equ 6
REPEAT_RATE equ 3
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
FLAGS: defb 0
MASK: defb 0
MODE: defb 0
ALL_SET: 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 startThe observed custom row is 01 10 02 00 00 00 00 00. The retained records qualify these named configurations; a new input domain or larger layout needs its own bounds and fresh execution checks.
Common mistake and repair
The wrong client passes 3, the intended bit number, where the API expects mask 8. The binary value 3 selects the two lowest bits. Setting and later clearing it destroys the unrelated mask-1 fact. Pass a mask, not an ordinal bit number.
Deliberately wrong client selection
org $8000
CUSTOM equ 0
BROKEN equ 1
SCORE_CAP equ 65535
QUEUE_CAP equ 4
REPEAT_DELAY equ 4
REPEAT_RATE equ 2
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
FLAGS: defb 0
MASK: defb 0
MODE: defb 0
ALL_SET: 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 wrong branch is in the displayed client above, selected by BROKEN. repaired.asm selects the original client again. Its executable matches demo exactly; Spectrum tape filenames can differ while loaded CODE is identical. The bad caller is a labelled experiment, not an alternative recommended implementation.
Cost and verification
The measured helper occupies 68 code bytes plus 4 named state bytes in this layout. Return addresses, alignment, tables and display diagnostics are additional. The sizes cover init and step together, not the whole standalone program.
At most one byte of world state changes. Mask operations take bounded paths and no scan. A byte per fact costs more RAM but may make an early project easier to inspect.
More than eight facts need a larger byte array plus an index/mask lookup. Counters belong in counters: a flag cannot hold three arrows. Shared interrupt/main-loop updates need an ownership or critical-section policy because these read/modify/write sequences are not atomic transactions.
Four native runs use Spectrum 48K with stock ROM tape loading and USR entry; Asm198x 0.0.72 and Emu198x 0.44.2. Every run checks 96 table results, dirty initialisation and every state in a separate sequential trace against an independent integer model. This is boundary/varied-input qualification, not exhaustive coverage of every byte combination. Source/tool/firmware hashes, native startup and completion, preserved-register sentinels, immutable loaded code, actual helper extent, capture bytes and pixels, and exact repair are checked. Deliberately changed observations must fail. Firmware is hashed, never distributed.