romdevtools 0.15.0 → 0.21.0

package/examples/atari2600/templates/sports.asm

@@ -0,0 +1,362 @@
+; ── sports.asm — Atari 2600 SPORTS genre scaffold (Pong) ──────────────
+;
+; Pong IS the 2600's sport — the console shipped with Combat and Video
+; Olympics; the paddle-and-ball game is the genre's archetype and a
+; flawless fit for the TIA's two players + ball. Identical in spirit to
+; the verified `paddle` template.
+;
+; Two paddles (player 0 = left, player 1 = right), one ball (BL),
+; symmetric playfield with top + bottom walls. Joystick port A up/down
+; moves the left paddle; the right paddle does simple AI (chases ball Y).
+;
+; 2600 architecture refresher:
+;   - No frame buffer. Every scanline you write TIA registers describing
+;     what THAT line looks like, then STA WSYNC to advance.
+;   - 5 graphics objects: P0, P1, M0, M1, BL (+ PF tiles via PF0/1/2).
+;   - "Race the beam": the CPU has ~76 cycles between WSYNCs.
+;
+; This scaffold uses:
+;   P0  → left paddle  (8-pixel-tall vertical bar)
+;   P1  → right paddle (8-pixel-tall vertical bar)
+;   BL  → 2-pixel-wide ball
+;   PF0 → top + bottom playfield walls (drawn for the top + bottom rows)
+
+  processor 6502
+  org $F000
+
+VSYNC    = $00
+VBLANK   = $01
+WSYNC    = $02
+COLUP0   = $06
+COLUP1   = $07
+COLUPF   = $08
+COLUBK   = $09
+PF0      = $0D
+PF1      = $0E
+PF2      = $0F
+RESP0    = $10
+RESP1    = $11
+RESBL    = $14
+GRP0     = $1B
+GRP1     = $1C
+ENABL    = $1F
+HMP0     = $20
+HMP1     = $21
+HMBL     = $24
+HMOVE    = $2A
+CTRLPF   = $0A
+SWCHA    = $280
+; ── TIA audio (R41) ────────────────────────────────────────────────
+AUDC0    = $15
+AUDF0    = $17
+AUDV0    = $19
+
+; ── Zero-page state ──────────────────────────────────────────────────
+P0_Y     = $80        ; left paddle top scanline (16..168)
+P1_Y     = $81        ; right paddle top scanline
+BALL_X   = $82        ; ball horizontal (TIA pixel 0..159)
+BALL_Y   = $83        ; ball vertical (scanline)
+BALL_DX  = $84        ; +1 or -1
+BALL_DY  = $85        ; +1 or -1
+FRAME    = $86
+SFX_LEFT = $87        ; frames remaining on active sfx (0 = silent)
+
+START:
+  SEI
+  CLD
+  LDX #$FF
+  TXS
+  LDA #0
+.clr:
+  STA $00,X
+  DEX
+  BNE .clr
+
+  LDA #88
+  STA P0_Y
+  STA P1_Y
+  LDA #80
+  STA BALL_X
+  LDA #90
+  STA BALL_Y
+  LDA #1
+  STA BALL_DX
+  STA BALL_DY
+
+  ; Boot chime — confirms TIA audio is wired.
+  LDA #$04
+  STA AUDC0
+  LDA #$0C
+  STA AUDF0
+  LDA #$0F
+  STA AUDV0
+  LDA #20
+  STA SFX_LEFT
+
+  LDA #$80           ; blue background
+  STA COLUBK
+  LDA #$0F           ; white paddles
+  STA COLUP0
+  STA COLUP1
+  LDA #$48           ; cyan playfield
+  STA COLUPF
+  LDA #$05           ; PF symmetric reflect + ball priority
+  STA CTRLPF
+
+MAIN:
+  INC FRAME
+
+  ; ── VSYNC ─────────────────────────────────────────────────────────
+  LDA #2
+  STA VSYNC
+  STA WSYNC
+  STA WSYNC
+  STA WSYNC
+  LDA #0
+  STA VSYNC
+
+  ; ── VBLANK (37 lines) — game logic ────────────────────────────────
+  ; 34 here + the 3 STA WSYNC in the P0/P1 positioning block below = 37 VBLANK
+  ; lines total. (Bug fix: this loop used to be 37 AND the positioning added 3
+  ; more → 265 scanlines/frame → the TV/emulator can't lock vsync → rolling /
+  ; black picture. Exactly 262 lines = 3 VSYNC + 37 VBLANK + 192 visible + 30
+  ; overscan; the positioning WSYNCs MUST be counted against the 37.)
+  LDA #2
+  STA VBLANK
+  LDX #34
+.vb:
+  STA WSYNC
+  DEX
+  BNE .vb
+
+  ; Move left paddle from joystick (every 2 frames to throttle).
+  LDA FRAME
+  AND #$01
+  BNE .skip_pad
+  LDA SWCHA
+  ASL                 ; right (unused)
+  ASL                 ; left (unused)
+  ASL                 ; down
+  BCS .nd
+  INC P0_Y
+.nd:
+  ASL                 ; up
+  BCS .nu
+  DEC P0_Y
+.nu:
+  ; Clamp paddle within bounds
+  LDA P0_Y
+  CMP #16
+  BCS .nopaddmin
+  LDA #16
+  STA P0_Y
+.nopaddmin:
+  CMP #168
+  BCC .nopaddmax
+  LDA #168
+  STA P0_Y
+.nopaddmax:
+.skip_pad:
+
+  ; Right-paddle AI — chase the ball's Y
+  LDA BALL_Y
+  CMP P1_Y
+  BCC .ai_up
+  INC P1_Y
+  JMP .ai_done
+.ai_up:
+  DEC P1_Y
+.ai_done:
+
+  ; Move ball
+  LDA BALL_DX
+  CLC
+  ADC BALL_X
+  STA BALL_X
+  LDA BALL_DY
+  CLC
+  ADC BALL_Y
+  STA BALL_Y
+
+  ; Bounce off top/bottom — short blip on each bounce.
+  LDA BALL_Y
+  CMP #20
+  BCS .nb_top
+  LDA #1
+  STA BALL_DY
+  JSR sfx_wall
+.nb_top:
+  LDA BALL_Y
+  CMP #180
+  BCC .nb_bot
+  LDA #$FF              ; -1
+  STA BALL_DY
+  JSR sfx_wall
+.nb_bot:
+  ; Bounce off left/right (and respawn near centre on miss) — pew on miss.
+  LDA BALL_X
+  CMP #4
+  BCS .nb_l
+  LDA #1
+  STA BALL_DX
+  LDA #80
+  STA BALL_X
+  JSR sfx_score
+.nb_l:
+  LDA BALL_X
+  CMP #156
+  BCC .nb_r
+  LDA #$FF
+  STA BALL_DX
+  LDA #80
+  STA BALL_X
+  JSR sfx_score
+.nb_r:
+
+  ; sfx_update: tick the countdown, silence on zero.
+  LDA SFX_LEFT
+  BEQ .sfx_done
+  DEC SFX_LEFT
+  BNE .sfx_done
+  LDA #0
+  STA AUDV0
+.sfx_done:
+
+  ; ── Position P0 / P1 / HMOVE — exactly 3 WSYNC-bounded lines ───────
+  ; CRITICAL: every RESPx write AND the STA HMOVE must complete inside
+  ; the 76-cycle scanline that began with its STA WSYNC. A DEX/BNE delay
+  ; loop costs 5 cycles/iteration, so the loop count must be small enough
+  ; that RESPx still lands before the line ends. The old code used
+  ; LDX #38 (~189 cycles = 2.5 scanlines!) with no WSYNC before RESP1/
+  ; HMOVE, so it emitted ~2-3 UNCOUNTED scanlines past the 262 budget →
+  ; ~265 lines/frame → vsync never locks (rolling magenta band). HMOVE
+  ; was also issued mid-line; it must follow a fresh WSYNC.
+
+  ; Line 1 of 3: coarse-position P0 (left, ~column 16)
+  STA WSYNC
+  LDX #5
+.p0d:
+  DEX
+  BNE .p0d           ; ~24 cycles in → P0 lands near the left edge
+  STA RESP0
+  ; Line 2 of 3: coarse-position P1 (right, ~column 132)
+  STA WSYNC
+  LDX #13
+.p1d:
+  DEX
+  BNE .p1d           ; ~64 cycles in (< 76) → P1 lands near the right
+  STA RESP1
+  ; Line 3 of 3: apply HMOVE on a FRESH line, right after WSYNC
+  STA WSYNC
+  STA HMOVE
+
+  LDA #0
+  STA VBLANK
+
+  ; ── Visible (192 lines) — TWO-LINE KERNEL ─────────────────────────
+  ; CRITICAL: a single scanline is only 76 CPU cycles. The full per-line
+  ; render here (playfield walls + P0 + P1 + ball, each a SEC/SBC/CMP +
+  ; conditional store) is ~88 cycles — it does NOT fit in one line. In a
+  ; 1-line kernel each WSYNC iteration then spills past the line boundary,
+  ; so 192 iterations stretch to ~232 emitted lines → ~250-line frame →
+  ; vsync never locks (rolling magenta band — THE bug).
+  ;
+  ; The fix is the standard 2600 "2-line kernel": each loop pass renders
+  ; TWO scanlines and splits the work across two WSYNCs, doubling the
+  ; budget to ~152 cycles. 96 passes × 2 lines = 192 visible lines.
+  ; Y counts 192→2 in steps of 2; paddles/ball move in 2px steps (fine
+  ; for Pong). The branchless "LDA #off / CMP / BCS skip / LDA #on" form
+  ; also drops the JMPs the old code paid every line.
+  LDY #192
+.draw:
+  ; ---- first line of the pair: playfield walls + left paddle ----
+  STA WSYNC
+  ; Top + bottom walls: full-width PF on the outer rows (Y>=189 / Y<5)
+  LDA #0
+  CPY #189
+  BCS .wall
+  CPY #5
+  BCS .nowall
+.wall:
+  LDA #$FF
+.nowall:
+  STA PF0
+  STA PF1
+  STA PF2
+  ; Left paddle: 8 lines starting at P0_Y
+  TYA
+  SEC
+  SBC P0_Y
+  CMP #8
+  LDA #0
+  BCS .p0off
+  LDA #$FF
+.p0off:
+  STA GRP0
+  ; ---- second line of the pair: right paddle + ball ----
+  STA WSYNC
+  ; Right paddle: 8 lines starting at P1_Y
+  TYA
+  SEC
+  SBC P1_Y
+  CMP #8
+  LDA #0
+  BCS .p1off
+  LDA #$FF
+.p1off:
+  STA GRP1
+  ; Ball: 2 lines starting at BALL_Y
+  TYA
+  SEC
+  SBC BALL_Y
+  CMP #2
+  LDA #0
+  BCS .bloff
+  LDA #2
+.bloff:
+  STA ENABL
+  DEY
+  DEY
+  BNE .draw
+
+  ; ── Overscan (30 lines) ───────────────────────────────────────────
+  LDA #2
+  STA VBLANK
+  LDX #30
+.os:
+  STA WSYNC
+  DEX
+  BNE .os
+
+  JMP MAIN
+
+  ; ── TIA sfx helpers (R41) ─────────────────────────────────────────
+  ; sfx_wall — short blip on wall bounce (4-frame ringing tone)
+sfx_wall:
+  LDA #$04
+  STA AUDC0
+  LDA #$10
+  STA AUDF0
+  LDA #$0F
+  STA AUDV0
+  LDA #4
+  STA SFX_LEFT
+  RTS
+
+  ; sfx_score — longer chime when a player scores (16 frames)
+sfx_score:
+  LDA #$04
+  STA AUDC0
+  LDA #$06            ; higher pitch
+  STA AUDF0
+  LDA #$0F
+  STA AUDV0
+  LDA #16
+  STA SFX_LEFT
+  RTS
+
+  ; ── Vector table ──────────────────────────────────────────────────
+  org $FFFA
+  .word START
+  .word START
+  .word START

package/examples/atari7800/templates/default.c

@@ -43,6 +43,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -91,6 +93,43 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
  * at dp+1; if it's 0, the parse loop exits immediately. */
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background playfield ─────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the one
+ * sprite above and ~99% of the screen stays the flat BACKGRND colour
+ * (reads as "blank"). These full-width bands fill every non-sprite
+ * zone with scenery so the frame has real content.
+ *
+ * One scanline of solid pixels lives in ROM (band_pix). A single DL
+ * drawable is at most 32 bytes = 128 px wide, so a full 160-px line
+ * needs TWO drawables. Width encoding (byte[3] low 5 bits) = 32-bytes;
+ * high 3 bits = palette: field uses palette 1, ground uses palette 2.
+ */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_field, 1);
+MK_BAND(dl_ground, 2);
+#define GROUND_ZONE 188
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
+/* Background DL for a non-sprite zone: sky (empty) up top, field in the
+ * middle, ground at the bottom. */
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= GROUND_ZONE) return (uint16_t)(uintptr_t)dl_ground;
+  if (zone >= 28)          return (uint16_t)(uintptr_t)dl_field;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 /* DLL: one entry per visible scanline + the 10-line top overscan
  * MARIA walks BEFORE the visible area begins. NTSC display area =
  * scanlines 16..258 = 243 lines.
@@ -130,9 +169,12 @@ static void vblank_wait(void) {
 
 void main(void) {
   uint16_t dll_addr;
-  uint16_t empty_dl = (uint16_t)(uintptr_t)dl_empty;
   int i;
 
+  /* Point the background bands at their shared ROM pixel row. */
+  set_band_addr(dl_field);
+  set_band_addr(dl_ground);
+
   /* Patch each row's DL to point at its sprite-data row. */
   set_dl_addr(dl_row0, sprite_row0);
   set_dl_addr(dl_row1, sprite_row1);
@@ -143,9 +185,9 @@ void main(void) {
   set_dl_addr(dl_row6, sprite_row6);
   set_dl_addr(dl_row7, sprite_row7);
 
-  /* Build the DLL: empty zones everywhere except the 8 sprite rows. */
+  /* Build the DLL: background scenery everywhere except the 8 sprite rows. */
   for (i = 0; i < DLL_ZONES; i++) {
-    uint16_t dl_ptr = empty_dl;
+    uint16_t dl_ptr = bg_zone_dl(i);
     if      (i == SPRITE_Y + 0) dl_ptr = (uint16_t)(uintptr_t)dl_row0;
     else if (i == SPRITE_Y + 1) dl_ptr = (uint16_t)(uintptr_t)dl_row1;
     else if (i == SPRITE_Y + 2) dl_ptr = (uint16_t)(uintptr_t)dl_row2;
@@ -158,10 +200,12 @@ void main(void) {
   }
 
   /* Palette + background. Atari NTSC palette: HHHL nibble form. */
-  BACKGRND = 0x88;   /* light blue */
-  P0C1     = 0x46;   /* orange-red */
+  BACKGRND = 0x88;   /* light blue sky */
+  P0C1     = 0x46;   /* orange-red (sprite) */
   P0C2     = 0x0F;   /* white */
   P0C3     = 0x36;   /* pink */
+  P1C1     = 0xC8;   /* field green (background band) */
+  P2C1     = 0x14;   /* ground brown (background band) */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/atari7800/templates/platformer.c

@@ -14,6 +14,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -44,6 +46,40 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background playfield ─────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the
+ * player and ~99% of the screen stays the flat BACKGRND colour
+ * (reads as "blank"). These full-width bands give the level a sky,
+ * a field, and a solid ground strip the player stands on.
+ *
+ * A single DL drawable is at most 32 bytes = 128 px wide, so a full
+ * 160-px line needs TWO drawables. Width = byte[3] low 5 bits (32-n);
+ * high 3 bits = palette. */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_field, 1);
+MK_BAND(dl_ground, 2);
+/* Ground strip starts just below where the player rests (GROUND_Y). */
+#define GROUND_ZONE 200
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= GROUND_ZONE) return (uint16_t)(uintptr_t)dl_ground;
+  if (zone >= 28)          return (uint16_t)(uintptr_t)dl_field;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -60,7 +96,6 @@ static void set_dll_entry(int idx, uint16_t dl_ptr) {
 }
 
 static void build_dll(uint8_t y) {
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
@@ -74,7 +109,7 @@ static void build_dll(uint8_t y) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;
     }
     set_dll_entry(i, dl);
   }
@@ -112,13 +147,17 @@ void main(void) {
   set_dl_addr(dl_row5, player_row5);
   set_dl_addr(dl_row6, player_row6);
   set_dl_addr(dl_row7, player_row7);
+  set_band_addr(dl_field);
+  set_band_addr(dl_ground);
   set_x((uint8_t)px);
   build_dll((uint8_t)(py16 >> 4));
 
-  BACKGRND = 0x84;
-  P0C1     = 0x46;
+  BACKGRND = 0x84;   /* sky */
+  P0C1     = 0x46;   /* player */
   P0C2     = 0x0F;
   P0C3     = 0x36;
+  P1C1     = 0x96;   /* distant field (teal) */
+  P2C1     = 0x24;   /* ground (brown) */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/atari7800/templates/puzzle.c

@@ -20,6 +20,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -53,6 +55,37 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background well ──────────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the
+ * falling block and ~99% of the screen stays the flat BACKGRND colour
+ * (reads as "blank"). Each well zone draws three full-width segments:
+ * a side wall (palette 2), the playfield well in the centre where the
+ * piece falls (palette 1), the other wall (palette 2). Width =
+ * byte[3] low 5 bits (32-n); high 3 bits = palette. */
+static const uint8_t band_pix[16] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+/* 12 bytes (48 px) wall @ x0, 16 bytes (64 px) well @ x48,
+ * 12 bytes (48 px) wall @ x112, terminator. */
+static uint8_t dl_well[16] = {
+  0, 0x40, 0, (2 << 5) | 20, 0,
+  0, 0x40, 0, (1 << 5) | 16, 48,
+  0, 0x40, 0, (2 << 5) | 20, 112,
+  0
+};
+
+static void set_well_addr(void) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl_well[0] = dl_well[5] = dl_well[10] = (uint8_t)(a & 0xFF);
+  dl_well[2] = dl_well[7] = dl_well[12] = (uint8_t)(a >> 8);
+}
+
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= 32 && zone < 200) return (uint16_t)(uintptr_t)dl_well;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -80,7 +113,6 @@ static void set_x(uint8_t x) {
 }
 
 static void build_dll(int y) {
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
@@ -94,7 +126,7 @@ static void build_dll(int y) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;
     }
     set_dll_entry(i, dl);
   }
@@ -120,13 +152,16 @@ void main(void) {
   piece_x_col = COLS / 2;
   piece_y = TOP_Y;
   color_cycle = 0;
+  set_well_addr();
   set_x((uint8_t)(60 + piece_x_col * CELL_W_PIX));
   build_dll(piece_y);
 
-  BACKGRND = 0x00;
-  P0C1 = 0x46;   /* red */
+  BACKGRND = 0x00;   /* black surround */
+  P0C1 = 0x46;   /* falling piece (red) */
   P0C2 = 0x46;
   P0C3 = 0x46;
+  P1C1 = 0x02;   /* well interior (dark blue-grey) */
+  P2C1 = 0x08;   /* well walls (steel) */
   CHARBASE = 0;
   OFFSET = 0;
 

package/examples/atari7800/templates/racing.c

@@ -17,6 +17,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -44,6 +46,37 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background road ──────────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the car
+ * and ~99% of the screen stays the flat BACKGRND colour (reads as
+ * "blank"). Each road zone draws three full-width segments: grass on
+ * the left (palette 1), the grey road down the centre (palette 2),
+ * grass on the right (palette 1). Width = byte[3] low 5 bits (32-n);
+ * high 3 bits = palette. */
+static const uint8_t band_pix[16] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+/* 8 bytes (32 px) grass @ x0, 16 bytes (64 px) road @ x32,
+ * 8 bytes (32 px) grass @ x96, terminator. */
+static uint8_t dl_road[16] = {
+  0, 0x40, 0, (1 << 5) | 24, 0,
+  0, 0x40, 0, (2 << 5) | 16, 32,
+  0, 0x40, 0, (1 << 5) | 24, 96,
+  0
+};
+
+static void set_road_addr(void) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl_road[0]  = dl_road[5]  = dl_road[10] = (uint8_t)(a & 0xFF);
+  dl_road[2]  = dl_road[7]  = dl_road[12] = (uint8_t)(a >> 8);
+}
+
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= 16 && zone < 220) return (uint16_t)(uintptr_t)dl_road;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -71,7 +104,6 @@ static void set_x(uint8_t x) {
 }
 
 static void build_dll(void) {
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
@@ -85,7 +117,7 @@ static void build_dll(void) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;
     }
     set_dll_entry(i, dl);
   }
@@ -110,13 +142,16 @@ void main(void) {
   set_dl_addr(dl_row7, car_row7);
 
   lane = 1;
+  set_road_addr();
   set_x(lane_xs[lane]);
   build_dll();
 
-  BACKGRND = 0x88;
-  P0C1     = 0x46;
+  BACKGRND = 0x88;   /* sky/horizon */
+  P0C1     = 0x46;   /* car */
   P0C2     = 0x0F;
   P0C3     = 0x36;
+  P1C1     = 0xC8;   /* roadside grass (green) */
+  P2C1     = 0x06;   /* road surface (grey) */
   CHARBASE = 0;
   OFFSET   = 0;