Code Like It's 198x

Enter and Leave a Ladder on NES

Climbing should suspend gravity, but jumping away must hand movement back to the ordinary player controller.

Climbing should suspend gravity, but jumping away must hand movement back to the ordinary player controller.

NES shows the working diagnostic row 00 08 01 01 01 01 01 00.
A completed native caller displays 00 08 01 01 01 01 01 00. The public field order below identifies these bytes; the capture is a state diagnostic, not a recording of a finished game.

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

6502.inc
; 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:
    lda #0
    sta MODE
    sta POSITION
    sta GRAVITY
    sta JUMPED
    sta VALID
    sta ON_LADDER
    sta UP
    sta DOWN
    sta JUMP
    sta MINIMUM
    sta MAXIMUM
    rts
ladder_controller_step:
; GRAVITY = 0
    lda #0
    sta GRAVITY
; JUMPED = 0
    lda #0
    sta JUMPED
; VALID = 0
    lda #0
    sta VALID
; if MODE > 1:
    lda MODE
    cmp #1
    beq ladder_controller_L5
    bcs ladder_controller_L4
ladder_controller_L5:
    jmp ladder_controller_L2
ladder_controller_L4:
    jmp ladder_controller_L1
ladder_controller_L1:
; return
    rts
    jmp ladder_controller_L3
ladder_controller_L2:
ladder_controller_L3:
; if MINIMUM > POSITION:
    lda MINIMUM
    cmp POSITION
    beq ladder_controller_L10
    bcs ladder_controller_L9
ladder_controller_L10:
    jmp ladder_controller_L7
ladder_controller_L9:
    jmp ladder_controller_L6
ladder_controller_L6:
; return
    rts
    jmp ladder_controller_L8
ladder_controller_L7:
ladder_controller_L8:
; if POSITION > MAXIMUM:
    lda POSITION
    cmp MAXIMUM
    beq ladder_controller_L15
    bcs ladder_controller_L14
ladder_controller_L15:
    jmp ladder_controller_L12
ladder_controller_L14:
    jmp ladder_controller_L11
ladder_controller_L11:
; return
    rts
    jmp ladder_controller_L13
ladder_controller_L12:
ladder_controller_L13:
; VALID = 1
    lda #1
    sta VALID
; if ON_LADDER == 0:
    lda ON_LADDER
    cmp #0
    beq ladder_controller_L19
ladder_controller_L20:
    jmp ladder_controller_L17
ladder_controller_L19:
    jmp ladder_controller_L16
ladder_controller_L16:
; MODE = 0
    lda #0
    sta MODE
    jmp ladder_controller_L18
ladder_controller_L17:
; if MODE == 0:
    lda MODE
    cmp #0
    beq ladder_controller_L24
ladder_controller_L25:
    jmp ladder_controller_L22
ladder_controller_L24:
    jmp ladder_controller_L21
ladder_controller_L21:
; if UP != 0:
    lda UP
    cmp #0
    bne ladder_controller_L29
ladder_controller_L30:
    jmp ladder_controller_L27
ladder_controller_L29:
    jmp ladder_controller_L26
ladder_controller_L26:
; MODE = 1
    lda #1
    sta MODE
    jmp ladder_controller_L28
ladder_controller_L27:
ladder_controller_L28:
; if DOWN != 0:
    lda DOWN
    cmp #0
    bne ladder_controller_L34
ladder_controller_L35:
    jmp ladder_controller_L32
ladder_controller_L34:
    jmp ladder_controller_L31
ladder_controller_L31:
; MODE = 1
    lda #1
    sta MODE
    jmp ladder_controller_L33
ladder_controller_L32:
ladder_controller_L33:
    jmp ladder_controller_L23
ladder_controller_L22:
ladder_controller_L23:
; if MODE == 1:
    lda MODE
    cmp #1
    beq ladder_controller_L39
ladder_controller_L40:
    jmp ladder_controller_L37
ladder_controller_L39:
    jmp ladder_controller_L36
ladder_controller_L36:
; if JUMP != 0:
    lda JUMP
    cmp #0
    bne ladder_controller_L44
ladder_controller_L45:
    jmp ladder_controller_L42
ladder_controller_L44:
    jmp ladder_controller_L41
ladder_controller_L41:
; MODE = 0
    lda #0
    sta MODE
; JUMPED = 1
    lda #1
    sta JUMPED
    jmp ladder_controller_L43
ladder_controller_L42:
; if UP != 0:
    lda UP
    cmp #0
    bne ladder_controller_L49
ladder_controller_L50:
    jmp ladder_controller_L47
ladder_controller_L49:
    jmp ladder_controller_L46
ladder_controller_L46:
; if DOWN == 0:
    lda DOWN
    cmp #0
    beq ladder_controller_L54
ladder_controller_L55:
    jmp ladder_controller_L52
ladder_controller_L54:
    jmp ladder_controller_L51
ladder_controller_L51:
; if POSITION > MINIMUM:
    lda POSITION
    cmp MINIMUM
    beq ladder_controller_L60
    bcs ladder_controller_L59
ladder_controller_L60:
    jmp ladder_controller_L57
ladder_controller_L59:
    jmp ladder_controller_L56
ladder_controller_L56:
; POSITION = POSITION - 1
    lda POSITION
    sec
    sbc #1
    sta POSITION
    jmp ladder_controller_L58
ladder_controller_L57:
ladder_controller_L58:
    jmp ladder_controller_L53
ladder_controller_L52:
ladder_controller_L53:
    jmp ladder_controller_L48
ladder_controller_L47:
; if DOWN != 0:
    lda DOWN
    cmp #0
    bne ladder_controller_L64
ladder_controller_L65:
    jmp ladder_controller_L62
ladder_controller_L64:
    jmp ladder_controller_L61
ladder_controller_L61:
; if POSITION < MAXIMUM:
    lda POSITION
    cmp MAXIMUM
    bcc ladder_controller_L69
ladder_controller_L70:
    jmp ladder_controller_L67
ladder_controller_L69:
    jmp ladder_controller_L66
ladder_controller_L66:
; POSITION = POSITION + 1
    lda POSITION
    clc
    adc #1
    sta POSITION
    jmp ladder_controller_L68
ladder_controller_L67:
ladder_controller_L68:
    jmp ladder_controller_L63
ladder_controller_L62:
ladder_controller_L63:
ladder_controller_L48:
ladder_controller_L43:
    jmp ladder_controller_L38
ladder_controller_L37:
ladder_controller_L38:
ladder_controller_L18:
; if MODE == 0:
    lda MODE
    cmp #0
    beq ladder_controller_L74
ladder_controller_L75:
    jmp ladder_controller_L72
ladder_controller_L74:
    jmp ladder_controller_L71
ladder_controller_L71:
; GRAVITY = 1
    lda #1
    sta GRAVITY
    jmp ladder_controller_L73
ladder_controller_L72:
ladder_controller_L73:
    rts
component_end:

Machine contract

A/X/status may change; Y is preserved. The 2A03 has no decimal arithmetic mode. A direct JSR 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 NROM caller owns PPU setup and background display, with NMI and DMC disabled. Table and packet sizes are bounded to fit the cartridge caller and internal RAM; the helper owns no PPU registers.

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

demo.asm
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
MODE=$80
POSITION=$81
GRAVITY=$82
JUMPED=$83
VALID=$84
ON_LADDER=$85
UP=$86
DOWN=$87
JUMP=$88
MINIMUM=$89
MAXIMUM=$8a
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0

A client retaining state between calls

exercise.inc, excerpt
preview_rules:
.if CUSTOM
; POSITION = 19
    lda #19
    sta POSITION
; MAXIMUM = 20
    lda #20
    sta MAXIMUM
; ON_LADDER = 1
    lda #1
    sta ON_LADDER
; DOWN = 1
    lda #1
    sta DOWN
.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state
    rts
.else
; POSITION = 10
    lda #10
    sta POSITION
; MAXIMUM = 20
    lda #20
    sta MAXIMUM
; ON_LADDER = 1
    lda #1
    sta ON_LADDER
; UP = 1
    lda #1
    sta UP
.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state
; JUMP = 1
    lda #1
    sta JUMP
.if BROKEN
; ON_LADDER = 0
    lda #0
    sta ON_LADDER
.endif
    jsr checked_step
    jsr emit_state
.endif
    rts

Customise 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

custom.asm
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
MODE=$80
POSITION=$81
GRAVITY=$82
JUMPED=$83
VALID=$84
ON_LADDER=$85
UP=$86
DOWN=$87
JUMP=$88
MINIMUM=$89
MAXIMUM=$8a
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0

The 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

wrong.asm
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
MODE=$80
POSITION=$81
GRAVITY=$82
JUMPED=$83
VALID=$84
ON_LADDER=$85
UP=$86
DOWN=$87
JUMP=$88
MINIMUM=$89
MAXIMUM=$8a
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
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"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0
NES shows the deliberate error row 00 0A 01 00 01 00 01 00.
The wrong client completes with 00 0A 01 00 01 00 01 00; its changed inputs and state explain the result.

Cost and alternatives

The measured helper extent is 316 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 NTSC NROM, background only, DMC/NMI disabled, 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.

The Craft · Maths for Games · Source and native evidence.