Code Like It's 198x

Query a Byte Map on Atari 2600

Read and change map cells, look up tile properties and convert world positions with reusable 6502 code and an explicit memory contract.

A level does not need to be on screen for the game to ask what is there. Give it a byte per cell, keep those bytes in row order, and the same map can answer questions about walls, hazards, goals or scenery that has changed.

This implementation supplies four routines: checked get, checked set, property lookup and conversion from unsigned world positions to eight-unit cells. It does not draw or wait for a frame. The shared entry explains the arrangement and links the implementations across all 30 machines.

Include and initialise

Define TM as the start of a reserved 20-byte context, then include the routine. The map contains W×H consecutive bytes, with width and height each from 1 to 255. Its property table contains one byte per possible ID, through the configured highest ID. Both ranges must remain addressable without crossing an address-space end, bank window or unmapped boundary. Use writable RAM for tile_set; a ROM map needs another way to record changes.

The 6502 context must fit entirely in zero page, and decimal mode must be clear.

Context offsets: 0–1 map pointer; 2/3 width/height; 4/5 column/row; 6 tile; 7 valid; 8–10 scratch; 11 property; 12–13 property pointer; 14 highest tile ID; 15 scratch; 16–17 X; 18–19 Y. Initialise the pointers, dimensions and highest ID before a call. Scratch bytes belong to the routine.

Initialise the diagnostic map and make its first checked query

demo.asm, excerpt
start:
    sei
    cld
    ldx #$ff
    txs
    lda #0
    ldx #19
clear_context:
    sta TM,x
    dex
    bpl clear_context
    ldx #34
copy_map:
    lda initial_map,x
    sta MAP,x
    dex
    bpl copy_map
    lda #$a5
    sta MAP+35
    lda #<MAP
    sta TM
    lda #>MAP
    sta TM+1
    lda #7
    sta TM+2
    lda #5
    sta TM+3
    lda #3
    sta TM+14
    lda #<properties
    sta TM+12
    lda #>properties
    sta TM+13
    lda #0
    sta TM+4
    lda #0
    sta TM+5
    jsr tile_get
    lda TM+7
    cmp #1
    beq valid_0
    lda #255
    sta TM+6

The complete diagnostic uses a 7×5 map. Its context starts at $00B2, results at $0086 and writable map at $00C6. These locations belong to a caller taking over the machine; choose and reserve suitable memory in your own project, accounting for firmware, display, banking and interrupts.

Call the routine

Set column and row, call tile_get, then check the valid byte. A successful call returns the tile ID. Failure returns valid=0 and tile=0, so tile zero alone does not mean success. This compact variant uses unsigned byte coordinates; wider maps can use a wider-coordinate variant rather than treating this as a machine limit. Translate a signed or wider world into this representation explicitly.

For a write, set column/row/tile and call tile_set. Invalid coordinates or an ID above the configured maximum leave the map unchanged. To classify a tile, call tile_property; it returns the table byte and a separate valid flag. Your game decides whether those property bits mean blocking, damage, a goal or something else.

Reusable 6502 map/query implementation

6502.inc
; Byte map, caller-owned zero-page context TM..TM+19. See README.md.
; A/X/Y/flags clobbered. Decimal flag must be clear. No IRQ/stack ownership.
tile_locate:
    lda #0
    sta TM+7
    lda TM+4
    cmp TM+2
    bcs tile_locate_done
    lda TM+5
    cmp TM+3
    bcs tile_locate_done
    lda TM
    sta TM+8
    lda TM+1
    sta TM+9
    lda TM+5
    sta TM+10
    beq tile_column
tile_rows:
    clc
    lda TM+8
    adc TM+2
    sta TM+8
    bcc tile_no_carry
    inc TM+9
tile_no_carry:
    dec TM+10
    bne tile_rows
tile_column:
    clc
    lda TM+8
    adc TM+4
    sta TM+8
    bcc tile_address_ready
    inc TM+9
tile_address_ready:
    lda #1
    sta TM+7
tile_locate_done:
    rts

tile_get:
    jsr tile_locate
    lda TM+7
    beq tile_get_invalid
    ldy #0
    lda (TM+8),y
    sta TM+6
    rts
tile_get_invalid:
    lda #0
    sta TM+6
    rts

tile_set:
    lda #0
    sta TM+7
    lda TM+6
    cmp TM+14
    bcc tile_set_id_ok
    beq tile_set_id_ok
    rts
tile_set_id_ok:
    jsr tile_locate
    lda TM+7
    beq tile_set_done
    ldy #0
    lda TM+6
    sta (TM+8),y
tile_set_done:
    rts

tile_property:
    lda #0
    sta TM+7
    sta TM+11
    lda TM+6
    cmp TM+14
    bcc tile_property_ok
    beq tile_property_ok
    rts
tile_property_ok:
    tay
    lda (TM+12),y
    sta TM+11
    lda #1
    sta TM+7
    rts

; Unsigned 16-bit world X/Y -> eight-unit cells. Does not mutate X/Y.
tile_pixel8:
    lda #0
    sta TM+7
    sta TM+6
    lda TM+16
    sta TM+4
    lda TM+17
    sta TM+15
    ldx #3
tile_shift_x:
    lsr TM+15
    ror TM+4
    dex
    bne tile_shift_x
    lda TM+15
    bne tile_pixel_done
    lda TM+18
    sta TM+5
    lda TM+19
    sta TM+15
    ldx #3
tile_shift_y:
    lsr TM+15
    ror TM+5
    dex
    bne tile_shift_y
    lda TM+15
    bne tile_pixel_done
    jsr tile_get
tile_pixel_done:
    rts

For tile_pixel8, set unsigned 16-bit X and Y in world coordinates. It divides by eight, rejects a cell coordinate too large for a byte, then performs the checked lookup. Read cell/tile outputs only after checking valid. X/Y inputs remain unchanged. Eight-unit square cells are this routine’s deliberate fast conversion; other sizes, wrapping or a signed origin need a corresponding variant.

State, stack and cost

A, X, Y and flags are clobbered. The routines use the current stack and the supplied context. They do not mask or install interrupts. An interrupt caller needs its own context and must preserve the state that the interrupted code needs.

Get/set use 4 bytes of return addresses at their deepest point, including the direct caller’s call into the library. Pixel conversion uses 6; property lookup uses 2. Add the surrounding caller stack and any interrupt frames.

Map storage is W×H bytes, plus highest-ID+1 property bytes, context, code and stack. This readable version adds the row width repeatedly; later rows cost more work. Row-pointer tables or fixed-width shifts are alternatives when query speed matters. There is no whole-game frame-rate claim.

Run and adapt it

make ASM198X=/path/to/asm198x builds the complete original diagnostic. It uses a synthetic reset ROM/cartridge to execute the routines and observe their RAM results. This establishes the query code and its declared memory on this machine; it does not establish a stock BASIC/FORTH loader, video output, IRQ coexistence or a frame deadline.

The caller checks every cell of a non-square map, rejected reads/writes, a map-end guard, a valid change, properties and coordinate conversion. The same observer rejects completed wrong-stride and write-without-valid versions. Its small map remains inside the Atari 2600’s 128-byte RAM window; it is not a TIA display kernel. Use the reusable include in your own program; the unrolled diagnostic queries make observations explicit and are not a proposed game loop.