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:
move.b #0,d0
move.b d0,MODE
move.b d0,POSITION
move.b d0,GRAVITY
move.b d0,JUMPED
move.b d0,VALID
move.b d0,ON_LADDER
move.b d0,UP
move.b d0,DOWN
move.b d0,JUMP
move.b d0,MINIMUM
move.b d0,MAXIMUM
rts
ladder_controller_step:
; GRAVITY = 0
move.b #0,d0
move.b d0,GRAVITY
; JUMPED = 0
move.b #0,d0
move.b d0,JUMPED
; VALID = 0
move.b #0,d0
move.b d0,VALID
; if MODE > 1:
move.b MODE,d0
cmp.b #1,d0
bhi ladder_controller_L1
jmp ladder_controller_L2
ladder_controller_L1:
; return
rts
jmp ladder_controller_L3
ladder_controller_L2:
ladder_controller_L3:
; if MINIMUM > POSITION:
move.b MINIMUM,d0
move.b POSITION,d1
cmp.b d1,d0
bhi ladder_controller_L4
jmp ladder_controller_L5
ladder_controller_L4:
; return
rts
jmp ladder_controller_L6
ladder_controller_L5:
ladder_controller_L6:
; if POSITION > MAXIMUM:
move.b POSITION,d0
move.b MAXIMUM,d1
cmp.b d1,d0
bhi ladder_controller_L7
jmp ladder_controller_L8
ladder_controller_L7:
; return
rts
jmp ladder_controller_L9
ladder_controller_L8:
ladder_controller_L9:
; VALID = 1
move.b #1,d0
move.b d0,VALID
; if ON_LADDER == 0:
move.b ON_LADDER,d0
cmp.b #0,d0
beq ladder_controller_L10
jmp ladder_controller_L11
ladder_controller_L10:
; MODE = 0
move.b #0,d0
move.b d0,MODE
jmp ladder_controller_L12
ladder_controller_L11:
; if MODE == 0:
move.b MODE,d0
cmp.b #0,d0
beq ladder_controller_L13
jmp ladder_controller_L14
ladder_controller_L13:
; if UP != 0:
move.b UP,d0
cmp.b #0,d0
bne ladder_controller_L16
jmp ladder_controller_L17
ladder_controller_L16:
; MODE = 1
move.b #1,d0
move.b d0,MODE
jmp ladder_controller_L18
ladder_controller_L17:
ladder_controller_L18:
; if DOWN != 0:
move.b DOWN,d0
cmp.b #0,d0
bne ladder_controller_L19
jmp ladder_controller_L20
ladder_controller_L19:
; MODE = 1
move.b #1,d0
move.b d0,MODE
jmp ladder_controller_L21
ladder_controller_L20:
ladder_controller_L21:
jmp ladder_controller_L15
ladder_controller_L14:
ladder_controller_L15:
; if MODE == 1:
move.b MODE,d0
cmp.b #1,d0
beq ladder_controller_L22
jmp ladder_controller_L23
ladder_controller_L22:
; if JUMP != 0:
move.b JUMP,d0
cmp.b #0,d0
bne ladder_controller_L25
jmp ladder_controller_L26
ladder_controller_L25:
; MODE = 0
move.b #0,d0
move.b d0,MODE
; JUMPED = 1
move.b #1,d0
move.b d0,JUMPED
jmp ladder_controller_L27
ladder_controller_L26:
; if UP != 0:
move.b UP,d0
cmp.b #0,d0
bne ladder_controller_L28
jmp ladder_controller_L29
ladder_controller_L28:
; if DOWN == 0:
move.b DOWN,d0
cmp.b #0,d0
beq ladder_controller_L31
jmp ladder_controller_L32
ladder_controller_L31:
; if POSITION > MINIMUM:
move.b POSITION,d0
move.b MINIMUM,d1
cmp.b d1,d0
bhi ladder_controller_L34
jmp ladder_controller_L35
ladder_controller_L34:
; POSITION = POSITION - 1
move.b POSITION,d0
sub.b #1,d0
move.b d0,POSITION
jmp ladder_controller_L36
ladder_controller_L35:
ladder_controller_L36:
jmp ladder_controller_L33
ladder_controller_L32:
ladder_controller_L33:
jmp ladder_controller_L30
ladder_controller_L29:
; if DOWN != 0:
move.b DOWN,d0
cmp.b #0,d0
bne ladder_controller_L37
jmp ladder_controller_L38
ladder_controller_L37:
; if POSITION < MAXIMUM:
move.b POSITION,d0
move.b MAXIMUM,d1
cmp.b d1,d0
bcs ladder_controller_L40
jmp ladder_controller_L41
ladder_controller_L40:
; POSITION = POSITION + 1
move.b POSITION,d0
add.b #1,d0
move.b d0,POSITION
jmp ladder_controller_L42
ladder_controller_L41:
ladder_controller_L42:
jmp ladder_controller_L39
ladder_controller_L38:
ladder_controller_L39:
ladder_controller_L30:
ladder_controller_L27:
jmp ladder_controller_L24
ladder_controller_L23:
ladder_controller_L24:
ladder_controller_L12:
; if MODE == 0:
move.b MODE,d0
cmp.b #0,d0
beq ladder_controller_L43
jmp ladder_controller_L44
ladder_controller_L43:
; GRAVITY = 1
move.b #1,d0
move.b d0,GRAVITY
jmp ladder_controller_L45
ladder_controller_L44:
ladder_controller_L45:
rts
component_end:Machine contract
D0–D3/A0–A1/CCR may change; D4–D7/A2–A6 are preserved. A direct BSR/JSR needs four 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 A500 OCS diagnostic cold-boots an OFS disk, owns the Copper and bitplane and disables interrupt/DMA sources. The helper does not take over hardware or allocate Chip RAM.
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 and BUILD198X=/path/to/build198x. The Makefile produces normal, custom, deliberately wrong and repaired programs. Tools must already be installed; the sample downloads nothing.
Bindings and include order
section code,code_c
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"
even
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
MODE: dc.b 0
POSITION: dc.b 0
GRAVITY: dc.b 0
JUMPED: dc.b 0
VALID: dc.b 0
ON_LADDER: dc.b 0
UP: dc.b 0
DOWN: dc.b 0
JUMP: dc.b 0
MINIMUM: dc.b 0
MAXIMUM: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XNIGHTTWO000",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0A client retaining state between calls
preview_rules:
ifne CUSTOM
; POSITION = 19
move.b #19,d0
move.b d0,POSITION
; MAXIMUM = 20
move.b #20,d0
move.b d0,MAXIMUM
; ON_LADDER = 1
move.b #1,d0
move.b d0,ON_LADDER
; DOWN = 1
move.b #1,d0
move.b d0,DOWN
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
rts
else
; POSITION = 10
move.b #10,d0
move.b d0,POSITION
; MAXIMUM = 20
move.b #20,d0
move.b d0,MAXIMUM
; ON_LADDER = 1
move.b #1,d0
move.b d0,ON_LADDER
; UP = 1
move.b #1,d0
move.b d0,UP
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
; JUMP = 1
move.b #1,d0
move.b d0,JUMP
ifne BROKEN
; ON_LADDER = 0
move.b #0,d0
move.b d0,ON_LADDER
endif
bsr checked_step
bsr emit_state
endif
rtsCustomise 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
section code,code_c
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"
even
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
MODE: dc.b 0
POSITION: dc.b 0
GRAVITY: dc.b 0
JUMPED: dc.b 0
VALID: dc.b 0
ON_LADDER: dc.b 0
UP: dc.b 0
DOWN: dc.b 0
JUMP: dc.b 0
MINIMUM: dc.b 0
MAXIMUM: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XNIGHTTWO000",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0The 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
section code,code_c
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"
even
include "data.inc"
include "cases.inc"
even
include "display.inc"
include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
MODE: dc.b 0
POSITION: dc.b 0
GRAVITY: dc.b 0
JUMPED: dc.b 0
VALID: dc.b 0
ON_LADDER: dc.b 0
UP: dc.b 0
DOWN: dc.b 0
JUMP: dc.b 0
MINIMUM: dc.b 0
MAXIMUM: dc.b 0
even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
even
signature: dc.b "198XNIGHTTWO000",0
even
copperlist:
dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
dc.w $180,$012,$182,$fff
copbpl:
dc.w $0e0,0,$0e2,0
dc.w $ffff,$fffe
plane: dcb.b 10240,0
Cost and alternatives
The measured helper extent is 464 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 A500 OCS PAL, Kickstart1.3 OFS cold boot, using Asm198x 0.0.72, Emu198x 0.44.2 and Build198x 0.2.9. 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.