romdev-mcp 0.1.1

package/src/platforms/atari2600/lib/kernel_skeleton.asm

@@ -0,0 +1,85 @@
+; ── Atari 2600 standard kernel skeleton ───────────────────────────
+; Three-section frame: vertical sync (3 lines) → vertical blank (37 lines)
+; → 192 visible scanlines → 30 lines overscan. This is the canonical
+; NTSC 262-line frame (3 + 37 + 192 + 30 = 262).
+;
+; Drop your per-frame game logic into the `; --- VBLANK work here ---`
+; slot so it runs during the 37-line blanking period (≈ 2812 cycles).
+; Anything that doesn't fit in vblank gets pushed into overscan (30
+; lines ≈ 2280 cycles).
+
+  processor 6502
+  include "vcs_constants.h"
+
+  org $F000
+
+START:
+  SEI
+  CLD
+  LDX #$FF
+  TXS
+  LDA #0
+.clear_ram:
+  STA $00,X
+  DEX
+  BNE .clear_ram
+
+  ; Pick a background color so something renders.
+  LDA #$80           ; blue, mid luma
+  STA COLUBK
+
+; ── Main loop ───────────────────────────────────────────────────────
+MAIN_LOOP:
+  LDA #2
+  STA VSYNC          ; start vsync (bit 1 = on)
+  STA WSYNC
+  STA WSYNC
+  STA WSYNC          ; 3 lines of vsync
+  LDA #0
+  STA VSYNC
+
+  ; ── VBLANK (37 lines) ─────────────────────────────────────────────
+  LDA #VBLANK_ON
+  STA VBLANK
+  LDX #37
+.vb_loop:
+  STA WSYNC
+  ; --- VBLANK work here --------------------------------------------
+  ;  Game logic, controller reads, sprite positioning, etc.
+  ;  Each iteration is one scanline (≈ 76 CPU cycles).
+  ; -----------------------------------------------------------------
+  DEX
+  BNE .vb_loop
+
+  ; ── Visible kernel (192 lines) ────────────────────────────────────
+  LDA #0
+  STA VBLANK         ; turn on the picture
+  LDX #192
+.draw_loop:
+  STA WSYNC
+  ; --- per-scanline graphics writes here ---------------------------
+  ;  Update GRP0/GRP1/PF0/PF1/PF2/ENABL etc. *just before* WSYNC if
+  ;  you want them visible on THIS line.
+  ; -----------------------------------------------------------------
+  DEX
+  BNE .draw_loop
+
+  ; ── Overscan (30 lines) ───────────────────────────────────────────
+  LDA #VBLANK_ON
+  STA VBLANK
+  LDX #30
+.os_loop:
+  STA WSYNC
+  ; --- overscan work here ------------------------------------------
+  ;  Lower-priority logic that didn't fit in vblank.
+  ; -----------------------------------------------------------------
+  DEX
+  BNE .os_loop
+
+  JMP MAIN_LOOP
+
+  ; vector table (always 6 bytes at the top of the bank)
+  org $FFFA
+  .word START        ; NMI (unused on 2600)
+  .word START        ; RESET
+  .word START        ; IRQ (unused unless BRK is used)

package/src/platforms/atari2600/lib/player_kernel.asm

@@ -0,0 +1,87 @@
+; ── Single-player kernel — render an 8x16 sprite via GRP0 ─────────
+; Shows the minimal pattern: load sprite bytes from a table during the
+; visible kernel, WSYNC between lines. Position the player with RESP0
+; (cycle-counted) before the first visible line.
+;
+; ── COPY-PASTE TEMPLATE, not a linkable module ─────────────────────
+; No `org` directives here on purpose — they'd collide with your main
+; ROM layout ("Origin Reverse-indexed") when dasm builds the flat ROM.
+; Inline the routines + PLAYER_SHAPE table into your own source where
+; you want them. Your kernel_skeleton.asm owns the org $F000 / $FFFA.
+;
+; Usage: inline after vcs_constants.h, JSR PLAYER_INIT once after RAM
+; clear, then call PLAYER_FRAME from inside the visible kernel.
+
+  ; --- player position byte lives in zp at $80 (player X 0-159) ---
+PLAYER_X equ $80
+PLAYER_Y equ $81  ; top scanline (0-191)
+
+  ; --- sprite data (8 rows × 1 byte each) — place in your data area
+PLAYER_SHAPE:
+  .byte %00111100
+  .byte %01111110
+  .byte %11011011
+  .byte %11111111
+  .byte %11111111
+  .byte %11011011
+  .byte %01100110
+  .byte %01000010
+
+PLAYER_INIT:
+  ; Default position: roughly center.
+  LDA #80
+  STA PLAYER_X
+  LDA #90
+  STA PLAYER_Y
+  RTS
+
+; ── POS_OBJ_P0 — coarse + fine horizontal position for P0 ──────────
+; Call with the target X column 0..159 in A. This is the canonical
+; "burn cycles equivalent to (X/15) and use the remainder for HMOVE
+; fine adjust" 2600 technique. Same shape works for P1/M0/M1/BL —
+; replace RESP0/HMP0 with the equivalent register pair.
+;
+; Cost: ~12-90 cycles depending on X, plus 3 WSYNCs (~228 cycles
+; total in the worst case). Always call inside VBLANK, never inside
+; the visible kernel.
+;
+; CRITICAL: the SBC #15 loop terminates ONLY when the carry clears;
+; if you forget the SEC before .loop you get an infinite loop. The
+; EOR #$07 + 4× ASL converts the remainder to the HMP0 nibble format
+; (high nibble is signed -8..+7 in 2's-complement-ish form, stored
+; pre-shifted in the high byte).
+POS_OBJ_P0:
+  STA WSYNC          ; sync to line start so timing is deterministic
+  SEC                ; carry SET before SBC chain
+.loop:
+  SBC #15            ; burn 15-cycle chunks
+  BCS .loop          ; until we go negative
+  EOR #$07           ; convert -1..-15 remainder to HMP0 nibble
+  ASL
+  ASL
+  ASL
+  ASL
+  STA RESP0          ; coarse position (whatever column we're at now)
+  STA HMP0           ; fine adjust amount
+  STA WSYNC          ; let RESP0 settle
+  STA HMOVE          ; apply fine adjust
+  STA WSYNC
+  STA HMCLR          ; clear HMP0 so next line doesn't drift
+  RTS
+
+; PLAYER_FRAME — call inside the visible-kernel loop. X holds line index.
+PLAYER_FRAME:
+  ; Is this line within the player sprite range?
+  TXA
+  SEC
+  SBC PLAYER_Y
+  CMP #8
+  BCS .blank          ; outside sprite: blank GRP0
+  TAY
+  LDA PLAYER_SHAPE,Y
+  STA GRP0
+  RTS
+.blank:
+  LDA #0
+  STA GRP0
+  RTS

package/src/platforms/atari2600/lib/playfield_kernel.asm

@@ -0,0 +1,63 @@
+; ── Asymmetric playfield kernel ───────────────────────────────────
+; Renders a 40-pixel-wide playfield from a per-scanline byte table.
+; Each "row" of the playfield is 3 bytes (PF0 high-nibble, PF1, PF2),
+; so a 96-row map needs 288 bytes — well within a 4K cart.
+;
+; This is the foundation for level / maze / "title screen" graphics
+; on the 2600. Pair with `score_kernel.asm` for a status bar.
+;
+; ── COPY-PASTE TEMPLATE, not a linkable module ─────────────────────
+; No `org` directive here — it'd collide with your main ROM layout
+; when dasm builds the flat ROM. Inline these routines + the
+; PLAYFIELD_DATA table into your own source. Your kernel_skeleton.asm
+; owns the org $F000 / $FFFA that define the ROM image.
+
+  ; Per-row playfield bytes: PF0, PF1, PF2 interleaved.
+  ; 96 rows × 3 bytes = 288 bytes.
+  ;
+  ; (PF0 high nibble is what's drawn — low nibble is ignored.)
+PLAYFIELD_TABLE_LO equ $80   ; low byte of current row pointer
+PLAYFIELD_TABLE_HI equ $81
+PLAYFIELD_ROW      equ $82
+
+PLAYFIELD_INIT:
+  LDA #<PLAYFIELD_DATA
+  STA PLAYFIELD_TABLE_LO
+  LDA #>PLAYFIELD_DATA
+  STA PLAYFIELD_TABLE_HI
+  LDA #0
+  STA PLAYFIELD_ROW
+  ; Asymmetric playfield (CTRLPF.SCORE = 0, REFLECT = 0): both halves
+  ; use the same PF0/PF1/PF2 bytes — but for a level map most authors
+  ; instead use CTRLPF_REFLECT for mirroring.
+  LDA #CTRLPF_REFLECT
+  STA CTRLPF
+  RTS
+
+; Call from inside the visible kernel. X = current scanline index.
+PLAYFIELD_LINE:
+  LDA PLAYFIELD_ROW
+  ASL                ; ×2
+  ADC PLAYFIELD_ROW  ; ×3  (Y = row * 3)
+  TAY
+  LDA (PLAYFIELD_TABLE_LO),Y
+  STA PF0
+  INY
+  LDA (PLAYFIELD_TABLE_LO),Y
+  STA PF1
+  INY
+  LDA (PLAYFIELD_TABLE_LO),Y
+  STA PF2
+  INC PLAYFIELD_ROW
+  RTS
+
+  ; 8-row demo map: a hollow rectangle. Each row is PF0, PF1, PF2.
+PLAYFIELD_DATA:
+  .byte $F0, $FF, $FF        ; top border (all on)
+  .byte $10, $00, $80
+  .byte $10, $00, $80
+  .byte $10, $00, $80
+  .byte $10, $00, $80
+  .byte $10, $00, $80
+  .byte $10, $00, $80
+  .byte $F0, $FF, $FF        ; bottom border

package/src/platforms/atari2600/lib/read_joystick.asm

@@ -0,0 +1,76 @@
+; ── Read joystick 0 ────────────────────────────────────────────────
+; Joystick state lives in RIOT register SWCHA ($280). The 4 high bits
+; (P0_RIGHT/LEFT/DOWN/UP) are the player-0 stick directions, ACTIVE-LOW.
+; Bit 7 = right, 6 = left, 5 = down, 4 = up.
+;
+; Fire button is on TIA INPT4 ($3C), latched low when pressed.
+;
+; ── How to use ─────────────────────────────────────────────────────
+; Call READ_JOYSTICK once per frame (in vblank ideally), then test the
+; cached JOY_STATE byte — NEVER re-read SWCHA in the middle of your
+; bit-test chain. Reading SWCHA returns the *live* state, so if you
+; chain `LDA SWCHA / ASL / BCS / ASL / BCS` you'll see different bits
+; on each ASL because the value in A has changed since the last load.
+;
+; THE CLASSIC BUG (cost an agent 30 min): "left works once, right
+; never does" — caused by reading SWCHA twice without re-load, or by
+; ASL-chaining without re-loading A between bit-tests. The cached
+; JOY_STATE pattern below avoids it entirely.
+;
+;   JSR READ_JOYSTICK
+;
+;   ; Pattern A — bit mask (clearest, no ASL chain to mis-count):
+;   LDA JOY_STATE
+;   AND #P0_RIGHT_MASK
+;   BEQ .not_right
+;   ; ... right pressed: do work, freely clobber A ...
+; .not_right:
+;   LDA JOY_STATE          ; ← RE-LOAD before next direction test
+;   AND #P0_LEFT_MASK
+;   BEQ .not_left
+;   ; ... left pressed ...
+; .not_left:
+;   LDA JOY_STATE          ; ← RE-LOAD again
+;   AND #P0_UP_MASK
+;   BEQ .not_up
+;   ; ...
+;
+;   ; Pattern B — ASL chain (cheaper, but you MUST re-load JOY_STATE
+;   ; before the chain and ensure no code path consumes A mid-chain):
+;   LDA JOY_STATE
+;   ASL                    ; carry = bit 7 = RIGHT
+;   BCC .not_right
+;   ; right pressed — do NOT touch A's bits, OR re-load below
+; .not_right:
+;   LDA JOY_STATE          ; ← RE-LOAD if branch body clobbered A
+;   ASL                    ; bit 7 shifted out previously? no — fresh load.
+;   ASL                    ; consume bit 7
+;   ASL                    ; carry = bit 6 = LEFT (counting from MSB-first
+;                          ; after one ASL would be bit 6, etc. — easy to
+;                          ; off-by-one. Pattern A above is safer.)
+;
+; Prefer Pattern A unless you're cycle-counting.
+
+P0_RIGHT_MASK equ $80
+P0_LEFT_MASK  equ $40
+P0_DOWN_MASK  equ $20
+P0_UP_MASK    equ $10
+FIRE_MASK     equ $80    ; bit 7 of FIRE_STATE = pressed
+
+JOY_STATE  equ $90   ; ZP byte holding inverted joystick bits
+FIRE_STATE equ $91   ; ZP byte: bit 7 set if fire pressed
+
+; READ_JOYSTICK — call once per frame. Caches state in JOY_STATE +
+; FIRE_STATE; from then on read those, NOT SWCHA/INPT4 directly.
+READ_JOYSTICK:
+  LDA SWCHA
+  EOR #$FF        ; invert (input is active-low)
+  STA JOY_STATE   ; now bit 7 = right pressed, bit 6 = left, etc.
+
+  LDA INPT4
+  ASL             ; bit 7 → carry (button is bit 7, active-low)
+  LDA #0
+  ROR             ; carry → bit 7
+  EOR #$80        ; flip so "pressed" = $80
+  STA FIRE_STATE
+  RTS

package/src/platforms/atari2600/lib/score_kernel.asm

@@ -0,0 +1,141 @@
+; ── Score-band kernel — top-of-screen 2-digit score via PF1 ───────
+;
+; Renders a 1-2 digit score (0-99) at the top of the visible playfield
+; using PF1 in SCORE mode (CTRLPF bit 1 set). SCORE mode makes the LEFT
+; half of the playfield use P0's color and the RIGHT half use P1's
+; color — so the same playfield bits draw the tens digit (P0 color)
+; on the left half and the ones digit (P1 color) on the right half.
+;
+; This is the canonical 2600 score-display pattern (Combat onward).
+;
+; ── COPY-PASTE TEMPLATE, not a linkable module ─────────────────────
+; This file has NO `org` directive on purpose. dasm builds a flat ROM,
+; and an `org` here would collide with your main code / other snippets
+; ("Origin Reverse-indexed"). Inline the routines + the DIGIT_SHAPES
+; table into your own source wherever you want them to live. Put the
+; DIGIT_SHAPES table somewhere it won't straddle a page boundary
+; relative to your other data (the (ptr),Y reads cross-page fine, but
+; keeping a digit's 8 bytes contiguous is the only requirement).
+;
+; ── How to use ─────────────────────────────────────────────────────
+;   1. Init: write your score (0..99) into SCORE_VALUE (ZP $86),
+;      stored BCD-style — high nibble = tens, low nibble = ones.
+;      (Maintain it with SED math, or split a binary value yourself.)
+;   2. Each frame BEFORE the visible kernel, JSR SCORE_PREP. It splits
+;      SCORE_VALUE into tens/ones and builds two FULL 16-bit pointers
+;      (lo+hi) into DIGIT_SHAPES.
+;   3. Inside the visible kernel, JSR SCORE_KERNEL_BAND at the line
+;      where the score should appear. It eats 8 scanlines + 1 cleanup.
+;   4. Set COLUP0 (tens color) and COLUP1 (ones color), CTRLPF bit 1
+;      (SCORE mode), and zero PF0/PF2 before calling the band.
+;
+; ── Cost ───────────────────────────────────────────────────────────
+;   ROM: ~80 bytes digit shapes + ~55 bytes routines
+;   RAM: 5 bytes — $86 SCORE_VALUE, $87/$88 tens ptr lo/hi,
+;        $89/$8A ones ptr lo/hi.
+;   Cycles: 8 lines × 76 = ~608 per frame.
+
+SCORE_VALUE     equ $86  ; 0..99, BCD: high nibble tens, low nibble ones
+SCORE_PTR_T_LO  equ $87  ; tens-digit shape pointer, LO byte
+SCORE_PTR_T_HI  equ $88  ; tens-digit shape pointer, HI byte
+SCORE_PTR_O_LO  equ $89  ; ones-digit shape pointer, LO byte
+SCORE_PTR_O_HI  equ $8A  ; ones-digit shape pointer, HI byte
+
+; ── Digit shapes — 4 pixels wide × 8 rows each, 10 blocks of 8 bytes.
+;    Pixels live in the HIGH nibble of each byte; the low nibble is
+;    ALWAYS zero. That layout lets SCORE_KERNEL_BAND OR-merge the
+;    ones digit (shifted into the low nibble) without masking. Digit
+;    N starts at offset N*8.
+;
+;    INLINE THIS TABLE into your source (no `org` — place it in your
+;    data area). (ptr),Y indexing handles a page-crossing table fine.
+DIGIT_SHAPES:
+  ; '0'
+  .byte $60,$90,$90,$90,$90,$90,$60,$00
+  ; '1'
+  .byte $20,$60,$20,$20,$20,$20,$70,$00
+  ; '2'
+  .byte $60,$90,$10,$20,$40,$80,$F0,$00
+  ; '3'
+  .byte $60,$90,$10,$60,$10,$90,$60,$00
+  ; '4'
+  .byte $90,$90,$90,$F0,$10,$10,$10,$00
+  ; '5'
+  .byte $F0,$80,$80,$E0,$10,$90,$60,$00
+  ; '6'
+  .byte $60,$90,$80,$E0,$90,$90,$60,$00
+  ; '7'
+  .byte $F0,$10,$20,$20,$40,$40,$40,$00
+  ; '8'
+  .byte $60,$90,$90,$60,$90,$90,$60,$00
+  ; '9'
+  .byte $60,$90,$90,$70,$10,$90,$60,$00
+
+; SCORE_PREP — compute FULL (lo+hi) pointers for the current
+; SCORE_VALUE. Call once per frame BEFORE entering the visible kernel.
+SCORE_PREP:
+  ; Tens: high nibble of SCORE_VALUE → digit, * 8 = byte offset.
+  LDA SCORE_VALUE
+  LSR
+  LSR
+  LSR
+  LSR                  ; A = tens digit (0..9)
+  ASL
+  ASL
+  ASL                  ; A = tens * 8
+  CLC
+  ADC #<DIGIT_SHAPES
+  STA SCORE_PTR_T_LO
+  LDA #>DIGIT_SHAPES
+  ADC #0               ; carry from the LO add (page-cross safe)
+  STA SCORE_PTR_T_HI
+  ; Ones: low nibble * 8.
+  LDA SCORE_VALUE
+  AND #$0F
+  ASL
+  ASL
+  ASL                  ; A = ones * 8
+  CLC
+  ADC #<DIGIT_SHAPES
+  STA SCORE_PTR_O_LO
+  LDA #>DIGIT_SHAPES
+  ADC #0
+  STA SCORE_PTR_O_HI
+  RTS
+
+; SCORE_KERNEL_BAND — render 8 scanlines of score. Composites BOTH
+; digits into ONE PF1 byte per scanline and writes PF1 once. SCORE
+; mode (CTRLPF bit 1) then colors the high-nibble (tens) pixels with
+; P0's color on the left half and the low-nibble (ones) pixels with
+; P1's color on the right half — the classic "10  10" two-color look.
+;
+; Assumes before entry: CTRLPF bit 1 set, COLUP0/COLUP1 set, PF0=PF2=0.
+; Clobbers A, Y, and scratch ZP $94.
+;
+; (Advanced: if you want two TRULY independent digit shapes — e.g.
+; different glyphs whose pixels don't share a single PF1 byte — you
+; need a cycle-tight 2-write kernel where the 2nd STA PF1 lands at
+; CPU cycle >= 38 / visible pixel >= 48. That's harder to get right;
+; the single-write composite below is the standard approach and
+; renders correctly out of the box.)
+SCORE_KERNEL_BAND:
+  LDY #0
+.row:
+  STA WSYNC
+  LDA (SCORE_PTR_T_LO),Y   ; tens row — pixels already in HIGH nibble
+  STA $94                  ; stash (low nibble is 0 by table design)
+  LDA (SCORE_PTR_O_LO),Y   ; ones row — pixels in HIGH nibble
+  LSR
+  LSR
+  LSR
+  LSR                      ; shift ones pixels down into LOW nibble
+  ORA $94                  ; composite: tens(hi) | ones(lo)
+  STA PF1                  ; single write — both halves from one byte
+  INY
+  CPY #8
+  BNE .row
+  ; Clear PF1 so the score band doesn't bleed into the next region.
+  STA WSYNC
+  LDA #0
+  STA PF1
+  RTS

package/src/platforms/atari2600/lib/vcs_constants.h

@@ -0,0 +1,97 @@
+; ── Atari 2600 register map (TIA write + RIOT) ─────────────────────
+; Standard dasm-style constants matching vcs.h from the stella-asm
+; distribution. Include via:  include "vcs_constants.h"
+
+; ── TIA write registers ($00-$2C) ──────────────────────────────────
+VSYNC     equ $00     ; vertical sync set/clear (bit 1)
+VBLANK    equ $01     ; vertical blank + input dump
+WSYNC     equ $02     ; wait for horizontal blank — block until next line
+RSYNC     equ $03     ; reset horizontal sync counter
+NUSIZ0    equ $04     ; player 0 + missile 0 size/count
+NUSIZ1    equ $05     ; player 1 + missile 1 size/count
+COLUP0    equ $06     ; player 0 + missile 0 color/luma
+COLUP1    equ $07     ; player 1 + missile 1 color/luma
+COLUPF    equ $08     ; playfield + ball color/luma
+COLUBK    equ $09     ; background color/luma
+CTRLPF    equ $0A     ; playfield reflect / score / priority / ball size
+REFP0     equ $0B     ; reflect player 0 (bit 3)
+REFP1     equ $0C     ; reflect player 1 (bit 3)
+PF0       equ $0D     ; playfield register 0 (4 high bits)
+PF1       equ $0E     ; playfield register 1 (8 bits)
+PF2       equ $0F     ; playfield register 2 (8 bits, reverse-scan)
+RESP0     equ $10     ; reset player 0 (write triggers, value ignored)
+RESP1     equ $11     ; reset player 1
+RESM0     equ $12     ; reset missile 0
+RESM1     equ $13     ; reset missile 1
+RESBL     equ $14     ; reset ball
+AUDC0     equ $15     ; audio control channel 0
+AUDC1     equ $16     ; audio control channel 1
+AUDF0     equ $17     ; audio frequency channel 0
+AUDF1     equ $18     ; audio frequency channel 1
+AUDV0     equ $19     ; audio volume channel 0
+AUDV1     equ $1A     ; audio volume channel 1
+GRP0      equ $1B     ; graphics for player 0 (8 bits)
+GRP1      equ $1C     ; graphics for player 1
+ENAM0     equ $1D     ; enable missile 0 (bit 1)
+ENAM1     equ $1E     ; enable missile 1 (bit 1)
+ENABL     equ $1F     ; enable ball (bit 1)
+HMP0      equ $20     ; horizontal motion player 0 (4-bit signed)
+HMP1      equ $21
+HMM0      equ $22
+HMM1      equ $23
+HMBL      equ $24
+VDELP0    equ $25     ; vertical delay player 0 (bit 0)
+VDELP1    equ $26
+VDELBL    equ $27
+RESMP0    equ $28     ; reset missile 0 to player 0 (bit 1)
+RESMP1    equ $29
+HMOVE     equ $2A     ; apply horizontal motion (latched from HMxx)
+HMCLR     equ $2B     ; clear all HMxx
+CXCLR     equ $2C     ; clear collision latches
+
+; ── TIA read registers ($30-$3D) ───────────────────────────────────
+CXM0P     equ $30     ; collisions: M0/P1, M0/P0
+CXM1P     equ $31
+CXP0FB    equ $32
+CXP1FB    equ $33
+CXM0FB    equ $34
+CXM1FB    equ $35
+CXBLPF    equ $36
+CXPPMM    equ $37
+INPT0     equ $38     ; analog input port 0 (paddle dump)
+INPT1     equ $39
+INPT2     equ $3A
+INPT3     equ $3B
+INPT4     equ $3C     ; latched: joystick 0 fire button
+INPT5     equ $3D     ; latched: joystick 1 fire button
+
+; ── RIOT ($280-$297) ───────────────────────────────────────────────
+SWCHA     equ $280    ; joysticks: bits 7-4 = P0 right/left/down/up,
+                      ;            bits 3-0 = P1 right/left/down/up
+SWACNT    equ $281    ; port A data direction (usually $00 = input)
+SWCHB     equ $282    ; console switches (select/reset/colorbw/diffP0/diffP1)
+SWBCNT    equ $283
+INTIM     equ $284    ; timer current value (read-only)
+TIMINT    equ $285    ; timer wraparound flag
+T1024T    equ $296    ; set timer (÷1024 prescale)
+T1T       equ $294    ; set timer (÷1)
+T8T       equ $295    ; set timer (÷8)
+T64T      equ $295    ; set timer (÷64)
+
+; ── Common bit masks ────────────────────────────────────────────────
+VBLANK_ON        equ $02       ; bit 1: dump+latch+blank
+VSYNC_ON         equ $02
+CTRLPF_REFLECT   equ $01
+CTRLPF_SCORE     equ $02
+CTRLPF_PRIORITY  equ $04
+CTRLPF_BALL_2    equ $10       ; bits 4-5 = ball width
+CTRLPF_BALL_4    equ $20
+CTRLPF_BALL_8    equ $30
+NUSIZ_ONE        equ $00       ; one copy, normal width
+NUSIZ_TWO_CLOSE  equ $01
+NUSIZ_TWO_MED    equ $02
+NUSIZ_THREE_CLOSE equ $03
+NUSIZ_TWO_WIDE   equ $04
+NUSIZ_DOUBLE     equ $05       ; one copy, double width
+NUSIZ_THREE_MED  equ $06
+NUSIZ_QUAD       equ $07

package/src/platforms/atari2600/lib/vectors.asm

@@ -0,0 +1,16 @@
+; ── Cart vector table ──────────────────────────────────────────────
+; The 6502 looks here for handler addresses on reset/NMI/IRQ. On the
+; 2600 this lives at $FFFA-$FFFF, the top 6 bytes of the cart bank.
+;
+; For 4 KB carts the bank is mapped at $F000-$FFFF; for banked carts
+; EVERY bank must terminate with these same 6 bytes (only the currently-
+; mapped bank's vectors are visible to the CPU).
+;
+; Include via `include "vectors.asm"` after the rest of your code,
+; pointing at your reset entry point.
+
+  ; Replace START with your reset label.
+  org $FFFA
+  .word START        ; NMI handler (unused on 2600 — points at reset)
+  .word START        ; RESET handler — where the CPU starts
+  .word START        ; IRQ handler (BRK and external IRQs land here)