Code Like It's 198x

Resource Counters on Spectrum

An empty magazine should refuse a shot, not turn into 255 rounds.

An empty magazine should refuse a shot, not turn into 255 rounds. A full energy meter should stay full when you collect another recharge. This small counter gives those two operations different rules: refill saturates at 255; spending succeeds in full or leaves the balance alone.

Spectrum shows the working result 05 06 01 00 00 00 00 00.
The completed native caller shows hexadecimal state bytes. The field order below explains the result; the full verification packet retains every call.

Include, initialise and call

Bind BALANCE, AMOUNT, MODE, OK as 4 contiguous private bytes in that order. Include the helper once. Call resource_wallet_init at the deliberate reset boundary: it clears all named bytes, including inputs. Set your starting values afterwards. Call resource_wallet_step when this service is needed.

Initialise once, then set the starting balance. Try a spend before creating the effect; consume OK immediately. A rejected request leaves all the resource available for a later affordable action. The helper does not spawn a projectile, reserve an object slot or coordinate another writer.

Set BALANCE to the current unsigned amount, AMOUNT to the requested change and MODE to 0 for refill or 1 for spend. Call step, then read OK: 1 means the operation was accepted, 0 means an unaffordable spend or an unknown mode. A zero-amount refill or spend is valid and succeeds. Other MODE values leave BALANCE alone and clear OK. AMOUNT and MODE survive.

Reusable initialisation and service

component.inc
; SPDX-License-Identifier: MIT
; Resource Counters. Bind these contiguous private bytes: BALANCE, AMOUNT, MODE, OK.
; 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.
resource_wallet_init:
    xor a
    ld (BALANCE),a
    ld (AMOUNT),a
    ld (MODE),a
    ld (OK),a
    ret
resource_wallet_step:
    xor a
    ld (OK),a
    ld a,(MODE)
    or a
    jr z,wallet_add
    cp 1
    ret nz
    ld a,(AMOUNT)
    ld b,a
    ld a,(BALANCE)
    sub b
    ret c
    jr wallet_store
wallet_add:
    ld a,(AMOUNT)
    ld b,a
    ld a,(BALANCE)
    add a,b
    jr nc,wallet_store
    ld a,255
wallet_store:
    ld (BALANCE),a
    ld a,1
    ld (OK),a
    ret
component_end:

State and ownership

BALANCE is persistent resource state; AMOUNT and MODE are caller inputs; OK is replaced on every call.

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

demo.asm
    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:
BALANCE: defb 0
AMOUNT: defb 0
MODE: defb 0
OK: 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,3
    ld (BALANCE),a
    ld a,2
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,255
    ld (AMOUNT),a
    ld a,0
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,250
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,6
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    else
    ld a,3
    ld (BALANCE),a
    ld a,5
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,255
    ld (AMOUNT),a
    ld a,0
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,250
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    ld a,6
    ld (AMOUNT),a
    ld a,1
    ld (MODE),a
    if BROKEN
    ld a,0
    ld (MODE),a
    call checked_step
    else
    call checked_step
    endif
    call emit_state
    endif
    ret

The eight display fields follow BALANCE, AMOUNT, MODE, OK; unused display fields are zero. Each field is a hexadecimal byte. The working row is 05 06 01 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 changes the first spend from five units to two. It succeeds from a balance of three; the later refill still saturates and the later unaffordable spend is still rejected.

Maintained custom configuration or caller

custom.asm
    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:
BALANCE: defb 0
AMOUNT: defb 0
MODE: defb 0
OK: 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 observed custom row is 05 06 01 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 labels every request as a refill by replacing MODE with zero. Spending now increases the balance, so an emptying sequence ends at 255. Preserve the requested operation and let the affordability check decide whether to spend.

Deliberately wrong client selection

wrong.asm
    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:
BALANCE: defb 0
AMOUNT: defb 0
MODE: defb 0
OK: 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 result FF 06 00 01 00 00 00 00.
The wrong client completes and records FF 06 00 01 00 00 00 00. Compare its state with the working row and the explained failure.

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 59 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.

Refill and spend take bounded branch paths, with no search or loop. Two output bytes can change. A simple decrement is smaller when running out is impossible, but cannot enforce affordability.

For a smaller capacity, clamp refills to an explicit capacity instead of 255 and qualify both the new cap and the initial-balance invariant. Multiple resource types need separate state. Transactions involving both ammo and object slots need an explicit reservation/commit policy; OK is not a lock.

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.

Related reusable technique · Maths for Games · The Craft.

Source and native evidence.