Climbing should suspend gravity, but jumping away must hand movement back to the ordinary player controller.
Use it in a project
MODE is 0 ordinary or 1 climbing. POSITION is an unsigned vertical coordinate between inclusive MINIMUM and MAXIMUM. A nonzero ON_LADDER means the caller has established ladder contact. Up or down enters climbing; contradictory buttons hold still. Climbing moves one unit per service and clamps to the limits. JUMP exits and emits JUMPED=1 only while climbing. Losing contact exits. GRAVITY=1 in ordinary mode and zero while climbing. Invalid mode or coordinate bounds clears VALID and leaves MODE/POSITION unchanged; outputs are otherwise cleared.
Include component.inc once (MOS callers include the shared 6502 implementation through it). Reserve the public fields in this exact order: MODE, POSITION, GRAVITY, JUMPED, VALID, ON_LADDER, UP, DOWN, JUMP, MINIMUM, MAXIMUM. They occupy 11 contiguous bytes. Also reserve the private workspace: none (0 bytes). Array names in the explanation refer to the numbered consecutive bindings, such as C0, C1 and so on.
Call ladder_controller_init once at the intended reset boundary. It clears inputs as well as outputs and workspace. Set your starting state and configuration afterwards, then call ladder_controller_step whenever the described event occurs. The helper reads no device, waits for no frame and installs no interrupt handler.
| Ownership | Fields |
|---|---|
| Retain between calls | MODE and POSITION |
| Supply before service | contact, buttons and bounds |
| Read after service | MODE, POSITION, GRAVITY, JUMPED and VALID |
Contact controls whether climbing is possible; buttons request entry, and jump explicitly returns ownership to normal motion. Contradictory climb buttons hold rather than biasing one direction.
Reusable initialisation and service
; SPDX-License-Identifier: MIT
; Enter and Leave a Ladder. See README.md for the byte interface and ownership.
; init clears the public fields and private workspace; set inputs afterwards.
ladder_controller_init:
ld a,0
ld (MODE),a
ld (POSITION),a
ld (GRAVITY),a
ld (JUMPED),a
ld (VALID),a
ld (ON_LADDER),a
ld (UP),a
ld (DOWN),a
ld (JUMP),a
ld (MINIMUM),a
ld (MAXIMUM),a
ret
ladder_controller_step:
; GRAVITY = 0
ld a,0
ld (GRAVITY),a
; JUMPED = 0
ld a,0
ld (JUMPED),a
; VALID = 0
ld a,0
ld (VALID),a
; if MODE > 1:
ld a,(MODE)
cp 1
jp z,ladder_controller_L2
jp nc,ladder_controller_L1
jp ladder_controller_L2
ladder_controller_L1:
; return
ret
jp ladder_controller_L3
ladder_controller_L2:
ladder_controller_L3:
; if MINIMUM > POSITION:
ld a,(MINIMUM)
ld b,a
ld a,(POSITION)
ld c,a
ld a,b
cp c
jp z,ladder_controller_L5
jp nc,ladder_controller_L4
jp ladder_controller_L5
ladder_controller_L4:
; return
ret
jp ladder_controller_L6
ladder_controller_L5:
ladder_controller_L6:
; if POSITION > MAXIMUM:
ld a,(POSITION)
ld b,a
ld a,(MAXIMUM)
ld c,a
ld a,b
cp c
jp z,ladder_controller_L8
jp nc,ladder_controller_L7
jp ladder_controller_L8
ladder_controller_L7:
; return
ret
jp ladder_controller_L9
ladder_controller_L8:
ladder_controller_L9:
; VALID = 1
ld a,1
ld (VALID),a
; if ON_LADDER == 0:
ld a,(ON_LADDER)
cp 0
jp z,ladder_controller_L10
jp ladder_controller_L11
ladder_controller_L10:
; MODE = 0
ld a,0
ld (MODE),a
jp ladder_controller_L12
ladder_controller_L11:
; if MODE == 0:
ld a,(MODE)
cp 0
jp z,ladder_controller_L13
jp ladder_controller_L14
ladder_controller_L13:
; if UP != 0:
ld a,(UP)
cp 0
jp nz,ladder_controller_L16
jp ladder_controller_L17
ladder_controller_L16:
; MODE = 1
ld a,1
ld (MODE),a
jp ladder_controller_L18
ladder_controller_L17:
ladder_controller_L18:
; if DOWN != 0:
ld a,(DOWN)
cp 0
jp nz,ladder_controller_L19
jp ladder_controller_L20
ladder_controller_L19:
; MODE = 1
ld a,1
ld (MODE),a
jp ladder_controller_L21
ladder_controller_L20:
ladder_controller_L21:
jp ladder_controller_L15
ladder_controller_L14:
ladder_controller_L15:
; if MODE == 1:
ld a,(MODE)
cp 1
jp z,ladder_controller_L22
jp ladder_controller_L23
ladder_controller_L22:
; if JUMP != 0:
ld a,(JUMP)
cp 0
jp nz,ladder_controller_L25
jp ladder_controller_L26
ladder_controller_L25:
; MODE = 0
ld a,0
ld (MODE),a
; JUMPED = 1
ld a,1
ld (JUMPED),a
jp ladder_controller_L27
ladder_controller_L26:
; if UP != 0:
ld a,(UP)
cp 0
jp nz,ladder_controller_L28
jp ladder_controller_L29
ladder_controller_L28:
; if DOWN == 0:
ld a,(DOWN)
cp 0
jp z,ladder_controller_L31
jp ladder_controller_L32
ladder_controller_L31:
; if POSITION > MINIMUM:
ld a,(POSITION)
ld b,a
ld a,(MINIMUM)
ld c,a
ld a,b
cp c
jp z,ladder_controller_L35
jp nc,ladder_controller_L34
jp ladder_controller_L35
ladder_controller_L34:
; POSITION = POSITION - 1
ld a,(POSITION)
sub 1
ld (POSITION),a
jp ladder_controller_L36
ladder_controller_L35:
ladder_controller_L36:
jp ladder_controller_L33
ladder_controller_L32:
ladder_controller_L33:
jp ladder_controller_L30
ladder_controller_L29:
; if DOWN != 0:
ld a,(DOWN)
cp 0
jp nz,ladder_controller_L37
jp ladder_controller_L38
ladder_controller_L37:
; if POSITION < MAXIMUM:
ld a,(POSITION)
ld b,a
ld a,(MAXIMUM)
ld c,a
ld a,b
cp c
jp c,ladder_controller_L40
jp ladder_controller_L41
ladder_controller_L40:
; POSITION = POSITION + 1
ld a,(POSITION)
add a,1
ld (POSITION),a
jp ladder_controller_L42
ladder_controller_L41:
ladder_controller_L42:
jp ladder_controller_L39
ladder_controller_L38:
ladder_controller_L39:
ladder_controller_L30:
ladder_controller_L27:
jp ladder_controller_L24
ladder_controller_L23:
ladder_controller_L24:
ladder_controller_L12:
; if MODE == 0:
ld a,(MODE)
cp 0
jp z,ladder_controller_L43
jp ladder_controller_L44
ladder_controller_L43:
; GRAVITY = 1
ld a,1
ld (GRAVITY),a
jp ladder_controller_L45
ladder_controller_L44:
ladder_controller_L45:
ret
component_end:Machine contract
AF/BC/DE/HL may change; IX/IY are preserved. A direct CALL needs two return-address stack bytes. The helper makes no nested calls and adds no other stack use. Its named scratch is private workspace, not a pointer, a ROM variable or shared zero-page space that the game may borrow concurrently. The samples use fixed symbol bindings. Scope or rename every label and binding, including the component_end measurement marker, and allocate a separate block for each independent instance. Different helpers can also use common field names, so combining them needs separate namespaces or explicitly renamed bindings. Give each block one mutation owner.
The 48K diagnostic boots through ROM tape loading and USR, disables interrupts and owns the screen. The helper performs no port or screen writes.
Adapt the caller
demo.asm supplies the bindings and include order. exercise.inc first runs table cases, then a separate client retaining state between calls. A game can call the public step entry directly and remove the diagnostic packet and display. Do not copy the diagnostic’s hardware takeover into an existing game loop.
Build with make ASM198X=/path/to/asm198x. The Makefile produces normal, custom, deliberately wrong and repaired programs. Tools must already be installed; the sample downloads nothing.
Bindings and include order
org $8000
CUSTOM equ 0
BROKEN equ 0
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
MODE: defb 0
POSITION: defb 0
GRAVITY: defb 0
JUMPED: defb 0
VALID: defb 0
ON_LADDER: defb 0
UP: defb 0
DOWN: defb 0
JUMP: defb 0
MINIMUM: defb 0
MAXIMUM: 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 client retaining state between calls
preview_rules:
if CUSTOM
; POSITION = 19
ld a,19
ld (POSITION),a
; MAXIMUM = 20
ld a,20
ld (MAXIMUM),a
; ON_LADDER = 1
ld a,1
ld (ON_LADDER),a
; DOWN = 1
ld a,1
ld (DOWN),a
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
ret
else
; POSITION = 10
ld a,10
ld (POSITION),a
; MAXIMUM = 20
ld a,20
ld (MAXIMUM),a
; ON_LADDER = 1
ld a,1
ld (ON_LADDER),a
; UP = 1
ld a,1
ld (UP),a
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
; JUMP = 1
ld a,1
ld (JUMP),a
if BROKEN
; ON_LADDER = 0
ld a,0
ld (ON_LADDER),a
endif
call checked_step
call emit_state
endif
retCustomise it
Climb down to the bottom bound, then leave the ladder volume. The maintained custom caller changes its inputs or client sequence rather than hiding a different implementation behind the same label. Compare every state of the two clients, not only their final display.
Custom client selection
org $8000
CUSTOM equ 1
BROKEN equ 0
COYOTE_STEPS equ 2
BUFFER_STEPS equ 2
TEXT_CAP equ 4
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 49
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
MODE: defb 0
POSITION: defb 0
GRAVITY: defb 0
JUMPED: defb 0
VALID: defb 0
ON_LADDER: defb 0
UP: defb 0
DOWN: defb 0
JUMP: defb 0
MINIMUM: defb 0
MAXIMUM: 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 custom diagnostic row is 00 14 01 00 01 00 00 01. The full client trace in the source explains how it gets there.
Mistake and repair
The wrong client discards established ladder contact. Climb requests keep ordinary mode and gravity active instead of moving up. Supply collision-derived contact before service.
The BROKEN branch lives in the sequential client, not the reusable helper. wrong.asm selects it; repaired.asm restores the normal call sequence. The repaired executable matches the normal program (for Spectrum, compare loaded CODE rather than the tape filename).
Select the deliberately wrong client
org $8000
CUSTOM equ 0
BROKEN equ 1
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
MODE: defb 0
POSITION: defb 0
GRAVITY: defb 0
JUMPED: defb 0
VALID: defb 0
ON_LADDER: defb 0
UP: defb 0
DOWN: defb 0
JUMP: defb 0
MINIMUM: defb 0
MAXIMUM: 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
Cost and alternatives
The measured helper extent is 348 code bytes; public state is 11 bytes and private scratch is 0 bytes. There are no immutable helper tables. Caller data, the test cases, return-address stack, alignment and display buffers cost additional space. These are assembled sizes, not cycle measurements.
Constant bounded work and no map accesses. Pixel collision and animation remain separate costs. A faster climb can use a bounded delta, but needs clipping against both world obstacles and coordinate limits.
This selects a movement mode, not ladder collision geometry or full vertical physics. Apply ordinary gravity only when GRAVITY is set, and consume JUMPED to initialise the existing jump velocity. A world collision solver must still decide whether the proposed climb is possible.
Execution evidence
Four variants run on 48K PAL ROM tape load and USR, using Asm198x 0.0.72, Emu198x 0.44.2. Each executes 64 boundary/varied/error table cases, dirty initialisation and the separate retained-state client. An independent mathematical/container model checks every public byte after every call. This is bounded example coverage, not exhaustive correctness for every possible state.
The records retain loaded immutable code, completion, register sentinels, full packets, source/tool/firmware hashes and captures. The public gate validates these retained observations and rejects altered evidence; it does not run restricted firmware. No firmware is distributed. The eight displayed bytes are the first eight public fields, zero-padded when shorter; the packet includes every field.
Where it fits
Bounded acceleration: Use the ordinary motion helper only when this controller enables gravity.