Game 1Unit 20 of 201 hr learning time
Again
The last arrow: win or lose, SPACE returns you to a title that remembers your best night — what persists, what's reborn, and an input lock to make every transition deliberate. The state machine closes and the module converges on the shipped game — and then the winnability gate does its job: two bugs the proof found, a tie that steals a win and a wall that kills, closed for good.
100% of Gloaming
Four screens, and they form a line: title, play, gold, black. Walk the line once and it ends — THE NIGHT IS HELD holds forever, NIGHT FALLS never lifts, and the only way to play again is to reload the machine. Every arcade cabinet, every cassette game, every title you fed your evenings to knew the shape this game still lacks: a loop. Win or lose, you go back — to a title that, ideally, has something to say about how you did. This unit draws the last arrow, and in doing so answers the question every game must eventually face: when everything begins again, what deserves to survive?
Milestone 1 — the way back
Unit 19 did the hard part without knowing it. Returning to the title is a state transition like any other, and starting fresh is exactly what init_game was built to provide. What’s missing is the arrow itself — and a reason to follow it.
The arrow is end_step: a fourth hand for the dispatch. WIN and LOSE frames — which since Unit 15 have fallen through to “hold everything” — now go somewhere: read SPACE, and on a press, draw the title, sound the chime, switch to STATE_TITLE. Both end screens print PRESS SPACE beneath their verdict, so the invitation is visible from the moment the night ends, either way it ends.
The reason is the score. One byte, best_lives — the lives you kept on your finest win:
best_lives:
defb 0 ; lives kept on the finest win — never resetThe win path updates it (keep the maximum — a two-life win never overwrites a three-life one), and the title draws it: a row of LIVES pips beside the name, warm up to your best, cold beyond it. No digits, in this game’s steadfast idiom — a bar of gold that says you held the night, and kept this much of yourself doing it.
Step 1: end_step, the invitations, and a best night remembered
+51
| 45 | 45 | PROMPT_COL equ 10 ; PRESS SPACE, centred | |
| 46 | 46 | TITLE_ROW equ 8 | |
| 47 | 47 | PROMPT_ROW equ 14 | |
| 48 | + | CONT_ROW equ 16 ; "PRESS SPACE" under a win/lose line | |
| 48 | 49 | | |
| 49 | 50 | START_COL equ 15 ; where the lamplighter begins | |
| 50 | 51 | START_ROW equ 11 | |
| ... | |||
| 78 | 79 | jr z, .do_title | |
| 79 | 80 | cp STATE_PLAY | |
| 80 | 81 | jr z, .do_play | |
| 82 | + | call end_step ; WIN or LOSE — wait for a key, then title | |
| 81 | 83 | jr main_loop | |
| 82 | 84 | .do_title: | |
| 83 | 85 | call title_step | |
| ... | |||
| 96 | 98 | ret nz | |
| 97 | 99 | call init_game | |
| 98 | 100 | ld a, STATE_PLAY | |
| 101 | + | ld (game_state), a | |
| 102 | + | ret | |
| 103 | + | | |
| 104 | + | ; ---------------------------------------------------------------------------- | |
| 105 | + | ; end_step — WIN or LOSE: SPACE returns to the title. | |
| 106 | + | ; ---------------------------------------------------------------------------- | |
| 107 | + | end_step: | |
| 108 | + | ld bc, KEYS_SPACE | |
| 109 | + | in a, (c) | |
| 110 | + | bit 0, a | |
| 111 | + | ret nz | |
| 112 | + | call draw_title_screen | |
| 113 | + | call chime_dusk | |
| 114 | + | ld a, STATE_TITLE | |
| 99 | 115 | ld (game_state), a | |
| 100 | 116 | ret | |
| 101 | 117 | | |
| ... | |||
| 114 | 130 | ld a, (lit_count) | |
| 115 | 131 | cp NUM_LAMPS | |
| 116 | 132 | ret nz | |
| 133 | + | ; the night is held — the lives you kept are the score | |
| 134 | + | ld a, (lives) | |
| 135 | + | ld hl, best_lives | |
| 136 | + | cp (hl) | |
| 137 | + | jr c, .nobest | |
| 138 | + | ld (hl), a | |
| 139 | + | .nobest: | |
| 117 | 140 | call draw_win_screen | |
| 118 | 141 | call fanfare_held | |
| 119 | 142 | ld a, STATE_WIN | |
| ... | |||
| 355 | 378 | ld b, PROMPT_ROW | |
| 356 | 379 | ld c, PROMPT_COL | |
| 357 | 380 | call print_string | |
| 381 | + | ; your best night — the lives you kept on your finest win, | |
| 382 | + | ; read in lamps (no digits). It survives the loop back to | |
| 383 | + | ; the title: the go-again hook. | |
| 384 | + | ld hl, $5800 + 11 * 32 + 14 | |
| 385 | + | ld b, LIVES | |
| 386 | + | ld a, (best_lives) | |
| 387 | + | ld c, a | |
| 388 | + | .tpip: | |
| 389 | + | ld a, PIP_UNLIT | |
| 390 | + | inc c | |
| 391 | + | dec c | |
| 392 | + | jr z, .tpcold | |
| 393 | + | ld a, PIP_LIT | |
| 394 | + | dec c | |
| 395 | + | .tpcold: | |
| 396 | + | ld (hl), a | |
| 397 | + | inc hl | |
| 398 | + | djnz .tpip | |
| 358 | 399 | ret | |
| 359 | 400 | | |
| 360 | 401 | draw_win_screen: | |
| ... | |||
| 362 | 403 | ld hl, win_text | |
| 363 | 404 | ld b, MSG_ROW | |
| 364 | 405 | ld c, WIN_COL | |
| 406 | + | call print_string | |
| 407 | + | ld hl, prompt_text | |
| 408 | + | ld b, CONT_ROW | |
| 409 | + | ld c, PROMPT_COL | |
| 365 | 410 | call print_string | |
| 366 | 411 | ret | |
| 367 | 412 | | |
| ... | |||
| 376 | 421 | ld hl, lose_text | |
| 377 | 422 | ld b, MSG_ROW | |
| 378 | 423 | ld c, LOSE_COL | |
| 424 | + | call print_string | |
| 425 | + | ld hl, prompt_text | |
| 426 | + | ld b, CONT_ROW | |
| 427 | + | ld c, PROMPT_COL | |
| 379 | 428 | call print_string | |
| 380 | 429 | ret | |
| 381 | 430 | | |
| ... | |||
| 1139 | 1188 | defb 0 | |
| 1140 | 1189 | lives: | |
| 1141 | 1190 | defb LIVES | |
| 1191 | + | best_lives: | |
| 1192 | + | defb 0 ; lives kept on the finest win — never reset | |
| 1142 | 1193 | | |
| 1143 | 1194 | draught_col: | |
| 1144 | 1195 | defb 28 |
The complete step 1 program
; Gloaming — Unit 20: Again
; Cumulative build; every step runs on its own. Narrative: the unit page.
; Win or lose, SPACE returns to a title that remembers — the state machine closes.
org 32768
COBBLE equ %00000001 ; PAPER black (0), INK blue (1) — dark ground
WALL equ %00001111 ; PAPER blue (1), INK white (7) — pale stone
WALL_BIT equ 3 ; the attribute bit that says "this is wall"
LAMP_ATTR equ %01000111 ; BRIGHT, PAPER black, INK white — his own light
LAMP_UNLIT equ %00000101 ; cold cyan INK on black PAPER — bit 3
; clear, so a lamp reads as floor
LAMP_LIT equ %01000110 ; BRIGHT yellow INK on black — a held flame
DRAUGHT_ATTR equ %01000101 ; the wisp: BRIGHT cyan on black — cold light
LIVES equ 3
LIFE_PIP equ %01010000 ; a life: BRIGHT red PAPER — a small ember
LIFE_BASE equ $5800 + 28 ; row 0, right of the ledge — three cells
DRAUGHT_SPEED equ 16 ; frames between the wisp's steps
DRAUGHT_COL0 equ 28 ; the corner the dark enters from
DRAUGHT_ROW0 equ 4
PIP_UNLIT equ %00101000 ; a cold pip: cyan PAPER, a solid block
PIP_LIT equ %01110000 ; a warm pip: BRIGHT yellow PAPER
PIP_BASE equ $5800 + 12 ; row 0, column 12 — the HUD ledge,
; eight cells, centred over the square
NUM_LAMPS equ 8
MSG_ATTR equ %01000111 ; message text: bright white on black
MSG_ROW equ 11
LOSE_COL equ 10 ; centres the eleven characters
WIN_COL equ 7 ; centres the seventeen characters
FONT equ $3C00 ; the ROM font, addressed so that
; ASCII x 8 lands on the right glyph
STATE_TITLE equ 0
STATE_PLAY equ 1
STATE_WIN equ 2 ; the night is held — the game is won
STATE_LOSE equ 3 ; night falls — the game is lost
SPEAKER equ %00010000 ; port $FE bit 4 — the beeper's one bit
TITLE_COL equ 12 ; GLOAMING, centred
PROMPT_COL equ 10 ; PRESS SPACE, centred
TITLE_ROW equ 8
PROMPT_ROW equ 14
CONT_ROW equ 16 ; "PRESS SPACE" under a win/lose line
START_COL equ 15 ; where the lamplighter begins
START_ROW equ 11
PLAYER_REPEAT equ 6 ; frames between steps while a key is held
GATHER equ 120 ; frames the dark gathers before its first step
KEYS_OP equ $DFFE ; half-row P O I U Y — bits 1 and 0
KEYS_Q equ $FBFE ; half-row Q W E R T — bit 0 is Q
KEYS_A equ $FDFE ; half-row A S D F G — bit 0 is A
KEYS_SPACE equ $7FFE ; half-row SPACE SYM M N B — bit 0
start:
; --- the border goes black — the night beyond the square ---
; Port $FE bits 0-2 set the BORDER colour. A = 0 = black.
ld a, 0
out ($FE), a
ld a, STATE_TITLE
ld (game_state), a
call draw_title_screen
im 1
ei
call chime_dusk ; after EI — the rests need the interrupt
main_loop:
halt
; the dispatch: each state names what a frame means — the
; title listens for a beginning, PLAY beats the game forward,
; WIN and LOSE hold the screen exactly as it stands
ld a, (game_state)
cp STATE_TITLE
jr z, .do_title
cp STATE_PLAY
jr z, .do_play
call end_step ; WIN or LOSE — wait for a key, then title
jr main_loop
.do_title:
call title_step
jr main_loop
.do_play:
call play_step
jr main_loop
; ----------------------------------------------------------------------------
; title_step — SPACE starts a fresh game.
; ----------------------------------------------------------------------------
title_step:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call init_game
ld a, STATE_PLAY
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; end_step — WIN or LOSE: SPACE returns to the title.
; ----------------------------------------------------------------------------
end_step:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call draw_title_screen
call chime_dusk
ld a, STATE_TITLE
ld (game_state), a
ret
; play_step — one beat of the game: ask the keyboard.
play_step:
call player_step
; contact can end the game mid-frame — if it did, stop here
ld a, (game_state)
cp STATE_PLAY
ret nz
call draught_step
ld a, (game_state)
cp STATE_PLAY
ret nz
; the win check, at the only beat the count can have changed
ld a, (lit_count)
cp NUM_LAMPS
ret nz
; the night is held — the lives you kept are the score
ld a, (lives)
ld hl, best_lives
cp (hl)
jr c, .nobest
ld (hl), a
.nobest:
call draw_win_screen
call fanfare_held
ld a, STATE_WIN
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; init_game — everything a fresh night needs, gathered from what was
; the boot sequence. Beginning is a callable thing now.
; ----------------------------------------------------------------------------
init_game:
xor a
ld (lit_count), a
ld a, LIVES
ld (lives), a
; --- place the lamplighter ---
; His position is data. Everything that draws him reads it.
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
; --- and, in the far corner, something else ---
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
; the dark gathers before its first step — a beat to read
; the square before the hunt begins
ld a, GATHER
ld (draught_timer), a
xor a
ld (player_timer), a
; --- wipe the canvas ---
; The bitmap ($4000-$57FF) is the pixel layer; whatever was on
; screen before us still lives there. Zero it so only our
; attribute colours show.
call clear_bitmap
; --- texture the ground ---
; Blit the cobble stipple into every cell's bitmap, rows 1-23.
; The attributes will colour these pixels in a moment.
call fill_ground
; --- wash in the cobbles ---
; Seed the first attribute cell, point DE one cell ahead, and
; let LDIR cascade the byte through all 768 cells.
ld hl, $5800
ld de, $5801
ld (hl), COBBLE
ld bc, 767
ldir
call warm_walls
call paint_buildings
; --- brick the walls ---
; Now that the wall cells are painted, fill_walls can read the
; map back and lay brick wherever the wall bit is set.
call fill_walls
call draw_pips
call draw_lives
call draw_lamps
; save what he is about to stand on, BEFORE the first draw
call save_under
call draw_lamp
call save_draught
call draw_draught
ret
; ----------------------------------------------------------------------------
; warm_walls — the square's edge, one attribute write per cell; the
; colour is no longer a constant but the wall_ramp entry for how many
; lamps are lit. Same painting loop as ever — only where C comes from
; has changed.
; ----------------------------------------------------------------------------
warm_walls:
ld a, (lit_count)
ld e, a
ld d, 0
ld hl, wall_ramp
add hl, de
ld c, (hl) ; the byte every wall cell gets
; the top wall: row 1 is 32 cells in a row from $5820
; (row 0 is kept back — it becomes the HUD later)
ld hl, $5820
ld b, 32
.wt:
ld (hl), c
inc hl
djnz .wt
; the bottom wall: row 23, 32 cells from $5AE0
ld hl, $5AE0
ld b, 32
.wb:
ld (hl), c
inc hl
djnz .wb
; the side walls: column 0 and column 31 of rows 1-23.
; Write the row's first cell, hop 31 cells to its last,
; then step a full row (32) down — 23 times.
ld hl, $5820
ld b, 23
.ws:
ld (hl), c
push hl
ld de, 31
add hl, de
ld (hl), c
pop hl
ld de, 32
add hl, de
djnz .ws
ret
; ----------------------------------------------------------------------------
; The beeper. One bit on port $FE: set it, wait, clear it, wait — a
; square wave by hand. C is the half-period (pitch: bigger is lower),
; B the number of cycles (duration). DI while it sounds: the 50 Hz
; interrupt would stretch random half-periods and buzz the tone.
; ----------------------------------------------------------------------------
beep:
di
.bcyc:
ld a, SPEAKER
out ($FE), a
ld a, c
.bd1:
dec a
jr nz, .bd1
xor a
out ($FE), a
ld a, c
.bd2:
dec a
jr nz, .bd2
djnz .bcyc
ei
ret
blip_lit: ; a rising third — the lamp catches
ld b, $17 ; C6
ld c, $67
call beep
ld b, $28 ; E6
ld c, $51
jp beep
chime_dusk: ; two cold tolls, then the motif far off
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 10
call rest
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 13
call rest
ld b, $92 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $9D ; C5
ld c, $CF
jp beep
; rest — B frames of silence. Musical time rides the heartbeat: the
; gaps between notes are counted in HALTs, not busy-loops.
rest:
halt
djnz rest
ret
fanfare_held: ; THE NIGHT IS HELD — a rising run
ld b, $83 ; C5
ld c, $CF
call beep
ld b, 3
call rest
ld b, $A5 ; E5
ld c, $A4
call beep
ld b, 3
call rest
ld b, $C4 ; G5
ld c, $8A
call beep
ld b, 3
call rest
ld b, $FF ; C6, held — B only counts to 255,
ld c, $67
call beep
ld b, $FF ; so hold it by sounding it twice
ld c, $67
jp beep
sting_nightfall: ; NIGHT FALLS — two steps down, then dark
ld b, $53 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $49 ; D5
ld c, $B8
call beep
ld b, 4
call rest
ld b, $DC ; A4, long — the night settles on it
ld c, $F7
jp beep
; ----------------------------------------------------------------------------
; Screens.
; ----------------------------------------------------------------------------
; draw_win_screen — lift the lamplighter off the board (restore his
; cell: the eighth lamp, lit, comes out of the buffer), then say it.
; draw_title_screen — sparse and suggestive: a black void, the name,
; the invitation. Everything else is left to the imagination, which
; is both the aesthetic and the budget.
draw_title_screen:
call clear_bitmap
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, title_text
ld b, TITLE_ROW
ld c, TITLE_COL
call print_string
ld hl, prompt_text
ld b, PROMPT_ROW
ld c, PROMPT_COL
call print_string
; your best night — the lives you kept on your finest win,
; read in lamps (no digits). It survives the loop back to
; the title: the go-again hook.
ld hl, $5800 + 11 * 32 + 14
ld b, LIVES
ld a, (best_lives)
ld c, a
.tpip:
ld a, PIP_UNLIT
inc c
dec c
jr z, .tpcold
ld a, PIP_LIT
dec c
.tpcold:
ld (hl), a
inc hl
djnz .tpip
ret
draw_win_screen:
call restore_under
ld hl, win_text
ld b, MSG_ROW
ld c, WIN_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; draw_lose_screen — the whole attribute table goes black: every lamp,
; every wall, every warm cell, gone in one LDIR. Then the words.
draw_lose_screen:
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, lose_text
ld b, MSG_ROW
ld c, LOSE_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; ----------------------------------------------------------------------------
; clear_bitmap — zero the pixel layer, $4000-$57FF, with the same
; seed-and-cascade LDIR idiom the cobble wash uses.
; ----------------------------------------------------------------------------
clear_bitmap:
ld hl, $4000
ld de, $4001
ld (hl), 0
ld bc, 6143
ldir
ret
; ----------------------------------------------------------------------------
; player_step — the keys become movement. Each direction key edits a
; TARGET position (tcol, trow) — a proposal, not yet a move — so it
; can be vetoed before it becomes real. Then the move commits: leave
; the old cell, take the new one, draw.
; ----------------------------------------------------------------------------
player_step:
; --- propose: the target starts where he stands ---
ld a, (lamp_col)
ld (tcol), a
ld a, (lamp_row)
ld (trow), a
; The held-key gate: the first press steps at once, then one
; step every PLAYER_REPEAT frames. Releasing every direction
; key re-arms the instant first step, so taps stay crisp.
ld bc, KEYS_OP
in a, (c)
cpl
and %00000011
ld e, a
ld bc, KEYS_Q
in a, (c)
cpl
and %00000001
or e
ld e, a
ld bc, KEYS_A
in a, (c)
cpl
and %00000001
or e
jr nz, .held
xor a
ld (player_timer), a
ret
.held:
ld a, (player_timer)
or a
jr z, .stepnow
dec a
ld (player_timer), a
ret
.stepnow:
ld a, PLAYER_REPEAT
ld (player_timer), a
ld bc, KEYS_OP
in a, (c)
bit 1, a ; O — a zero bit is a pressed key
jr z, .pleft
bit 0, a ; P, same half-row
jr z, .pright
ld bc, KEYS_Q
in a, (c)
bit 0, a ; Q
jr z, .pup
ld bc, KEYS_A
in a, (c)
bit 0, a ; A
jr z, .pdown
ret ; nothing held — nothing to do
.pleft:
ld hl, tcol
dec (hl)
jr .pmove
.pright:
ld hl, tcol
inc (hl)
jr .pmove
.pup:
ld hl, trow
dec (hl)
jr .pmove
.pdown:
ld hl, trow
inc (hl)
.pmove:
; The veto: ask the target cell's attribute whether it's wall.
; NZ means brick — the proposal dies here and he stays put.
ld a, (trow)
ld b, a
ld a, (tcol)
ld c, a
call wall_at
ret nz
; and the mirror rule: he cannot step onto the wisp either
ld a, (tcol)
ld hl, draught_col
cp (hl)
jr nz, .pcommit
ld a, (trow)
ld hl, draught_row
cp (hl)
jr nz, .pcommit
call lose_life ; walking into the cold costs the same
ret
.pcommit:
; --- commit: restore, step, save, draw — in that order ---
call restore_under
ld a, (tcol)
ld (lamp_col), a
ld a, (trow)
ld (lamp_row), a
call save_under
; light it where it lives: while he covers the lamp, its truth
; is the buffer — rewrite the saved attribute, and restore will
; paint the lamp back lit when he leaves
ld a, (under_lamp + 8)
cp LAMP_UNLIT
jr nz, .pdrawn
ld a, LAMP_LIT
ld (under_lamp + 8), a
call light_pip
call blip_lit
call warm_walls
.pdrawn:
call draw_lamp
ret
; ----------------------------------------------------------------------------
; fill_ground — the cobble stipple. Not decoration: the stipple is what
; makes ground-state changes visible later, when the game starts
; recolouring these pixels. Rows 1-23 (row 0 is the HUD).
; ----------------------------------------------------------------------------
fill_ground:
ld b, 1 ; rows 1-23 (row 0 is the HUD)
.fgr:
ld c, 0
.fgc:
ld de, cobble_tex
call blit_tex
inc c
ld a, c
cp 32
jr c, .fgc
inc b
ld a, b
cp 24
jr c, .fgr
ret
; fill_walls — brickwork. Driven by the wall attribute bit, so anything
; painted as wall — now or later in the game — gets its brick for free:
; the map itself decides where the brick goes.
fill_walls:
ld b, 1
.fwr:
ld c, 0
.fwc:
push bc
call attr_addr_cr
bit WALL_BIT, (hl)
pop bc
jr z, .fwn
ld de, brick_tex
call blit_tex
.fwn:
inc c
ld a, c
cp 32
jr c, .fwc
inc b
ld a, b
cp 24
jr c, .fwr
ret
; blit_tex — write the 8-byte texture at DE into cell (C, B)'s bitmap.
; scr_addr_cr finds the cell's first pixel row; INC H steps down the
; other seven, 256 bytes apart.
blit_tex:
push bc
call scr_addr_cr
ld b, 8
.bt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .bt
pop bc
ret
cobble_tex:
defb %10000010
defb %00000000
defb %00001000
defb %00000000
defb %00100001
defb %00000000
defb %00010000
defb %00000000
brick_tex:
; mortar courses with staggered verticals — dusk-lit stone
defb %00001000
defb %00001000
defb %00001000
defb %11111111
defb %10000000
defb %10000000
defb %10000000
defb %11111111
; ----------------------------------------------------------------------------
; draught_step — the hunt. One rule: step one cell along the axis with
; the greater distance to the lamplighter (ties go sideways). No walls,
; no vetoes — the wisp is not of the town, and stone means nothing to it.
; ----------------------------------------------------------------------------
draught_step:
ld a, (draught_timer)
dec a
ld (draught_timer), a
ret nz
ld a, DRAUGHT_SPEED
ld (draught_timer), a
; the dark hunts the lamplighter's own flame
ld a, (lamp_col)
ld (seek_col), a
ld a, (lamp_row)
ld (seek_row), a
.chase:
; step one cell along the axis with the greater distance
; (ties go sideways) — the night is 4-connected, like the
; lamplighter
ld a, (draught_col)
ld (dtcol), a
ld a, (draught_row)
ld (dtrow), a
ld a, (seek_col)
ld hl, draught_col
sub (hl)
jp p, .absc
neg
.absc:
ld d, a ; D = |dc|
ld a, (seek_row)
ld hl, draught_row
sub (hl)
jp p, .absr
neg
.absr:
cp d ; |dr| vs |dc|
jr z, .tie
jr c, .horiz
jr .vert
.tie:
ld a, d
or a
ret z ; already on the light
jr .horiz
.horiz:
ld a, (seek_col)
ld hl, draught_col
cp (hl)
jr c, .hleft
ld a, (hl)
inc a
ld (dtcol), a
jr .contact
.hleft:
ld a, (hl)
dec a
ld (dtcol), a
jr .contact
.vert:
ld a, (seek_row)
ld hl, draught_row
cp (hl)
jr c, .vup
ld a, (hl)
inc a
ld (dtrow), a
jr .contact
.vup:
ld a, (hl)
dec a
ld (dtrow), a
.contact:
; never step ONTO the lamplighter: adjacent is as close as
; the night comes. Two movers, two buffers — and one cell
; can only ever be under one of them.
ld a, (dtcol)
ld hl, lamp_col
cp (hl)
jr nz, .dmove
ld a, (dtrow)
ld hl, lamp_row
cp (hl)
jr nz, .dmove
call lose_life ; the touch, priced
ret
.dmove:
call restore_draught
ld a, (dtcol)
ld (draught_col), a
ld a, (dtrow)
ld (draught_row), a
call save_draught
call draw_draught
ret
; paint_buildings — walk the rectangle table: each entry is col, row,
; width, height; $FF ends the list. Every cell inside a rectangle gets
; the WALL attribute — and because fill_walls textures by the wall bit,
; the brickwork arrives without another line of drawing code.
paint_buildings:
ld hl, bldg_data
.pb:
ld a, (hl)
cp $FF
ret z
ld c, a ; col
inc hl
ld b, (hl) ; row
inc hl
ld d, (hl) ; width
inc hl
ld e, (hl) ; height
inc hl
push hl
.pbrow:
push bc
push de
.pbcol:
push bc
push de
call attr_addr_cr
ld (hl), WALL
pop de
pop bc
inc c
dec d
jr nz, .pbcol
pop de
pop bc
inc b
dec e
jr nz, .pbrow
pop hl
jr .pb
bldg_data:
defb 5, 5, 4, 3
defb 23, 5, 4, 3
defb $FF
; ----------------------------------------------------------------------------
; lose_life — the price of the touch: one ember out, and either a
; fresh start or the fall of night.
; ----------------------------------------------------------------------------
lose_life:
ld a, (lives)
dec a
ld (lives), a
ld e, a
ld d, 0
ld hl, LIFE_BASE
add hl, de
ld (hl), COBBLE ; the ember at the new count goes out
ld a, (lives)
or a
jr z, .gone
; a life left: the lamplighter returns to the start cell
call restore_under
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
call save_under
call draw_lamp
; the taking costs the night its reach — the wisp recoils to
; the far corner, so every life buys a whole fresh chase
; (leaving it beside the respawn made a catch strip every
; life in seconds once the draught learnt to hunt)
call restore_draught
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
ld a, DRAUGHT_SPEED
ld (draught_timer), a
call save_draught
call draw_draught
ret
.gone:
call draw_lose_screen
call sting_nightfall
ld a, STATE_LOSE
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; print_string / print_char — the machine's own letters. The Spectrum
; keeps its font in ROM: eight bytes per character, and FONT is chosen
; so that ASCII code x 8 + FONT is the glyph's address. Each character
; is drawn like any cell: attribute first, eight rows down the cell.
; ----------------------------------------------------------------------------
print_string:
.ps:
ld a, (hl)
cp $FF
ret z
push hl
push bc
call print_char
pop bc
pop hl
inc hl
inc c
jr .ps
print_char:
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
ld de, FONT
add hl, de
ex de, hl
push de
call attr_addr_cr
ld (hl), MSG_ATTR
call scr_addr_cr
pop de
ld b, 8
.pc:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .pc
ret
; ----------------------------------------------------------------------------
; light_pip / draw_pips / draw_lives.
; ----------------------------------------------------------------------------
; light_pip — warm the next pip along and count the lamp. lit_count is
; the index of the pip to light AND the number of lamps lit so far —
; read it for the address, then step it.
light_pip:
ld a, (lit_count)
ld e, a
ld d, 0
inc a
ld (lit_count), a
ld hl, PIP_BASE
add hl, de
ld (hl), PIP_LIT
ret
; draw_pips — the tally row: one cell per lamp on the HUD ledge, all
; cold to start. A pip is pure attribute — no glyph, just a block of
; PAPER — so the row costs eight bytes of screen and no bitmap at all.
draw_pips:
ld hl, PIP_BASE
ld b, NUM_LAMPS
ld a, PIP_UNLIT
.dp:
ld (hl), a
inc hl
djnz .dp
ret
; draw_lives — three embers on the ledge's right shoulder.
draw_lives:
ld hl, LIFE_BASE
ld b, LIVES
ld a, LIFE_PIP
.dlv:
ld (hl), a
inc hl
djnz .dlv
ret
; ----------------------------------------------------------------------------
; draw_lamps — walk the position table: col, row pairs, $FF to finish.
; Placement is data; the drawing code neither knows nor cares how many
; lamps the town has tonight.
; ----------------------------------------------------------------------------
draw_lamps:
ld hl, lamp_data
.next:
ld a, (hl)
cp $FF
ret z
ld c, a
inc hl
ld b, (hl)
inc hl
push hl
call draw_lantern
pop hl
jr .next
; draw_lantern — an unlit lamp into cell (C, B): cold cyan attribute,
; then the lantern glyph down the cell like any texture.
draw_lantern:
call attr_addr_cr
ld (hl), LAMP_UNLIT
call scr_addr_cr
ld de, lantern
ld b, 8
.dlt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dlt
ret
; ----------------------------------------------------------------------------
; scr_addr_cr — HL = bitmap address of cell (C, B)'s first pixel row.
; The row's top two bits pick the third of the screen (H), its bottom
; three become L's top bits, and the column fills L's low five.
; ----------------------------------------------------------------------------
scr_addr_cr:
ld a, b
and %00011000 ; the third (row bits 4-3) ...
or %01000000 ; ... under the screen base $40xx
ld h, a
ld a, b
and %00000111 ; the char row within the third ...
rrca ; ... rotated into bits 7-5
rrca
rrca
or c ; the column in bits 4-0
ld l, a
ret
; attr_addr_cr — HL = attribute address of cell (C, B):
; $5800 + row*32 + col, the row shifted up five times.
attr_addr_cr:
ld a, b
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
add hl, hl
add hl, hl
ld de, $5800
add hl, de
ld a, c
ld e, a
ld d, 0
add hl, de
ret
; wall_at — is cell (C, B) wall? The answer is already on the screen:
; every wall cell's attribute has WALL_BIT set, so one bit-test of
; attribute memory is the whole collision system. NZ = wall.
wall_at:
call attr_addr_cr
bit WALL_BIT, (hl)
ret
; ----------------------------------------------------------------------------
; The lamplighter's save / restore / draw.
; ----------------------------------------------------------------------------
; pos_bc — the lamplighter's cell into (C, B), read fresh from the data.
pos_bc:
ld a, (lamp_row)
ld b, a
ld a, (lamp_col)
ld c, a
ret
; save_under — copy the nine bytes of his cell into the buffer: eight
; bitmap rows, then the attribute. Runs as he ARRIVES, before the
; draw — so the buffer always holds true ground, never him.
save_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.su:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .su
call pos_bc
call attr_addr_cr
ld a, (hl)
ld (under_lamp + 8), a
ret
; restore_under — the same nine bytes back the other way: the ground
; returns exactly as it was. Runs as he LEAVES, while the position
; still points at the old cell.
restore_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.ru:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .ru
call pos_bc
call attr_addr_cr
ld a, (under_lamp + 8)
ld (hl), a
ret
draw_lamp:
; his colour first: the cell's attribute becomes his own —
; bright white on the black, his own light about him
call pos_bc
call attr_addr_cr
ld (hl), LAMP_ATTR
; then his shape, eight bytes down the cell like any texture
call pos_bc
call scr_addr_cr
ld de, lamplighter
ld b, 8
.dl:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dl
ret
; ----------------------------------------------------------------------------
; The draught's save / restore / draw — the lamplighter's engine, twice.
; Same loops, same nine-byte contract, its own buffer and its own
; position: two movers can share a world but never a buffer.
; ----------------------------------------------------------------------------
dpos_bc:
ld a, (draught_row)
ld b, a
ld a, (draught_col)
ld c, a
ret
save_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.sd:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .sd
call dpos_bc
call attr_addr_cr
ld a, (hl)
ld (under_draught + 8), a
ret
restore_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.rd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .rd
call dpos_bc
call attr_addr_cr
ld a, (under_draught + 8)
ld (hl), a
ret
draw_draught:
call dpos_bc
call attr_addr_cr
ld (hl), DRAUGHT_ATTR
call dpos_bc
call scr_addr_cr
ld de, draught_glyph
ld b, 8
.dd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dd
ret
; ----------------------------------------------------------------------------
; Data.
; ----------------------------------------------------------------------------
game_state:
defb STATE_TITLE
wall_ramp:
; The square warms in the game's own vocabulary: the stone
; stays dusk-blue; the lamplight catches the mortar first
; (ink white -> yellow), then the whole face glows BRIGHT.
; Never magenta — warmth is yellow here, not red-shifted blue.
defb %00001111 ; dusk stone, white mortar
defb %00001111
defb %00001111
defb %00001110 ; the mortar warms — yellow ink
defb %00001110
defb %00001110
defb %01001110 ; the stone catches the glow — BRIGHT
defb %01001110
defb %01110000 ; all eight lit: the square aglow —
; warm yellow stone, only at the win
lamp_data:
defb 4, 3
defb 27, 3
defb 9, 7
defb 22, 7
defb 6, 15
defb 25, 15
defb 13, 20
defb 18, 20
defb $FF
lamp_col:
defb START_COL
lamp_row:
defb START_ROW
tcol:
defb 0
trow:
defb 0
lit_count:
defb 0
lives:
defb LIVES
best_lives:
defb 0 ; lives kept on the finest win — never reset
draught_col:
defb 28
draught_row:
defb 4
draught_timer:
defb 16
player_timer:
defb 0
seek_col:
defb 0
seek_row:
defb 0
dtcol:
defb 0
dtrow:
defb 0
under_lamp:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
under_draught:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
lamplighter:
defb %00111100
defb %00111100
defb %00011000
defb %01111110
defb %00011000
defb %00011000
defb %00100100
defb %01000010
lantern:
defb %00011000
defb %00100100
defb %01111110
defb %01111110
defb %01011010
defb %01111110
defb %01111110
defb %00111100
draught_glyph:
defb %00000000
defb %00111100
defb %01111110
defb %11111111
defb %11111111
defb %01111110
defb %00111100
defb %00000000
title_text:
defb "GLOAMING"
defb $FF
prompt_text:
defb "PRESS SPACE"
defb $FF
win_text:
defb "THE NIGHT IS HELD"
defb $FF
lose_text:
defb "NIGHT FALLS"
defb $FF
end start
Now look hard at where best_lives lives, because this is the unit’s idea. init_game rebuilds everything — count, lives, positions, timers, the whole board — and best_lives isn’t in it. That’s not an oversight; that’s the design, and it deserves its name: persistence by omission. When beginning is a single routine, “what survives a new game” stops being a vague hope and becomes a precise, auditable list — it’s whatever init_game doesn’t touch. One byte sits outside the cycle of rebirth, and that byte is the entire memory of the machine’s evening. Every high score table you’ve ever typed three initials into is this idea, grown up.
Milestone 2 — deliberate transitions
Play the loop fast, though, and there’s a looseness. These transitions all ride the same key, and a key is held for many frames — press SPACE a beat too long at an end screen and you can feel the risk: the title blinks past and a new night starts before you chose it. The sound has been quietly protecting you — the chime and the sting each freeze the machine for a couple of seconds, eating most of a held press — but a guarantee that’s really a side-effect of a melody is no guarantee at all. Shorten a phrase later, and screens start slipping.
So the finished game makes the guarantee explicit. One byte, input_lock, armed to LOCK (25 frames — half a second) at every transition into a listening screen: entering WIN, entering LOSE, returning to TITLE. title_step and end_step both open the same way: while the lock is counting, decrement it and hear nothing.
Step 2: the input lock — every screen gets half a second of deafness
+24
| 38 | 38 | STATE_PLAY equ 1 | |
| 39 | 39 | STATE_WIN equ 2 ; the night is held — the game is won | |
| 40 | 40 | STATE_LOSE equ 3 ; night falls — the game is lost | |
| 41 | + | | |
| 42 | + | LOCK equ 25 ; input-lock frames after entering a screen | |
| 41 | 43 | | |
| 42 | 44 | SPEAKER equ %00010000 ; port $FE bit 4 — the beeper's one bit | |
| 43 | 45 | | |
| ... | |||
| 92 | 94 | ; title_step — SPACE starts a fresh game. | |
| 93 | 95 | ; ---------------------------------------------------------------------------- | |
| 94 | 96 | title_step: | |
| 97 | + | ld a, (input_lock) | |
| 98 | + | or a | |
| 99 | + | jr z, .tready | |
| 100 | + | dec a | |
| 101 | + | ld (input_lock), a | |
| 102 | + | ret | |
| 103 | + | .tready: | |
| 95 | 104 | ld bc, KEYS_SPACE | |
| 96 | 105 | in a, (c) | |
| 97 | 106 | bit 0, a | |
| ... | |||
| 105 | 114 | ; end_step — WIN or LOSE: SPACE returns to the title. | |
| 106 | 115 | ; ---------------------------------------------------------------------------- | |
| 107 | 116 | end_step: | |
| 117 | + | ld a, (input_lock) | |
| 118 | + | or a | |
| 119 | + | jr z, .eready | |
| 120 | + | dec a | |
| 121 | + | ld (input_lock), a | |
| 122 | + | ret | |
| 123 | + | .eready: | |
| 108 | 124 | ld bc, KEYS_SPACE | |
| 109 | 125 | in a, (c) | |
| 110 | 126 | bit 0, a | |
| 111 | 127 | ret nz | |
| 112 | 128 | call draw_title_screen | |
| 113 | 129 | call chime_dusk | |
| 130 | + | ld a, LOCK | |
| 131 | + | ld (input_lock), a | |
| 114 | 132 | ld a, STATE_TITLE | |
| 115 | 133 | ld (game_state), a | |
| 116 | 134 | ret | |
| ... | |||
| 139 | 157 | .nobest: | |
| 140 | 158 | call draw_win_screen | |
| 141 | 159 | call fanfare_held | |
| 160 | + | ld a, LOCK | |
| 161 | + | ld (input_lock), a | |
| 142 | 162 | ld a, STATE_WIN | |
| 143 | 163 | ld (game_state), a | |
| 144 | 164 | ret | |
| ... | |||
| 836 | 856 | .gone: | |
| 837 | 857 | call draw_lose_screen | |
| 838 | 858 | call sting_nightfall | |
| 859 | + | ld a, LOCK | |
| 860 | + | ld (input_lock), a | |
| 839 | 861 | ld a, STATE_LOSE | |
| 840 | 862 | ld (game_state), a | |
| 841 | 863 | ret | |
| ... | |||
| 1147 | 1169 | | |
| 1148 | 1170 | game_state: | |
| 1149 | 1171 | defb STATE_TITLE | |
| 1172 | + | input_lock: | |
| 1173 | + | defb 0 | |
| 1150 | 1174 | | |
| 1151 | 1175 | wall_ramp: | |
| 1152 | 1176 | ; The square warms in the game's own vocabulary: the stone |
The complete program
; Gloaming — Unit 20: Again
; Cumulative build; every step runs on its own. Narrative: the unit page.
; Win or lose, SPACE returns to a title that remembers — the state machine closes.
org 32768
COBBLE equ %00000001 ; PAPER black (0), INK blue (1) — dark ground
WALL equ %00001111 ; PAPER blue (1), INK white (7) — pale stone
WALL_BIT equ 3 ; the attribute bit that says "this is wall"
LAMP_ATTR equ %01000111 ; BRIGHT, PAPER black, INK white — his own light
LAMP_UNLIT equ %00000101 ; cold cyan INK on black PAPER — bit 3
; clear, so a lamp reads as floor
LAMP_LIT equ %01000110 ; BRIGHT yellow INK on black — a held flame
DRAUGHT_ATTR equ %01000101 ; the wisp: BRIGHT cyan on black — cold light
LIVES equ 3
LIFE_PIP equ %01010000 ; a life: BRIGHT red PAPER — a small ember
LIFE_BASE equ $5800 + 28 ; row 0, right of the ledge — three cells
DRAUGHT_SPEED equ 16 ; frames between the wisp's steps
DRAUGHT_COL0 equ 28 ; the corner the dark enters from
DRAUGHT_ROW0 equ 4
PIP_UNLIT equ %00101000 ; a cold pip: cyan PAPER, a solid block
PIP_LIT equ %01110000 ; a warm pip: BRIGHT yellow PAPER
PIP_BASE equ $5800 + 12 ; row 0, column 12 — the HUD ledge,
; eight cells, centred over the square
NUM_LAMPS equ 8
MSG_ATTR equ %01000111 ; message text: bright white on black
MSG_ROW equ 11
LOSE_COL equ 10 ; centres the eleven characters
WIN_COL equ 7 ; centres the seventeen characters
FONT equ $3C00 ; the ROM font, addressed so that
; ASCII x 8 lands on the right glyph
STATE_TITLE equ 0
STATE_PLAY equ 1
STATE_WIN equ 2 ; the night is held — the game is won
STATE_LOSE equ 3 ; night falls — the game is lost
LOCK equ 25 ; input-lock frames after entering a screen
SPEAKER equ %00010000 ; port $FE bit 4 — the beeper's one bit
TITLE_COL equ 12 ; GLOAMING, centred
PROMPT_COL equ 10 ; PRESS SPACE, centred
TITLE_ROW equ 8
PROMPT_ROW equ 14
CONT_ROW equ 16 ; "PRESS SPACE" under a win/lose line
START_COL equ 15 ; where the lamplighter begins
START_ROW equ 11
PLAYER_REPEAT equ 6 ; frames between steps while a key is held
GATHER equ 120 ; frames the dark gathers before its first step
KEYS_OP equ $DFFE ; half-row P O I U Y — bits 1 and 0
KEYS_Q equ $FBFE ; half-row Q W E R T — bit 0 is Q
KEYS_A equ $FDFE ; half-row A S D F G — bit 0 is A
KEYS_SPACE equ $7FFE ; half-row SPACE SYM M N B — bit 0
start:
; --- the border goes black — the night beyond the square ---
; Port $FE bits 0-2 set the BORDER colour. A = 0 = black.
ld a, 0
out ($FE), a
ld a, STATE_TITLE
ld (game_state), a
call draw_title_screen
im 1
ei
call chime_dusk ; after EI — the rests need the interrupt
main_loop:
halt
; the dispatch: each state names what a frame means — the
; title listens for a beginning, PLAY beats the game forward,
; WIN and LOSE hold the screen exactly as it stands
ld a, (game_state)
cp STATE_TITLE
jr z, .do_title
cp STATE_PLAY
jr z, .do_play
call end_step ; WIN or LOSE — wait for a key, then title
jr main_loop
.do_title:
call title_step
jr main_loop
.do_play:
call play_step
jr main_loop
; ----------------------------------------------------------------------------
; title_step — SPACE starts a fresh game.
; ----------------------------------------------------------------------------
title_step:
ld a, (input_lock)
or a
jr z, .tready
dec a
ld (input_lock), a
ret
.tready:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call init_game
ld a, STATE_PLAY
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; end_step — WIN or LOSE: SPACE returns to the title.
; ----------------------------------------------------------------------------
end_step:
ld a, (input_lock)
or a
jr z, .eready
dec a
ld (input_lock), a
ret
.eready:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call draw_title_screen
call chime_dusk
ld a, LOCK
ld (input_lock), a
ld a, STATE_TITLE
ld (game_state), a
ret
; play_step — one beat of the game: ask the keyboard.
play_step:
call player_step
; contact can end the game mid-frame — if it did, stop here
ld a, (game_state)
cp STATE_PLAY
ret nz
call draught_step
ld a, (game_state)
cp STATE_PLAY
ret nz
; the win check, at the only beat the count can have changed
ld a, (lit_count)
cp NUM_LAMPS
ret nz
; the night is held — the lives you kept are the score
ld a, (lives)
ld hl, best_lives
cp (hl)
jr c, .nobest
ld (hl), a
.nobest:
call draw_win_screen
call fanfare_held
ld a, LOCK
ld (input_lock), a
ld a, STATE_WIN
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; init_game — everything a fresh night needs, gathered from what was
; the boot sequence. Beginning is a callable thing now.
; ----------------------------------------------------------------------------
init_game:
xor a
ld (lit_count), a
ld a, LIVES
ld (lives), a
; --- place the lamplighter ---
; His position is data. Everything that draws him reads it.
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
; --- and, in the far corner, something else ---
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
; the dark gathers before its first step — a beat to read
; the square before the hunt begins
ld a, GATHER
ld (draught_timer), a
xor a
ld (player_timer), a
; --- wipe the canvas ---
; The bitmap ($4000-$57FF) is the pixel layer; whatever was on
; screen before us still lives there. Zero it so only our
; attribute colours show.
call clear_bitmap
; --- texture the ground ---
; Blit the cobble stipple into every cell's bitmap, rows 1-23.
; The attributes will colour these pixels in a moment.
call fill_ground
; --- wash in the cobbles ---
; Seed the first attribute cell, point DE one cell ahead, and
; let LDIR cascade the byte through all 768 cells.
ld hl, $5800
ld de, $5801
ld (hl), COBBLE
ld bc, 767
ldir
call warm_walls
call paint_buildings
; --- brick the walls ---
; Now that the wall cells are painted, fill_walls can read the
; map back and lay brick wherever the wall bit is set.
call fill_walls
call draw_pips
call draw_lives
call draw_lamps
; save what he is about to stand on, BEFORE the first draw
call save_under
call draw_lamp
call save_draught
call draw_draught
ret
; ----------------------------------------------------------------------------
; warm_walls — the square's edge, one attribute write per cell; the
; colour is no longer a constant but the wall_ramp entry for how many
; lamps are lit. Same painting loop as ever — only where C comes from
; has changed.
; ----------------------------------------------------------------------------
warm_walls:
ld a, (lit_count)
ld e, a
ld d, 0
ld hl, wall_ramp
add hl, de
ld c, (hl) ; the byte every wall cell gets
; the top wall: row 1 is 32 cells in a row from $5820
; (row 0 is kept back — it becomes the HUD later)
ld hl, $5820
ld b, 32
.wt:
ld (hl), c
inc hl
djnz .wt
; the bottom wall: row 23, 32 cells from $5AE0
ld hl, $5AE0
ld b, 32
.wb:
ld (hl), c
inc hl
djnz .wb
; the side walls: column 0 and column 31 of rows 1-23.
; Write the row's first cell, hop 31 cells to its last,
; then step a full row (32) down — 23 times.
ld hl, $5820
ld b, 23
.ws:
ld (hl), c
push hl
ld de, 31
add hl, de
ld (hl), c
pop hl
ld de, 32
add hl, de
djnz .ws
ret
; ----------------------------------------------------------------------------
; The beeper. One bit on port $FE: set it, wait, clear it, wait — a
; square wave by hand. C is the half-period (pitch: bigger is lower),
; B the number of cycles (duration). DI while it sounds: the 50 Hz
; interrupt would stretch random half-periods and buzz the tone.
; ----------------------------------------------------------------------------
beep:
di
.bcyc:
ld a, SPEAKER
out ($FE), a
ld a, c
.bd1:
dec a
jr nz, .bd1
xor a
out ($FE), a
ld a, c
.bd2:
dec a
jr nz, .bd2
djnz .bcyc
ei
ret
blip_lit: ; a rising third — the lamp catches
ld b, $17 ; C6
ld c, $67
call beep
ld b, $28 ; E6
ld c, $51
jp beep
chime_dusk: ; two cold tolls, then the motif far off
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 10
call rest
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 13
call rest
ld b, $92 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $9D ; C5
ld c, $CF
jp beep
; rest — B frames of silence. Musical time rides the heartbeat: the
; gaps between notes are counted in HALTs, not busy-loops.
rest:
halt
djnz rest
ret
fanfare_held: ; THE NIGHT IS HELD — a rising run
ld b, $83 ; C5
ld c, $CF
call beep
ld b, 3
call rest
ld b, $A5 ; E5
ld c, $A4
call beep
ld b, 3
call rest
ld b, $C4 ; G5
ld c, $8A
call beep
ld b, 3
call rest
ld b, $FF ; C6, held — B only counts to 255,
ld c, $67
call beep
ld b, $FF ; so hold it by sounding it twice
ld c, $67
jp beep
sting_nightfall: ; NIGHT FALLS — two steps down, then dark
ld b, $53 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $49 ; D5
ld c, $B8
call beep
ld b, 4
call rest
ld b, $DC ; A4, long — the night settles on it
ld c, $F7
jp beep
; ----------------------------------------------------------------------------
; Screens.
; ----------------------------------------------------------------------------
; draw_win_screen — lift the lamplighter off the board (restore his
; cell: the eighth lamp, lit, comes out of the buffer), then say it.
; draw_title_screen — sparse and suggestive: a black void, the name,
; the invitation. Everything else is left to the imagination, which
; is both the aesthetic and the budget.
draw_title_screen:
call clear_bitmap
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, title_text
ld b, TITLE_ROW
ld c, TITLE_COL
call print_string
ld hl, prompt_text
ld b, PROMPT_ROW
ld c, PROMPT_COL
call print_string
; your best night — the lives you kept on your finest win,
; read in lamps (no digits). It survives the loop back to
; the title: the go-again hook.
ld hl, $5800 + 11 * 32 + 14
ld b, LIVES
ld a, (best_lives)
ld c, a
.tpip:
ld a, PIP_UNLIT
inc c
dec c
jr z, .tpcold
ld a, PIP_LIT
dec c
.tpcold:
ld (hl), a
inc hl
djnz .tpip
ret
draw_win_screen:
call restore_under
ld hl, win_text
ld b, MSG_ROW
ld c, WIN_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; draw_lose_screen — the whole attribute table goes black: every lamp,
; every wall, every warm cell, gone in one LDIR. Then the words.
draw_lose_screen:
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, lose_text
ld b, MSG_ROW
ld c, LOSE_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; ----------------------------------------------------------------------------
; clear_bitmap — zero the pixel layer, $4000-$57FF, with the same
; seed-and-cascade LDIR idiom the cobble wash uses.
; ----------------------------------------------------------------------------
clear_bitmap:
ld hl, $4000
ld de, $4001
ld (hl), 0
ld bc, 6143
ldir
ret
; ----------------------------------------------------------------------------
; player_step — the keys become movement. Each direction key edits a
; TARGET position (tcol, trow) — a proposal, not yet a move — so it
; can be vetoed before it becomes real. Then the move commits: leave
; the old cell, take the new one, draw.
; ----------------------------------------------------------------------------
player_step:
; --- propose: the target starts where he stands ---
ld a, (lamp_col)
ld (tcol), a
ld a, (lamp_row)
ld (trow), a
; The held-key gate: the first press steps at once, then one
; step every PLAYER_REPEAT frames. Releasing every direction
; key re-arms the instant first step, so taps stay crisp.
ld bc, KEYS_OP
in a, (c)
cpl
and %00000011
ld e, a
ld bc, KEYS_Q
in a, (c)
cpl
and %00000001
or e
ld e, a
ld bc, KEYS_A
in a, (c)
cpl
and %00000001
or e
jr nz, .held
xor a
ld (player_timer), a
ret
.held:
ld a, (player_timer)
or a
jr z, .stepnow
dec a
ld (player_timer), a
ret
.stepnow:
ld a, PLAYER_REPEAT
ld (player_timer), a
ld bc, KEYS_OP
in a, (c)
bit 1, a ; O — a zero bit is a pressed key
jr z, .pleft
bit 0, a ; P, same half-row
jr z, .pright
ld bc, KEYS_Q
in a, (c)
bit 0, a ; Q
jr z, .pup
ld bc, KEYS_A
in a, (c)
bit 0, a ; A
jr z, .pdown
ret ; nothing held — nothing to do
.pleft:
ld hl, tcol
dec (hl)
jr .pmove
.pright:
ld hl, tcol
inc (hl)
jr .pmove
.pup:
ld hl, trow
dec (hl)
jr .pmove
.pdown:
ld hl, trow
inc (hl)
.pmove:
; The veto: ask the target cell's attribute whether it's wall.
; NZ means brick — the proposal dies here and he stays put.
ld a, (trow)
ld b, a
ld a, (tcol)
ld c, a
call wall_at
ret nz
; and the mirror rule: he cannot step onto the wisp either
ld a, (tcol)
ld hl, draught_col
cp (hl)
jr nz, .pcommit
ld a, (trow)
ld hl, draught_row
cp (hl)
jr nz, .pcommit
call lose_life ; walking into the cold costs the same
ret
.pcommit:
; --- commit: restore, step, save, draw — in that order ---
call restore_under
ld a, (tcol)
ld (lamp_col), a
ld a, (trow)
ld (lamp_row), a
call save_under
; light it where it lives: while he covers the lamp, its truth
; is the buffer — rewrite the saved attribute, and restore will
; paint the lamp back lit when he leaves
ld a, (under_lamp + 8)
cp LAMP_UNLIT
jr nz, .pdrawn
ld a, LAMP_LIT
ld (under_lamp + 8), a
call light_pip
call blip_lit
call warm_walls
.pdrawn:
call draw_lamp
ret
; ----------------------------------------------------------------------------
; fill_ground — the cobble stipple. Not decoration: the stipple is what
; makes ground-state changes visible later, when the game starts
; recolouring these pixels. Rows 1-23 (row 0 is the HUD).
; ----------------------------------------------------------------------------
fill_ground:
ld b, 1 ; rows 1-23 (row 0 is the HUD)
.fgr:
ld c, 0
.fgc:
ld de, cobble_tex
call blit_tex
inc c
ld a, c
cp 32
jr c, .fgc
inc b
ld a, b
cp 24
jr c, .fgr
ret
; fill_walls — brickwork. Driven by the wall attribute bit, so anything
; painted as wall — now or later in the game — gets its brick for free:
; the map itself decides where the brick goes.
fill_walls:
ld b, 1
.fwr:
ld c, 0
.fwc:
push bc
call attr_addr_cr
bit WALL_BIT, (hl)
pop bc
jr z, .fwn
ld de, brick_tex
call blit_tex
.fwn:
inc c
ld a, c
cp 32
jr c, .fwc
inc b
ld a, b
cp 24
jr c, .fwr
ret
; blit_tex — write the 8-byte texture at DE into cell (C, B)'s bitmap.
; scr_addr_cr finds the cell's first pixel row; INC H steps down the
; other seven, 256 bytes apart.
blit_tex:
push bc
call scr_addr_cr
ld b, 8
.bt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .bt
pop bc
ret
cobble_tex:
defb %10000010
defb %00000000
defb %00001000
defb %00000000
defb %00100001
defb %00000000
defb %00010000
defb %00000000
brick_tex:
; mortar courses with staggered verticals — dusk-lit stone
defb %00001000
defb %00001000
defb %00001000
defb %11111111
defb %10000000
defb %10000000
defb %10000000
defb %11111111
; ----------------------------------------------------------------------------
; draught_step — the hunt. One rule: step one cell along the axis with
; the greater distance to the lamplighter (ties go sideways). No walls,
; no vetoes — the wisp is not of the town, and stone means nothing to it.
; ----------------------------------------------------------------------------
draught_step:
ld a, (draught_timer)
dec a
ld (draught_timer), a
ret nz
ld a, DRAUGHT_SPEED
ld (draught_timer), a
; the dark hunts the lamplighter's own flame
ld a, (lamp_col)
ld (seek_col), a
ld a, (lamp_row)
ld (seek_row), a
.chase:
; step one cell along the axis with the greater distance
; (ties go sideways) — the night is 4-connected, like the
; lamplighter
ld a, (draught_col)
ld (dtcol), a
ld a, (draught_row)
ld (dtrow), a
ld a, (seek_col)
ld hl, draught_col
sub (hl)
jp p, .absc
neg
.absc:
ld d, a ; D = |dc|
ld a, (seek_row)
ld hl, draught_row
sub (hl)
jp p, .absr
neg
.absr:
cp d ; |dr| vs |dc|
jr z, .tie
jr c, .horiz
jr .vert
.tie:
ld a, d
or a
ret z ; already on the light
jr .horiz
.horiz:
ld a, (seek_col)
ld hl, draught_col
cp (hl)
jr c, .hleft
ld a, (hl)
inc a
ld (dtcol), a
jr .contact
.hleft:
ld a, (hl)
dec a
ld (dtcol), a
jr .contact
.vert:
ld a, (seek_row)
ld hl, draught_row
cp (hl)
jr c, .vup
ld a, (hl)
inc a
ld (dtrow), a
jr .contact
.vup:
ld a, (hl)
dec a
ld (dtrow), a
.contact:
; never step ONTO the lamplighter: adjacent is as close as
; the night comes. Two movers, two buffers — and one cell
; can only ever be under one of them.
ld a, (dtcol)
ld hl, lamp_col
cp (hl)
jr nz, .dmove
ld a, (dtrow)
ld hl, lamp_row
cp (hl)
jr nz, .dmove
call lose_life ; the touch, priced
ret
.dmove:
call restore_draught
ld a, (dtcol)
ld (draught_col), a
ld a, (dtrow)
ld (draught_row), a
call save_draught
call draw_draught
ret
; paint_buildings — walk the rectangle table: each entry is col, row,
; width, height; $FF ends the list. Every cell inside a rectangle gets
; the WALL attribute — and because fill_walls textures by the wall bit,
; the brickwork arrives without another line of drawing code.
paint_buildings:
ld hl, bldg_data
.pb:
ld a, (hl)
cp $FF
ret z
ld c, a ; col
inc hl
ld b, (hl) ; row
inc hl
ld d, (hl) ; width
inc hl
ld e, (hl) ; height
inc hl
push hl
.pbrow:
push bc
push de
.pbcol:
push bc
push de
call attr_addr_cr
ld (hl), WALL
pop de
pop bc
inc c
dec d
jr nz, .pbcol
pop de
pop bc
inc b
dec e
jr nz, .pbrow
pop hl
jr .pb
bldg_data:
defb 5, 5, 4, 3
defb 23, 5, 4, 3
defb $FF
; ----------------------------------------------------------------------------
; lose_life — the price of the touch: one ember out, and either a
; fresh start or the fall of night.
; ----------------------------------------------------------------------------
lose_life:
ld a, (lives)
dec a
ld (lives), a
ld e, a
ld d, 0
ld hl, LIFE_BASE
add hl, de
ld (hl), COBBLE ; the ember at the new count goes out
ld a, (lives)
or a
jr z, .gone
; a life left: the lamplighter returns to the start cell
call restore_under
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
call save_under
call draw_lamp
; the taking costs the night its reach — the wisp recoils to
; the far corner, so every life buys a whole fresh chase
; (leaving it beside the respawn made a catch strip every
; life in seconds once the draught learnt to hunt)
call restore_draught
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
ld a, DRAUGHT_SPEED
ld (draught_timer), a
call save_draught
call draw_draught
ret
.gone:
call draw_lose_screen
call sting_nightfall
ld a, LOCK
ld (input_lock), a
ld a, STATE_LOSE
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; print_string / print_char — the machine's own letters. The Spectrum
; keeps its font in ROM: eight bytes per character, and FONT is chosen
; so that ASCII code x 8 + FONT is the glyph's address. Each character
; is drawn like any cell: attribute first, eight rows down the cell.
; ----------------------------------------------------------------------------
print_string:
.ps:
ld a, (hl)
cp $FF
ret z
push hl
push bc
call print_char
pop bc
pop hl
inc hl
inc c
jr .ps
print_char:
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
ld de, FONT
add hl, de
ex de, hl
push de
call attr_addr_cr
ld (hl), MSG_ATTR
call scr_addr_cr
pop de
ld b, 8
.pc:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .pc
ret
; ----------------------------------------------------------------------------
; light_pip / draw_pips / draw_lives.
; ----------------------------------------------------------------------------
; light_pip — warm the next pip along and count the lamp. lit_count is
; the index of the pip to light AND the number of lamps lit so far —
; read it for the address, then step it.
light_pip:
ld a, (lit_count)
ld e, a
ld d, 0
inc a
ld (lit_count), a
ld hl, PIP_BASE
add hl, de
ld (hl), PIP_LIT
ret
; draw_pips — the tally row: one cell per lamp on the HUD ledge, all
; cold to start. A pip is pure attribute — no glyph, just a block of
; PAPER — so the row costs eight bytes of screen and no bitmap at all.
draw_pips:
ld hl, PIP_BASE
ld b, NUM_LAMPS
ld a, PIP_UNLIT
.dp:
ld (hl), a
inc hl
djnz .dp
ret
; draw_lives — three embers on the ledge's right shoulder.
draw_lives:
ld hl, LIFE_BASE
ld b, LIVES
ld a, LIFE_PIP
.dlv:
ld (hl), a
inc hl
djnz .dlv
ret
; ----------------------------------------------------------------------------
; draw_lamps — walk the position table: col, row pairs, $FF to finish.
; Placement is data; the drawing code neither knows nor cares how many
; lamps the town has tonight.
; ----------------------------------------------------------------------------
draw_lamps:
ld hl, lamp_data
.next:
ld a, (hl)
cp $FF
ret z
ld c, a
inc hl
ld b, (hl)
inc hl
push hl
call draw_lantern
pop hl
jr .next
; draw_lantern — an unlit lamp into cell (C, B): cold cyan attribute,
; then the lantern glyph down the cell like any texture.
draw_lantern:
call attr_addr_cr
ld (hl), LAMP_UNLIT
call scr_addr_cr
ld de, lantern
ld b, 8
.dlt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dlt
ret
; ----------------------------------------------------------------------------
; scr_addr_cr — HL = bitmap address of cell (C, B)'s first pixel row.
; The row's top two bits pick the third of the screen (H), its bottom
; three become L's top bits, and the column fills L's low five.
; ----------------------------------------------------------------------------
scr_addr_cr:
ld a, b
and %00011000 ; the third (row bits 4-3) ...
or %01000000 ; ... under the screen base $40xx
ld h, a
ld a, b
and %00000111 ; the char row within the third ...
rrca ; ... rotated into bits 7-5
rrca
rrca
or c ; the column in bits 4-0
ld l, a
ret
; attr_addr_cr — HL = attribute address of cell (C, B):
; $5800 + row*32 + col, the row shifted up five times.
attr_addr_cr:
ld a, b
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
add hl, hl
add hl, hl
ld de, $5800
add hl, de
ld a, c
ld e, a
ld d, 0
add hl, de
ret
; wall_at — is cell (C, B) wall? The answer is already on the screen:
; every wall cell's attribute has WALL_BIT set, so one bit-test of
; attribute memory is the whole collision system. NZ = wall.
wall_at:
call attr_addr_cr
bit WALL_BIT, (hl)
ret
; ----------------------------------------------------------------------------
; The lamplighter's save / restore / draw.
; ----------------------------------------------------------------------------
; pos_bc — the lamplighter's cell into (C, B), read fresh from the data.
pos_bc:
ld a, (lamp_row)
ld b, a
ld a, (lamp_col)
ld c, a
ret
; save_under — copy the nine bytes of his cell into the buffer: eight
; bitmap rows, then the attribute. Runs as he ARRIVES, before the
; draw — so the buffer always holds true ground, never him.
save_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.su:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .su
call pos_bc
call attr_addr_cr
ld a, (hl)
ld (under_lamp + 8), a
ret
; restore_under — the same nine bytes back the other way: the ground
; returns exactly as it was. Runs as he LEAVES, while the position
; still points at the old cell.
restore_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.ru:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .ru
call pos_bc
call attr_addr_cr
ld a, (under_lamp + 8)
ld (hl), a
ret
draw_lamp:
; his colour first: the cell's attribute becomes his own —
; bright white on the black, his own light about him
call pos_bc
call attr_addr_cr
ld (hl), LAMP_ATTR
; then his shape, eight bytes down the cell like any texture
call pos_bc
call scr_addr_cr
ld de, lamplighter
ld b, 8
.dl:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dl
ret
; ----------------------------------------------------------------------------
; The draught's save / restore / draw — the lamplighter's engine, twice.
; Same loops, same nine-byte contract, its own buffer and its own
; position: two movers can share a world but never a buffer.
; ----------------------------------------------------------------------------
dpos_bc:
ld a, (draught_row)
ld b, a
ld a, (draught_col)
ld c, a
ret
save_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.sd:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .sd
call dpos_bc
call attr_addr_cr
ld a, (hl)
ld (under_draught + 8), a
ret
restore_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.rd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .rd
call dpos_bc
call attr_addr_cr
ld a, (under_draught + 8)
ld (hl), a
ret
draw_draught:
call dpos_bc
call attr_addr_cr
ld (hl), DRAUGHT_ATTR
call dpos_bc
call scr_addr_cr
ld de, draught_glyph
ld b, 8
.dd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dd
ret
; ----------------------------------------------------------------------------
; Data.
; ----------------------------------------------------------------------------
game_state:
defb STATE_TITLE
input_lock:
defb 0
wall_ramp:
; The square warms in the game's own vocabulary: the stone
; stays dusk-blue; the lamplight catches the mortar first
; (ink white -> yellow), then the whole face glows BRIGHT.
; Never magenta — warmth is yellow here, not red-shifted blue.
defb %00001111 ; dusk stone, white mortar
defb %00001111
defb %00001111
defb %00001110 ; the mortar warms — yellow ink
defb %00001110
defb %00001110
defb %01001110 ; the stone catches the glow — BRIGHT
defb %01001110
defb %01110000 ; all eight lit: the square aglow —
; warm yellow stone, only at the win
lamp_data:
defb 4, 3
defb 27, 3
defb 9, 7
defb 22, 7
defb 6, 15
defb 25, 15
defb 13, 20
defb 18, 20
defb $FF
lamp_col:
defb START_COL
lamp_row:
defb START_ROW
tcol:
defb 0
trow:
defb 0
lit_count:
defb 0
lives:
defb LIVES
best_lives:
defb 0 ; lives kept on the finest win — never reset
draught_col:
defb 28
draught_row:
defb 4
draught_timer:
defb 16
player_timer:
defb 0
seek_col:
defb 0
seek_row:
defb 0
dtcol:
defb 0
dtrow:
defb 0
under_lamp:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
under_draught:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
lamplighter:
defb %00111100
defb %00111100
defb %00011000
defb %01111110
defb %00011000
defb %00011000
defb %00100100
defb %01000010
lantern:
defb %00011000
defb %00100100
defb %01111110
defb %01111110
defb %01011010
defb %01111110
defb %01111110
defb %00111100
draught_glyph:
defb %00000000
defb %00111100
defb %01111110
defb %11111111
defb %11111111
defb %01111110
defb %00111100
defb %00000000
title_text:
defb "GLOAMING"
defb $FF
prompt_text:
defb "PRESS SPACE"
defb $FF
win_text:
defb "THE NIGHT IS HELD"
defb $FF
lose_text:
defb "NIGHT FALLS"
defb $FF
end start
It’s a humble mechanism and worth being honest about its scope: the lock is a debounce, not a fortress — hold SPACE down stubbornly for four full seconds and you’ll still sail through. What it guards is the real case: the ordinary press that lands a few frames long, the panic key still down when the night ends. Half a second of deafness at each threshold turns “transitions usually feel deliberate” into “transitions are deliberate”, and the difference between those two sentences is the difference between a program and a finished game.
(One tiny idiom in the title’s pip loop rewards a close look: inc c / dec c — an increment immediately undone. Why? dec sets the flags; inc-then-dec tests C for zero without changing it — a flags-only read of a register the loop still needs. Z80 programmers collected tricks like this the way the title collects pips.)
Milestone 3 — the tie that steals a win
Two milestones ago this looked finished. It runs, it loops, it remembers. But finished isn’t a feeling — this course has said since Unit 16 that a game is not done because it looks done; it’s done when you can drive it to each of its endings and watch them arrive. So before we call it, we do exactly that: a scripted run to THE NIGHT IS HELD, and a scripted run to NIGHT FALLS. Proving a game is the discipline that turns “I think it works” into “I watched it work” — and the reason the discipline exists is that sometimes you watch it not.
Drive the win to its very edge — the eighth lamp lit on your last life, the wisp arriving on the same frame — and the shipped game does something it has no right to do:
Here’s why, and it’s a single matter of order. play_step runs the beat like this: move the lamplighter, then move the wisp, then ask if the night is held. On the tie frame the lamplighter lights the eighth lamp — the win is now true — and then the wisp steps onto him; draught_step resolves that catch, sets NIGHT FALLS, and the win is never asked, because the frame has already ended in a loss. The game checked defeat before it checked victory.
The fix is to ask the better question first:
play_step:
call player_step
; ... if the lamplighter's own move ended the game, stop ...
ld a, (lit_count) ; the win check, now FIRST
cp NUM_LAMPS
jr z, .night_held ; the set is complete — held, this instant
call draught_step ; only now does the wisp get its move
; ...Lighting the last lamp holds the night this instant — before the wisp is allowed its step. A win and a catch on the same frame now resolve as the win, which is the only fair reading: you finished before it reached you. Same tie, same last life — and now:
The other wrong the proof found
Push on the loss the same way and a second, subtler fault surfaces. Hug a wall while the wisp is phasing through it — the night is not of the town, and stone means nothing to it — and a bump that should cost nothing costs you a life. The wall still looks solid; you die walking into brick.
The culprit is a line we were proud of. wall_at reads collision straight off the screen — “the answer is already on the screen,” every wall cell’s attribute carrying the wall bit. Elegant, until two things share a cell. While the wisp is drawn over a wall, that cell’s attribute is the wisp’s (no wall bit), so wall_at waves the step through — and the mirror rule, finding the wisp there, prices the harmless bump as fatal contact.
The truth didn’t vanish; it moved. The wisp’s own buffer, under_draught, still holds the ground it stands on — and that is what to ask:
; the wisp is on the target cell — but is that cell really a wall?
ld a, (under_draught + 8) ; the ground beneath the wisp
bit WALL_BIT, a
ret nz ; brick under the wisp — blocked, harmless
call lose_life ; open ground — the cold touches, and it costsThe lesson is bigger than the bug: when two movers can occupy one cell, the screen stops being the ground truth — the buffer that remembers what lies underneath is. The two-mover pattern you built back in Unit 8 always carried this hazard; it only bites where a mover overlaps a wall, which is why it stayed hidden until the proof went looking.
Step 3: the win asked before the wisp moves, and a wall that blocks even with the wisp behind it
+19-5
| 140 | 140 | ld a, (game_state) | |
| 141 | 141 | cp STATE_PLAY | |
| 142 | 142 | ret nz | |
| 143 | + | ; the win check comes FIRST, before the wisp gets its move. Lighting | |
| 144 | + | ; the last lamp holds the night this instant: if the set is complete | |
| 145 | + | ; and the wisp reaches you on the very same frame, you still win — you | |
| 146 | + | ; finished before it touched you. Ask the wisp first and a tie falls | |
| 147 | + | ; the wrong way, stealing a night you had already held. | |
| 148 | + | ld a, (lit_count) | |
| 149 | + | cp NUM_LAMPS | |
| 150 | + | jr z, .night_held | |
| 143 | 151 | call draught_step | |
| 144 | 152 | ld a, (game_state) | |
| 145 | 153 | cp STATE_PLAY | |
| 146 | - | ret nz | |
| 147 | - | ; the win check, at the only beat the count can have changed | |
| 148 | - | ld a, (lit_count) | |
| 149 | - | cp NUM_LAMPS | |
| 150 | 154 | ret nz | |
| 155 | + | ret | |
| 156 | + | .night_held: | |
| 151 | 157 | ; the night is held — the lives you kept are the score | |
| 152 | 158 | ld a, (lives) | |
| 153 | 159 | ld hl, best_lives | |
| ... | |||
| 557 | 563 | ld hl, draught_row | |
| 558 | 564 | cp (hl) | |
| 559 | 565 | jr nz, .pcommit | |
| 560 | - | call lose_life ; walking into the cold costs the same | |
| 566 | + | ; the wisp is on the target cell — but is that cell really a wall? | |
| 567 | + | ; wall_at read the live attribute and saw the wisp's own (WALL_BIT | |
| 568 | + | ; clear), so it waved the step through. The truth is in the wisp's | |
| 569 | + | ; buffer: the ground it stands on. A wall there still blocks — the | |
| 570 | + | ; cold cannot reach you through the brick it is passing behind. | |
| 571 | + | ld a, (under_draught + 8) | |
| 572 | + | bit WALL_BIT, a | |
| 573 | + | ret nz ; real wall under the wisp — blocked, harmless | |
| 574 | + | call lose_life ; open ground — the cold touches, and it costs | |
| 561 | 575 | ret | |
| 562 | 576 | | |
| 563 | 577 | .pcommit: |
The complete program
; Gloaming — Unit 20: Again
; Cumulative build; every step runs on its own. Narrative: the unit page.
; Win or lose, SPACE returns to a title that remembers — the state machine closes.
org 32768
COBBLE equ %00000001 ; PAPER black (0), INK blue (1) — dark ground
WALL equ %00001111 ; PAPER blue (1), INK white (7) — pale stone
WALL_BIT equ 3 ; the attribute bit that says "this is wall"
LAMP_ATTR equ %01000111 ; BRIGHT, PAPER black, INK white — his own light
LAMP_UNLIT equ %00000101 ; cold cyan INK on black PAPER — bit 3
; clear, so a lamp reads as floor
LAMP_LIT equ %01000110 ; BRIGHT yellow INK on black — a held flame
DRAUGHT_ATTR equ %01000101 ; the wisp: BRIGHT cyan on black — cold light
LIVES equ 3
LIFE_PIP equ %01010000 ; a life: BRIGHT red PAPER — a small ember
LIFE_BASE equ $5800 + 28 ; row 0, right of the ledge — three cells
DRAUGHT_SPEED equ 16 ; frames between the wisp's steps
DRAUGHT_COL0 equ 28 ; the corner the dark enters from
DRAUGHT_ROW0 equ 4
PIP_UNLIT equ %00101000 ; a cold pip: cyan PAPER, a solid block
PIP_LIT equ %01110000 ; a warm pip: BRIGHT yellow PAPER
PIP_BASE equ $5800 + 12 ; row 0, column 12 — the HUD ledge,
; eight cells, centred over the square
NUM_LAMPS equ 8
MSG_ATTR equ %01000111 ; message text: bright white on black
MSG_ROW equ 11
LOSE_COL equ 10 ; centres the eleven characters
WIN_COL equ 7 ; centres the seventeen characters
FONT equ $3C00 ; the ROM font, addressed so that
; ASCII x 8 lands on the right glyph
STATE_TITLE equ 0
STATE_PLAY equ 1
STATE_WIN equ 2 ; the night is held — the game is won
STATE_LOSE equ 3 ; night falls — the game is lost
LOCK equ 25 ; input-lock frames after entering a screen
SPEAKER equ %00010000 ; port $FE bit 4 — the beeper's one bit
TITLE_COL equ 12 ; GLOAMING, centred
PROMPT_COL equ 10 ; PRESS SPACE, centred
TITLE_ROW equ 8
PROMPT_ROW equ 14
CONT_ROW equ 16 ; "PRESS SPACE" under a win/lose line
START_COL equ 15 ; where the lamplighter begins
START_ROW equ 11
PLAYER_REPEAT equ 6 ; frames between steps while a key is held
GATHER equ 120 ; frames the dark gathers before its first step
KEYS_OP equ $DFFE ; half-row P O I U Y — bits 1 and 0
KEYS_Q equ $FBFE ; half-row Q W E R T — bit 0 is Q
KEYS_A equ $FDFE ; half-row A S D F G — bit 0 is A
KEYS_SPACE equ $7FFE ; half-row SPACE SYM M N B — bit 0
start:
; --- the border goes black — the night beyond the square ---
; Port $FE bits 0-2 set the BORDER colour. A = 0 = black.
ld a, 0
out ($FE), a
ld a, STATE_TITLE
ld (game_state), a
call draw_title_screen
im 1
ei
call chime_dusk ; after EI — the rests need the interrupt
main_loop:
halt
; the dispatch: each state names what a frame means — the
; title listens for a beginning, PLAY beats the game forward,
; WIN and LOSE hold the screen exactly as it stands
ld a, (game_state)
cp STATE_TITLE
jr z, .do_title
cp STATE_PLAY
jr z, .do_play
call end_step ; WIN or LOSE — wait for a key, then title
jr main_loop
.do_title:
call title_step
jr main_loop
.do_play:
call play_step
jr main_loop
; ----------------------------------------------------------------------------
; title_step — SPACE starts a fresh game.
; ----------------------------------------------------------------------------
title_step:
ld a, (input_lock)
or a
jr z, .tready
dec a
ld (input_lock), a
ret
.tready:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call init_game
ld a, STATE_PLAY
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; end_step — WIN or LOSE: SPACE returns to the title.
; ----------------------------------------------------------------------------
end_step:
ld a, (input_lock)
or a
jr z, .eready
dec a
ld (input_lock), a
ret
.eready:
ld bc, KEYS_SPACE
in a, (c)
bit 0, a
ret nz
call draw_title_screen
call chime_dusk
ld a, LOCK
ld (input_lock), a
ld a, STATE_TITLE
ld (game_state), a
ret
; play_step — one beat of the game: ask the keyboard.
play_step:
call player_step
; contact can end the game mid-frame — if it did, stop here
ld a, (game_state)
cp STATE_PLAY
ret nz
; the win check comes FIRST, before the wisp gets its move. Lighting
; the last lamp holds the night this instant: if the set is complete
; and the wisp reaches you on the very same frame, you still win — you
; finished before it touched you. Ask the wisp first and a tie falls
; the wrong way, stealing a night you had already held.
ld a, (lit_count)
cp NUM_LAMPS
jr z, .night_held
call draught_step
ld a, (game_state)
cp STATE_PLAY
ret nz
ret
.night_held:
; the night is held — the lives you kept are the score
ld a, (lives)
ld hl, best_lives
cp (hl)
jr c, .nobest
ld (hl), a
.nobest:
call draw_win_screen
call fanfare_held
ld a, LOCK
ld (input_lock), a
ld a, STATE_WIN
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; init_game — everything a fresh night needs, gathered from what was
; the boot sequence. Beginning is a callable thing now.
; ----------------------------------------------------------------------------
init_game:
xor a
ld (lit_count), a
ld a, LIVES
ld (lives), a
; --- place the lamplighter ---
; His position is data. Everything that draws him reads it.
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
; --- and, in the far corner, something else ---
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
; the dark gathers before its first step — a beat to read
; the square before the hunt begins
ld a, GATHER
ld (draught_timer), a
xor a
ld (player_timer), a
; --- wipe the canvas ---
; The bitmap ($4000-$57FF) is the pixel layer; whatever was on
; screen before us still lives there. Zero it so only our
; attribute colours show.
call clear_bitmap
; --- texture the ground ---
; Blit the cobble stipple into every cell's bitmap, rows 1-23.
; The attributes will colour these pixels in a moment.
call fill_ground
; --- wash in the cobbles ---
; Seed the first attribute cell, point DE one cell ahead, and
; let LDIR cascade the byte through all 768 cells.
ld hl, $5800
ld de, $5801
ld (hl), COBBLE
ld bc, 767
ldir
call warm_walls
call paint_buildings
; --- brick the walls ---
; Now that the wall cells are painted, fill_walls can read the
; map back and lay brick wherever the wall bit is set.
call fill_walls
call draw_pips
call draw_lives
call draw_lamps
; save what he is about to stand on, BEFORE the first draw
call save_under
call draw_lamp
call save_draught
call draw_draught
ret
; ----------------------------------------------------------------------------
; warm_walls — the square's edge, one attribute write per cell; the
; colour is no longer a constant but the wall_ramp entry for how many
; lamps are lit. Same painting loop as ever — only where C comes from
; has changed.
; ----------------------------------------------------------------------------
warm_walls:
ld a, (lit_count)
ld e, a
ld d, 0
ld hl, wall_ramp
add hl, de
ld c, (hl) ; the byte every wall cell gets
; the top wall: row 1 is 32 cells in a row from $5820
; (row 0 is kept back — it becomes the HUD later)
ld hl, $5820
ld b, 32
.wt:
ld (hl), c
inc hl
djnz .wt
; the bottom wall: row 23, 32 cells from $5AE0
ld hl, $5AE0
ld b, 32
.wb:
ld (hl), c
inc hl
djnz .wb
; the side walls: column 0 and column 31 of rows 1-23.
; Write the row's first cell, hop 31 cells to its last,
; then step a full row (32) down — 23 times.
ld hl, $5820
ld b, 23
.ws:
ld (hl), c
push hl
ld de, 31
add hl, de
ld (hl), c
pop hl
ld de, 32
add hl, de
djnz .ws
ret
; ----------------------------------------------------------------------------
; The beeper. One bit on port $FE: set it, wait, clear it, wait — a
; square wave by hand. C is the half-period (pitch: bigger is lower),
; B the number of cycles (duration). DI while it sounds: the 50 Hz
; interrupt would stretch random half-periods and buzz the tone.
; ----------------------------------------------------------------------------
beep:
di
.bcyc:
ld a, SPEAKER
out ($FE), a
ld a, c
.bd1:
dec a
jr nz, .bd1
xor a
out ($FE), a
ld a, c
.bd2:
dec a
jr nz, .bd2
djnz .bcyc
ei
ret
blip_lit: ; a rising third — the lamp catches
ld b, $17 ; C6
ld c, $67
call beep
ld b, $28 ; E6
ld c, $51
jp beep
chime_dusk: ; two cold tolls, then the motif far off
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 10
call rest
ld b, $84 ; A4
ld c, $F7
call beep
ld b, 13
call rest
ld b, $92 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $9D ; C5
ld c, $CF
jp beep
; rest — B frames of silence. Musical time rides the heartbeat: the
; gaps between notes are counted in HALTs, not busy-loops.
rest:
halt
djnz rest
ret
fanfare_held: ; THE NIGHT IS HELD — a rising run
ld b, $83 ; C5
ld c, $CF
call beep
ld b, 3
call rest
ld b, $A5 ; E5
ld c, $A4
call beep
ld b, 3
call rest
ld b, $C4 ; G5
ld c, $8A
call beep
ld b, 3
call rest
ld b, $FF ; C6, held — B only counts to 255,
ld c, $67
call beep
ld b, $FF ; so hold it by sounding it twice
ld c, $67
jp beep
sting_nightfall: ; NIGHT FALLS — two steps down, then dark
ld b, $53 ; E5
ld c, $A4
call beep
ld b, 4
call rest
ld b, $49 ; D5
ld c, $B8
call beep
ld b, 4
call rest
ld b, $DC ; A4, long — the night settles on it
ld c, $F7
jp beep
; ----------------------------------------------------------------------------
; Screens.
; ----------------------------------------------------------------------------
; draw_win_screen — lift the lamplighter off the board (restore his
; cell: the eighth lamp, lit, comes out of the buffer), then say it.
; draw_title_screen — sparse and suggestive: a black void, the name,
; the invitation. Everything else is left to the imagination, which
; is both the aesthetic and the budget.
draw_title_screen:
call clear_bitmap
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, title_text
ld b, TITLE_ROW
ld c, TITLE_COL
call print_string
ld hl, prompt_text
ld b, PROMPT_ROW
ld c, PROMPT_COL
call print_string
; your best night — the lives you kept on your finest win,
; read in lamps (no digits). It survives the loop back to
; the title: the go-again hook.
ld hl, $5800 + 11 * 32 + 14
ld b, LIVES
ld a, (best_lives)
ld c, a
.tpip:
ld a, PIP_UNLIT
inc c
dec c
jr z, .tpcold
ld a, PIP_LIT
dec c
.tpcold:
ld (hl), a
inc hl
djnz .tpip
ret
draw_win_screen:
call restore_under
ld hl, win_text
ld b, MSG_ROW
ld c, WIN_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; draw_lose_screen — the whole attribute table goes black: every lamp,
; every wall, every warm cell, gone in one LDIR. Then the words.
draw_lose_screen:
ld hl, $5800
ld de, $5801
ld (hl), %00000000
ld bc, 767
ldir
ld hl, lose_text
ld b, MSG_ROW
ld c, LOSE_COL
call print_string
ld hl, prompt_text
ld b, CONT_ROW
ld c, PROMPT_COL
call print_string
ret
; ----------------------------------------------------------------------------
; clear_bitmap — zero the pixel layer, $4000-$57FF, with the same
; seed-and-cascade LDIR idiom the cobble wash uses.
; ----------------------------------------------------------------------------
clear_bitmap:
ld hl, $4000
ld de, $4001
ld (hl), 0
ld bc, 6143
ldir
ret
; ----------------------------------------------------------------------------
; player_step — the keys become movement. Each direction key edits a
; TARGET position (tcol, trow) — a proposal, not yet a move — so it
; can be vetoed before it becomes real. Then the move commits: leave
; the old cell, take the new one, draw.
; ----------------------------------------------------------------------------
player_step:
; --- propose: the target starts where he stands ---
ld a, (lamp_col)
ld (tcol), a
ld a, (lamp_row)
ld (trow), a
; The held-key gate: the first press steps at once, then one
; step every PLAYER_REPEAT frames. Releasing every direction
; key re-arms the instant first step, so taps stay crisp.
ld bc, KEYS_OP
in a, (c)
cpl
and %00000011
ld e, a
ld bc, KEYS_Q
in a, (c)
cpl
and %00000001
or e
ld e, a
ld bc, KEYS_A
in a, (c)
cpl
and %00000001
or e
jr nz, .held
xor a
ld (player_timer), a
ret
.held:
ld a, (player_timer)
or a
jr z, .stepnow
dec a
ld (player_timer), a
ret
.stepnow:
ld a, PLAYER_REPEAT
ld (player_timer), a
ld bc, KEYS_OP
in a, (c)
bit 1, a ; O — a zero bit is a pressed key
jr z, .pleft
bit 0, a ; P, same half-row
jr z, .pright
ld bc, KEYS_Q
in a, (c)
bit 0, a ; Q
jr z, .pup
ld bc, KEYS_A
in a, (c)
bit 0, a ; A
jr z, .pdown
ret ; nothing held — nothing to do
.pleft:
ld hl, tcol
dec (hl)
jr .pmove
.pright:
ld hl, tcol
inc (hl)
jr .pmove
.pup:
ld hl, trow
dec (hl)
jr .pmove
.pdown:
ld hl, trow
inc (hl)
.pmove:
; The veto: ask the target cell's attribute whether it's wall.
; NZ means brick — the proposal dies here and he stays put.
ld a, (trow)
ld b, a
ld a, (tcol)
ld c, a
call wall_at
ret nz
; and the mirror rule: he cannot step onto the wisp either
ld a, (tcol)
ld hl, draught_col
cp (hl)
jr nz, .pcommit
ld a, (trow)
ld hl, draught_row
cp (hl)
jr nz, .pcommit
; the wisp is on the target cell — but is that cell really a wall?
; wall_at read the live attribute and saw the wisp's own (WALL_BIT
; clear), so it waved the step through. The truth is in the wisp's
; buffer: the ground it stands on. A wall there still blocks — the
; cold cannot reach you through the brick it is passing behind.
ld a, (under_draught + 8)
bit WALL_BIT, a
ret nz ; real wall under the wisp — blocked, harmless
call lose_life ; open ground — the cold touches, and it costs
ret
.pcommit:
; --- commit: restore, step, save, draw — in that order ---
call restore_under
ld a, (tcol)
ld (lamp_col), a
ld a, (trow)
ld (lamp_row), a
call save_under
; light it where it lives: while he covers the lamp, its truth
; is the buffer — rewrite the saved attribute, and restore will
; paint the lamp back lit when he leaves
ld a, (under_lamp + 8)
cp LAMP_UNLIT
jr nz, .pdrawn
ld a, LAMP_LIT
ld (under_lamp + 8), a
call light_pip
call blip_lit
call warm_walls
.pdrawn:
call draw_lamp
ret
; ----------------------------------------------------------------------------
; fill_ground — the cobble stipple. Not decoration: the stipple is what
; makes ground-state changes visible later, when the game starts
; recolouring these pixels. Rows 1-23 (row 0 is the HUD).
; ----------------------------------------------------------------------------
fill_ground:
ld b, 1 ; rows 1-23 (row 0 is the HUD)
.fgr:
ld c, 0
.fgc:
ld de, cobble_tex
call blit_tex
inc c
ld a, c
cp 32
jr c, .fgc
inc b
ld a, b
cp 24
jr c, .fgr
ret
; fill_walls — brickwork. Driven by the wall attribute bit, so anything
; painted as wall — now or later in the game — gets its brick for free:
; the map itself decides where the brick goes.
fill_walls:
ld b, 1
.fwr:
ld c, 0
.fwc:
push bc
call attr_addr_cr
bit WALL_BIT, (hl)
pop bc
jr z, .fwn
ld de, brick_tex
call blit_tex
.fwn:
inc c
ld a, c
cp 32
jr c, .fwc
inc b
ld a, b
cp 24
jr c, .fwr
ret
; blit_tex — write the 8-byte texture at DE into cell (C, B)'s bitmap.
; scr_addr_cr finds the cell's first pixel row; INC H steps down the
; other seven, 256 bytes apart.
blit_tex:
push bc
call scr_addr_cr
ld b, 8
.bt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .bt
pop bc
ret
cobble_tex:
defb %10000010
defb %00000000
defb %00001000
defb %00000000
defb %00100001
defb %00000000
defb %00010000
defb %00000000
brick_tex:
; mortar courses with staggered verticals — dusk-lit stone
defb %00001000
defb %00001000
defb %00001000
defb %11111111
defb %10000000
defb %10000000
defb %10000000
defb %11111111
; ----------------------------------------------------------------------------
; draught_step — the hunt. One rule: step one cell along the axis with
; the greater distance to the lamplighter (ties go sideways). No walls,
; no vetoes — the wisp is not of the town, and stone means nothing to it.
; ----------------------------------------------------------------------------
draught_step:
ld a, (draught_timer)
dec a
ld (draught_timer), a
ret nz
ld a, DRAUGHT_SPEED
ld (draught_timer), a
; the dark hunts the lamplighter's own flame
ld a, (lamp_col)
ld (seek_col), a
ld a, (lamp_row)
ld (seek_row), a
.chase:
; step one cell along the axis with the greater distance
; (ties go sideways) — the night is 4-connected, like the
; lamplighter
ld a, (draught_col)
ld (dtcol), a
ld a, (draught_row)
ld (dtrow), a
ld a, (seek_col)
ld hl, draught_col
sub (hl)
jp p, .absc
neg
.absc:
ld d, a ; D = |dc|
ld a, (seek_row)
ld hl, draught_row
sub (hl)
jp p, .absr
neg
.absr:
cp d ; |dr| vs |dc|
jr z, .tie
jr c, .horiz
jr .vert
.tie:
ld a, d
or a
ret z ; already on the light
jr .horiz
.horiz:
ld a, (seek_col)
ld hl, draught_col
cp (hl)
jr c, .hleft
ld a, (hl)
inc a
ld (dtcol), a
jr .contact
.hleft:
ld a, (hl)
dec a
ld (dtcol), a
jr .contact
.vert:
ld a, (seek_row)
ld hl, draught_row
cp (hl)
jr c, .vup
ld a, (hl)
inc a
ld (dtrow), a
jr .contact
.vup:
ld a, (hl)
dec a
ld (dtrow), a
.contact:
; never step ONTO the lamplighter: adjacent is as close as
; the night comes. Two movers, two buffers — and one cell
; can only ever be under one of them.
ld a, (dtcol)
ld hl, lamp_col
cp (hl)
jr nz, .dmove
ld a, (dtrow)
ld hl, lamp_row
cp (hl)
jr nz, .dmove
call lose_life ; the touch, priced
ret
.dmove:
call restore_draught
ld a, (dtcol)
ld (draught_col), a
ld a, (dtrow)
ld (draught_row), a
call save_draught
call draw_draught
ret
; paint_buildings — walk the rectangle table: each entry is col, row,
; width, height; $FF ends the list. Every cell inside a rectangle gets
; the WALL attribute — and because fill_walls textures by the wall bit,
; the brickwork arrives without another line of drawing code.
paint_buildings:
ld hl, bldg_data
.pb:
ld a, (hl)
cp $FF
ret z
ld c, a ; col
inc hl
ld b, (hl) ; row
inc hl
ld d, (hl) ; width
inc hl
ld e, (hl) ; height
inc hl
push hl
.pbrow:
push bc
push de
.pbcol:
push bc
push de
call attr_addr_cr
ld (hl), WALL
pop de
pop bc
inc c
dec d
jr nz, .pbcol
pop de
pop bc
inc b
dec e
jr nz, .pbrow
pop hl
jr .pb
bldg_data:
defb 5, 5, 4, 3
defb 23, 5, 4, 3
defb $FF
; ----------------------------------------------------------------------------
; lose_life — the price of the touch: one ember out, and either a
; fresh start or the fall of night.
; ----------------------------------------------------------------------------
lose_life:
ld a, (lives)
dec a
ld (lives), a
ld e, a
ld d, 0
ld hl, LIFE_BASE
add hl, de
ld (hl), COBBLE ; the ember at the new count goes out
ld a, (lives)
or a
jr z, .gone
; a life left: the lamplighter returns to the start cell
call restore_under
ld a, START_COL
ld (lamp_col), a
ld a, START_ROW
ld (lamp_row), a
call save_under
call draw_lamp
; the taking costs the night its reach — the wisp recoils to
; the far corner, so every life buys a whole fresh chase
; (leaving it beside the respawn made a catch strip every
; life in seconds once the draught learnt to hunt)
call restore_draught
ld a, DRAUGHT_COL0
ld (draught_col), a
ld a, DRAUGHT_ROW0
ld (draught_row), a
ld a, DRAUGHT_SPEED
ld (draught_timer), a
call save_draught
call draw_draught
ret
.gone:
call draw_lose_screen
call sting_nightfall
ld a, LOCK
ld (input_lock), a
ld a, STATE_LOSE
ld (game_state), a
ret
; ----------------------------------------------------------------------------
; print_string / print_char — the machine's own letters. The Spectrum
; keeps its font in ROM: eight bytes per character, and FONT is chosen
; so that ASCII code x 8 + FONT is the glyph's address. Each character
; is drawn like any cell: attribute first, eight rows down the cell.
; ----------------------------------------------------------------------------
print_string:
.ps:
ld a, (hl)
cp $FF
ret z
push hl
push bc
call print_char
pop bc
pop hl
inc hl
inc c
jr .ps
print_char:
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
ld de, FONT
add hl, de
ex de, hl
push de
call attr_addr_cr
ld (hl), MSG_ATTR
call scr_addr_cr
pop de
ld b, 8
.pc:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .pc
ret
; ----------------------------------------------------------------------------
; light_pip / draw_pips / draw_lives.
; ----------------------------------------------------------------------------
; light_pip — warm the next pip along and count the lamp. lit_count is
; the index of the pip to light AND the number of lamps lit so far —
; read it for the address, then step it.
light_pip:
ld a, (lit_count)
ld e, a
ld d, 0
inc a
ld (lit_count), a
ld hl, PIP_BASE
add hl, de
ld (hl), PIP_LIT
ret
; draw_pips — the tally row: one cell per lamp on the HUD ledge, all
; cold to start. A pip is pure attribute — no glyph, just a block of
; PAPER — so the row costs eight bytes of screen and no bitmap at all.
draw_pips:
ld hl, PIP_BASE
ld b, NUM_LAMPS
ld a, PIP_UNLIT
.dp:
ld (hl), a
inc hl
djnz .dp
ret
; draw_lives — three embers on the ledge's right shoulder.
draw_lives:
ld hl, LIFE_BASE
ld b, LIVES
ld a, LIFE_PIP
.dlv:
ld (hl), a
inc hl
djnz .dlv
ret
; ----------------------------------------------------------------------------
; draw_lamps — walk the position table: col, row pairs, $FF to finish.
; Placement is data; the drawing code neither knows nor cares how many
; lamps the town has tonight.
; ----------------------------------------------------------------------------
draw_lamps:
ld hl, lamp_data
.next:
ld a, (hl)
cp $FF
ret z
ld c, a
inc hl
ld b, (hl)
inc hl
push hl
call draw_lantern
pop hl
jr .next
; draw_lantern — an unlit lamp into cell (C, B): cold cyan attribute,
; then the lantern glyph down the cell like any texture.
draw_lantern:
call attr_addr_cr
ld (hl), LAMP_UNLIT
call scr_addr_cr
ld de, lantern
ld b, 8
.dlt:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dlt
ret
; ----------------------------------------------------------------------------
; scr_addr_cr — HL = bitmap address of cell (C, B)'s first pixel row.
; The row's top two bits pick the third of the screen (H), its bottom
; three become L's top bits, and the column fills L's low five.
; ----------------------------------------------------------------------------
scr_addr_cr:
ld a, b
and %00011000 ; the third (row bits 4-3) ...
or %01000000 ; ... under the screen base $40xx
ld h, a
ld a, b
and %00000111 ; the char row within the third ...
rrca ; ... rotated into bits 7-5
rrca
rrca
or c ; the column in bits 4-0
ld l, a
ret
; attr_addr_cr — HL = attribute address of cell (C, B):
; $5800 + row*32 + col, the row shifted up five times.
attr_addr_cr:
ld a, b
ld l, a
ld h, 0
add hl, hl
add hl, hl
add hl, hl
add hl, hl
add hl, hl
ld de, $5800
add hl, de
ld a, c
ld e, a
ld d, 0
add hl, de
ret
; wall_at — is cell (C, B) wall? The answer is already on the screen:
; every wall cell's attribute has WALL_BIT set, so one bit-test of
; attribute memory is the whole collision system. NZ = wall.
wall_at:
call attr_addr_cr
bit WALL_BIT, (hl)
ret
; ----------------------------------------------------------------------------
; The lamplighter's save / restore / draw.
; ----------------------------------------------------------------------------
; pos_bc — the lamplighter's cell into (C, B), read fresh from the data.
pos_bc:
ld a, (lamp_row)
ld b, a
ld a, (lamp_col)
ld c, a
ret
; save_under — copy the nine bytes of his cell into the buffer: eight
; bitmap rows, then the attribute. Runs as he ARRIVES, before the
; draw — so the buffer always holds true ground, never him.
save_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.su:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .su
call pos_bc
call attr_addr_cr
ld a, (hl)
ld (under_lamp + 8), a
ret
; restore_under — the same nine bytes back the other way: the ground
; returns exactly as it was. Runs as he LEAVES, while the position
; still points at the old cell.
restore_under:
call pos_bc
call scr_addr_cr
ld de, under_lamp
ld b, 8
.ru:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .ru
call pos_bc
call attr_addr_cr
ld a, (under_lamp + 8)
ld (hl), a
ret
draw_lamp:
; his colour first: the cell's attribute becomes his own —
; bright white on the black, his own light about him
call pos_bc
call attr_addr_cr
ld (hl), LAMP_ATTR
; then his shape, eight bytes down the cell like any texture
call pos_bc
call scr_addr_cr
ld de, lamplighter
ld b, 8
.dl:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dl
ret
; ----------------------------------------------------------------------------
; The draught's save / restore / draw — the lamplighter's engine, twice.
; Same loops, same nine-byte contract, its own buffer and its own
; position: two movers can share a world but never a buffer.
; ----------------------------------------------------------------------------
dpos_bc:
ld a, (draught_row)
ld b, a
ld a, (draught_col)
ld c, a
ret
save_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.sd:
ld a, (hl)
ld (de), a
inc de
inc h
djnz .sd
call dpos_bc
call attr_addr_cr
ld a, (hl)
ld (under_draught + 8), a
ret
restore_draught:
call dpos_bc
call scr_addr_cr
ld de, under_draught
ld b, 8
.rd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .rd
call dpos_bc
call attr_addr_cr
ld a, (under_draught + 8)
ld (hl), a
ret
draw_draught:
call dpos_bc
call attr_addr_cr
ld (hl), DRAUGHT_ATTR
call dpos_bc
call scr_addr_cr
ld de, draught_glyph
ld b, 8
.dd:
ld a, (de)
ld (hl), a
inc de
inc h
djnz .dd
ret
; ----------------------------------------------------------------------------
; Data.
; ----------------------------------------------------------------------------
game_state:
defb STATE_TITLE
input_lock:
defb 0
wall_ramp:
; The square warms in the game's own vocabulary: the stone
; stays dusk-blue; the lamplight catches the mortar first
; (ink white -> yellow), then the whole face glows BRIGHT.
; Never magenta — warmth is yellow here, not red-shifted blue.
defb %00001111 ; dusk stone, white mortar
defb %00001111
defb %00001111
defb %00001110 ; the mortar warms — yellow ink
defb %00001110
defb %00001110
defb %01001110 ; the stone catches the glow — BRIGHT
defb %01001110
defb %01110000 ; all eight lit: the square aglow —
; warm yellow stone, only at the win
lamp_data:
defb 4, 3
defb 27, 3
defb 9, 7
defb 22, 7
defb 6, 15
defb 25, 15
defb 13, 20
defb 18, 20
defb $FF
lamp_col:
defb START_COL
lamp_row:
defb START_ROW
tcol:
defb 0
trow:
defb 0
lit_count:
defb 0
lives:
defb LIVES
best_lives:
defb 0 ; lives kept on the finest win — never reset
draught_col:
defb 28
draught_row:
defb 4
draught_timer:
defb 16
player_timer:
defb 0
seek_col:
defb 0
seek_row:
defb 0
dtcol:
defb 0
dtrow:
defb 0
under_lamp:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
under_draught:
defb 0, 0, 0, 0, 0, 0, 0, 0, 0
lamplighter:
defb %00111100
defb %00111100
defb %00011000
defb %01111110
defb %00011000
defb %00011000
defb %00100100
defb %01000010
lantern:
defb %00011000
defb %00100100
defb %01111110
defb %01111110
defb %01011010
defb %01111110
defb %01111110
defb %00111100
draught_glyph:
defb %00000000
defb %00111100
defb %01111110
defb %11111111
defb %11111111
defb %01111110
defb %00111100
defb %00000000
title_text:
defb "GLOAMING"
defb $FF
prompt_text:
defb "PRESS SPACE"
defb $FF
win_text:
defb "THE NIGHT IS HELD"
defb $FF
lose_text:
defb "NIGHT FALLS"
defb $FF
end start
Neither bug was invented for a lesson — both shipped, and both were caught the only way bugs like them ever are: by driving the game to its endings on purpose and watching, frame by frame, for the moment the machine does the wrong thing. That is what the winnability gate is for, and step-03 is the game with the gate’s findings closed — the build the shipped gloaming-m1 now becomes.
When it’s wrong, see why
- The end screens ignore SPACE forever. The dispatch never routes WIN/LOSE frames to
end_step— the Unit 15 “hold” was a dead end by design; the call must replace it, not join it. - A new game starts with the old game’s board showing through. The return path skipped
draw_title_screen, or starting skippedinit_game— every arrow in the machine has both a state write and a scene change, and they travel together. - The best row shows your latest win, not your best. The update is an unconditional store — it needs the compare: only write when the new night beats the old (
cp (hl)/jr cpast the store). - The best row is always full, or garbage. The pip loop’s count is wrong, or
best_livesgot swept intoinit_game— in which case it’s reborn as zero with everything else, and the title has amnesia. Persistence by omission cuts both ways: what you exclude survives, what you include forgets. - Screens still occasionally blink past. A transition is missing its
LOCKarm — all three entries (WIN, LOSE, back-to-TITLE) need it; the one you forget is the one the player finds. - A won game reads NIGHT FALLS. The win check sits after
draught_step, so a catch on the very frame you complete the set pre-empts a victory you’d earned. Move thelit_counttest ahead of the wisp’s move — finishing beats being reached. - A harmless wall-bump kills you.
wall_atread the wisp’s own attribute off the screen and waved the step through; the mirror rule then priced the bump as contact. When the target cell holds the wisp, askunder_draughtfor the real ground, not the screen.
Before and after — and the module, closed
The unit itself is small: one new step routine, one byte of memory, one byte of patience — and then two corrections the proof insisted on. But step back, because something bigger just happened. The build this module converged on is gloaming-m1 — the shipped game — byte for byte. Not similar; identical. Every unit ended by proving its code matched a checkpoint of the real game, and at step 2 the checkpoints ran out: the square you textured in Unit 2, the dance from Unit 8, the veto from Unit 9, the buffer-edit trick from Unit 12, the draught, the embers, the three phrases, the door, and the loop — they were never a teaching copy of Gloaming. They were Gloaming, assembled in an order that let every mistake teach. The game is yours now, in the strongest sense available to a programmer: you built every byte of it, and you know why each one is there.
And because you know why, you could do the thing shipped code so rarely gets: go back in and make it right. step-03 closes the two faults the winnability gate turned up — the stolen win, the wall that killed — so the shipped gloaming-m1 updates to match. “Byte for byte” still holds: the game you built is the game that ships. It’s just that the game that ships is now correct at the two edges where it wasn’t.
Try this: hold the button down
Remove the three LOCK arms and play the loop with a lazy thumb — hold SPACE a half-beat too long at NIGHT FALLS and watch the title flash past into a game you didn’t ask for. Put them back and feel the thresholds firm up. Then try the stubborn four-second hold with the locks and watch it still slip through — knowing a mechanism’s limits is as valuable as knowing its purpose.
Try this: remember more
best_lives proves the pattern; extend it. A nights_played counter, bumped in init_game itself (a counter of beginnings belongs inside rebirth — think about why), shown on the title as a little cyan row. Or remember a fastest win: count frames during PLAY and keep the minimum. Each is one byte outside the reset and a few cells of title. You’re designing memory now — the question is never “can it persist” but “does it deserve to”.
Try this: a harder night, again
Make the loop mean something: on each return to the title after a win, shave DRAUGHT_SPEED… except it’s an equ — a constant, baked in. To make difficulty persist you’d need it as a variable: a byte the wisp reads, initialised once at boot, tightened outside init_game. Do that conversion — constant to persistent state — and you’ve built new-game-plus in an evening, and felt exactly why “what survives” is a design axis, not a technicality.
Try this: any Spectrum
One last thing a finished game deserves: a wider market. Your whole game is about 1,650 bytes, but it assembles at address 32768 — the first byte above what a 16K Spectrum owns, and in 1983 the 16K machine was half the customers. Two lines fix it. Change the org to 24576, and add ld sp, 32767 as start:’s first instruction — the stack, it turns out, has been sitting at the top of 48K all along, put there by the snapshot rather than by you. Rebuild, and your game now runs on every Spectrum ever sold.
Then listen to it. Walk onto a lamp: the blip plays very slightly flat — about two-thirds of a semitone on its first note. That’s not a bug; that’s contended memory. Below address 32768 the ULA shares the RAM with the processor, stealing cycles while it fetches the picture — and your beeper’s pitch loops are made of exactly those cycles. Every 16K game of the era sounded like this, faintly and always. You’ve just heard the machine’s floor plan, with your ears.
- A loop is an arrow, not a rewind — end screens transition back through the same state machine, scene and state travelling together.
- Persistence by omission: with beginning centralised in
init_game, what survives is precisely what it doesn’t touch — auditable, deliberate, one byte here. - An input lock makes thresholds deliberate — half a second of deafness at each entry, guarding the press that lands long.
- Registers can be tested without being changed —
inc/decas a flags-only read. - A game is proven at its endings — and proving finds bugs. The stolen win and the phase-wall death both hid until a scripted run to each ending went looking. Order the win ahead of the threat; trust the buffer over the screen.
- And the whole of it: twenty units, one game — matched byte for byte to what shipped, then made right where the proof said it wasn’t.
What’s next
Module 1 is complete — Gloaming, held or fallen, one dusk at a time. The file it converged on was itself cut from something larger: the full prototype has pools of dark, a tendril that reaches, a grudge the night keeps, and a dawn that comes if you survive long enough. That game — The Long Night — is Module 2, and it starts from the code you just finished, the way every real sequel does. Before it, take an evening off. Play your game. You made it; the night is held.