Approach a Target Without Overshoot on Spectrum | Pattern Library

An enemy can move towards a waypoint without orbiting it forever. Move by the smaller of the remaining distance and your allowed step, then report arrival. That last short step matters when the target is not an exact multiple of the speed.

Spectrum shows the working result FF FF 0A 01 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 POSITION, TARGET, STEP, ARRIVED as 4 contiguous private bytes in that order. Include the helper once. Call approach_target_init at the deliberate reset boundary: it clears all named bytes, including inputs. Set your starting values afterwards. Call approach_target_step when this service is needed.

Initialise, then set the position, target and allowed step. Call once per simulation update. Change TARGET to follow a moving goal, or choose the next waypoint only after ARRIVED. Use another state block for the second axis if independent axis movement is the intended policy.

POSITION, TARGET and STEP are unsigned bytes. Step moves POSITION towards TARGET by at most STEP, without wrapping or overshooting, and replaces ARRIVED with 1 exactly when the resulting position equals TARGET. STEP zero stops movement but still reports an already reached target. TARGET and STEP survive.

Reusable initialisation and service

component.inc

; SPDX-License-Identifier: MIT
; Approach a Target Without Overshoot. Bind these contiguous private bytes: POSITION, TARGET, STEP, ARRIVED.
; 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.
approach_target_init:
    xor a
    ld (POSITION),a
    ld (TARGET),a
    ld (STEP),a
    ld (ARRIVED),a
    ret
approach_target_step:
    xor a
    ld (ARRIVED),a
    ld a,(TARGET)
    ld b,a
    ld a,(POSITION)
    cp b
    jr z,approach_arrived
    jr c,approach_up
    sub b
    ld b,a
    ld a,(STEP)
    cp b
    jr nc,approach_snap
    ld b,a
    ld a,(POSITION)
    sub b
    ld (POSITION),a
    ret
approach_up:
    ld c,a
    ld a,b
    sub c
    ld b,a
    ld a,(STEP)
    cp b
    jr nc,approach_snap
    add a,c
    ld (POSITION),a
    ret
approach_snap:
    ld a,(TARGET)
    ld (POSITION),a
approach_arrived:
    ld a,1
    ld (ARRIVED),a
    ret
component_end:

State and ownership

POSITION persists. TARGET and STEP are inputs. ARRIVED describes the resulting position and stays true on repeated calls at the target; it is not a one-time arrival event. Detect its edge if an action should occur only once.

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:
POSITION: defb 0
TARGET: defb 0
STEP: defb 0
ARRIVED: 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,250
    ld (POSITION),a
    ld a,255
    ld (TARGET),a
    ld a,2
    ld (STEP),a
    if BROKEN
    ld a,(STEP)
    ld b,a
    ld a,(POSITION)
    add a,b
    ld (POSITION),a
    ld b,a
    xor a
    ld (ARRIVED),a
    ld a,(TARGET)
    cp b
    jr nz,trace_bad_end_0_custom
    ld a,1
    ld (ARRIVED),a
trace_bad_end_0_custom:
    else
    call checked_step
    endif
    call emit_state
    if BROKEN
    ld a,(STEP)
    ld b,a
    ld a,(POSITION)
    add a,b
    ld (POSITION),a
    ld b,a
    xor a
    ld (ARRIVED),a
    ld a,(TARGET)
    cp b
    jr nz,trace_bad_end_1_custom
    ld a,1
    ld (ARRIVED),a
trace_bad_end_1_custom:
    else
    call checked_step
    endif
    call emit_state
    else
    ld a,250
    ld (POSITION),a
    ld a,255
    ld (TARGET),a
    ld a,10
    ld (STEP),a
    if BROKEN
    ld a,(STEP)
    ld b,a
    ld a,(POSITION)
    add a,b
    ld (POSITION),a
    ld b,a
    xor a
    ld (ARRIVED),a
    ld a,(TARGET)
    cp b
    jr nz,trace_bad_end_0
    ld a,1
    ld (ARRIVED),a
trace_bad_end_0:
    else
    call checked_step
    endif
    call emit_state
    if BROKEN
    ld a,(STEP)
    ld b,a
    ld a,(POSITION)
    add a,b
    ld (POSITION),a
    ld b,a
    xor a
    ld (ARRIVED),a
    ld a,(TARGET)
    cp b
    jr nz,trace_bad_end_1
    ld a,1
    ld (ARRIVED),a
trace_bad_end_1:
    else
    call checked_step
    endif
    call emit_state
    endif
    ret

The eight display fields follow POSITION, TARGET, STEP, ARRIVED; unused display fields are zero. Each field is a hexadecimal byte. The working row is FF FF 0A 01 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 reduces STEP from ten to two. Starting at 250 with target 255, the two calls end at 254 without arrival; a later call would take the last one-unit step.

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:
POSITION: defb 0
TARGET: defb 0
STEP: defb 0
ARRIVED: 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 FE FF 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 replaces the helper with an unconditional byte addition. Starting at 250, adding ten wraps to 4, then 14, moving away from target 255. Compare the remaining distance before adding or subtracting; increasing the target tolerance does not fix byte overflow.

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:
POSITION: defb 0
TARGET: defb 0
STEP: defb 0
ARRIVED: 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 0E FF 0A 00 00 00 00 00. — The wrong client completes and records 0E FF 0A 00 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 74 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.

One comparison chooses direction, then a distance comparison chooses a full or short step. No multiplication, division or path search occurs. This is straight-axis pursuit, not obstacle-aware navigation.

Signed coordinates, wider worlds and fixed-point subpixels need wider arithmetic and explicit bounds. Moving both axes by the same maximum gives faster diagonal travel in Euclidean distance; normalisation or an axis budget is a separate movement policy. Collision may still block a proposed position.

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.

Source and native evidence.