romdevtools 0.13.0

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -0,0 +1,194 @@
+# Atari 2600 / VCS — mental model
+
+One page. The 2600 is the most architecturally extreme console
+romdev supports. Read this twice before you write code.
+
+## The big idea
+
+**The 2600 has no frame buffer.** There's no VRAM. The TIA chip
+generates video signal one scanline at a time, and you — the
+6502 CPU — must reconfigure the TIA's graphics registers for each
+scanline you want to look different. This is called **"racing the
+beam."**
+
+If you forget to write the TIA for scanline 42, scanline 42 looks
+identical to scanline 41.
+
+## CPU memory map (6507 — a 6502 variant with fewer pins)
+
+```
+$0000-$003F   TIA write registers (graphics, audio, collision)
+$0030-$003D   TIA read registers (collision, input)
+$0080-$00FF   RIOT 128 bytes of RAM — that's ALL the RAM, 128 bytes
+$0280-$0297   RIOT I/O (joysticks, timer, console switches)
+$F000-$FFFF   ROM (4 KB — standard cart size; banks for larger)
+```
+
+**128 bytes of RAM**. Yes. Total. The stack lives here too ($FF
+down). Game state must fit in maybe 80 zero-page bytes.
+
+The 6507 has the same 6502 instruction set but only 13 address
+pins, so it can only address 8 KB. Bigger carts use bank-switching
+hot-spots inside the cart.
+
+## TIA — the graphics object zoo
+
+The TIA has 5 graphics objects and 1 playfield:
+
+```
+P0  player 0       8-pixel-wide bitmap, written to GRP0 ($1B)
+P1  player 1       8-pixel-wide bitmap, written to GRP1 ($1C)
+M0  missile 0      1-8-pixel-wide, shares P0's colour
+M1  missile 1      1-8-pixel-wide, shares P1's colour
+BL  ball           1-8-pixel-wide, shares playfield colour
+PF  playfield      20-pixel-wide pattern, optionally mirrored or
+                   repeated across the 160-pixel-wide screen
+```
+
+Per scanline, you choose which of these are on, what pattern they
+show, what colour they are, and where they're positioned.
+
+## Frame structure (NTSC)
+
+A 2600 NTSC frame is exactly **262 scanlines** in 4 phases:
+
+```
+3 scanlines   VSYNC      tell the TV "new frame coming"
+37 scanlines  VBLANK     game logic runs here — no rendering
+192 scanlines visible    the part the user sees — race the beam
+30 scanlines  overscan   more game logic; off-screen
+```
+
+Each scanline is exactly **76 CPU cycles** wide. You have to fit
+every per-line update into 76 cycles, or you'll be writing the
+TIA after the scanline started rendering — which produces
+mid-line artifacts (sometimes intentionally exploited).
+
+The canonical control flow:
+
+```asm
+MAIN:
+  ; VSYNC
+  LDA #2 ; STA VSYNC ; 3× STA WSYNC ; LDA #0 ; STA VSYNC
+
+  ; VBLANK — game logic
+  LDA #2 ; STA VBLANK
+  LDX #37 ; .vb: STA WSYNC ; DEX ; BNE .vb
+  ; ... move sprites, read input, update state ...
+  LDA #0 ; STA VBLANK
+
+  ; Visible — render scanline-by-scanline
+  LDY #192
+  .draw: STA WSYNC ; <write TIA for this line> ; DEY ; BNE .draw
+
+  ; Overscan
+  LDA #2 ; STA VBLANK
+  LDX #30 ; .os: STA WSYNC ; DEX ; BNE .os
+
+  JMP MAIN
+```
+
+## Positioning objects horizontally
+
+The TIA has NO X register. To set object X, you have to:
+
+1. Hit `WSYNC` (now at start of next scanline)
+2. Burn CPU cycles equal to the desired X position
+3. Write to `RESPx` (reset position 0/1/missile/ball)
+4. `STA HMOVE` later to apply fine adjustment
+
+Common pattern: a busy loop with known cycle count per iteration:
+
+```asm
+  STA WSYNC
+  LDX #15          ; X = X coord / 15 (rough)
+.delay:
+  DEX
+  BNE .delay
+  STA RESP0
+  STA HMOVE
+```
+
+This places P0 at roughly column `X * 15`. Fine X (sub-15 pixels)
+goes through `HMP0/HMP1/HMM0/HMM1/HMBL` followed by `HMOVE`.
+
+## Colour bytes (NTSC palette)
+
+128-entry palette: `HHHHLLLL` where H = hue (0..15) and L =
+luminance (0..15). The same palette as the 7800.
+
+```
+$00  greyscale (black at luma 0, white at luma 15)
+$0E  white
+$48  cyan
+$80  blue
+$C8  green
+$1C  yellow
+$46  orange
+```
+
+## Input
+
+```
+$280  SWCHA  joystick port A (both controllers; high nibble = P1)
+$282  SWCHB  console switches (reset, select, B/W, difficulty)
+$0C   INPT4  P1 fire button (active low, bit 7)
+$0D   INPT5  P2 fire button
+```
+
+Active low — invert after read. For SWCHA, bit 7 = P1 up, bit 6 =
+P1 down, bit 5 = P1 left, bit 4 = P1 right.
+
+### Driving input over MCP
+
+The 2600 joystick has **one** fire button. Over MCP it's pressed with
+`input({op:'set', b: true})` or the spatial `input({op:'set', south: true})` — both clear
+`INPT4` bit 7 (verified live against stella). `input({op:'set', a: true})` is a **no-op**
+(the 2600 pad has no second button — it's not in `input({op:'layout'})`'s
+`physicalButtons`). So drive fire with `b`/`south`, plus the d-pad
+up/down/left/right.
+
+## Audio
+
+Two voices, very simple:
+
+```
+$15  AUDC0   channel 0 wave shape (0..15 — 1=square, 6=pulse, etc.)
+$16  AUDC1   channel 1 wave shape
+$17  AUDF0   channel 0 frequency (0..31 — lower = higher pitch)
+$18  AUDF1   channel 1 frequency
+$19  AUDV0   channel 0 volume (0..15)
+$1A  AUDV1   channel 1 volume
+```
+
+Write once at trigger, the TIA holds the tone until you change it.
+
+## Collision detection
+
+The TIA tracks 15 pairwise collision flags in registers `$30-$37`.
+Each bit corresponds to "object A overlapped object B this frame."
+Read them, then write `CXCLR` ($2C) to clear for the next frame.
+
+E.g. P0 vs M1 collision is bit 6 of CXP0FB ($30).
+
+## Cartridge layout
+
+```
+$F000-$FFF9   game code + data
+$FFFA-$FFFB   NMI vector (unused on 2600)
+$FFFC-$FFFD   RESET vector  ← here's where the CPU starts
+$FFFE-$FFFF   IRQ vector (unused)
+```
+
+For 4 KB carts (the default), the cart is mirrored at `$F000-$FFFF`
+and `$1000-$1FFF`. Most games just `org $F000` and let the mirror
+take care of itself.
+
+## Build pipeline
+
+When you call `build({output:'rom', platform:"atari2600", source: ...})`:
+
+1. dasm assembles the .asm directly to a flat 4 KB binary.
+2. The result is `.a26` — loadable in stella (`loadMedia`).
+
+There's no linker — dasm produces a complete cart in one pass.

package/src/platforms/atari2600/TROUBLESHOOTING.md

@@ -0,0 +1,155 @@
+# Atari 2600 / VCS — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(via `platform({op:'doc', platform:"atari2600", name:"mental_model"})`).
+
+## "Screen rolls / shimmers / wrong height"
+
+You wrote the wrong number of scanlines. NTSC is **EXACTLY** 262
+scanlines per frame, broken into 3 VSYNC + 37 VBLANK + 192 visible
++ 30 overscan. Any of those off by 1, and the TV's vertical sync
+drifts.
+
+Check:
+- Did your VSYNC block call `STA WSYNC` exactly 3 times?
+- Is your VBLANK loop `LDX #37` then `STA WSYNC ; DEX ; BNE .vb`?
+  (37 iterations of WSYNC = 37 scanlines.)
+- Same for the visible 192 and overscan 30.
+- Are there any extra `STA WSYNC` instructions hiding in your
+  game-logic code that pushes you past 262?
+
+Use the cycle counter from `stella -trace` (or our `frame({op:'step'})` +
+`cpu({op:'read'})`) to verify your scanline count.
+
+## "Sprites are wider than expected"
+
+Two scanlines = one TIA pixel of vertical resolution at minimum,
+but the GRP0/GRP1 register stays valid until you change it. If you
+write GRP0 once and don't reset to 0 on the next line, the sprite
+"smears down" — extending to the bottom of the screen.
+
+The fix: explicitly write `STA GRP0` with 0 on every line where
+the player isn't drawn. Or write it ONCE for the scanlines you
+want, and zero AFTER:
+
+```asm
+  STA WSYNC
+  ; ... compute Y - P_Y ...
+  CMP #8           ; within sprite height?
+  BCS .blank
+  TAY
+  LDA SPRITE,Y
+  STA GRP0
+  JMP .next
+.blank:
+  LDA #0
+  STA GRP0
+.next:
+```
+
+## "Object X position is off / jittery"
+
+The X-position routine has cycle-count gotchas:
+
+1. **`STA RESP0` itself takes 3 cycles** — the actual reset happens
+   at cycle 3 of the instruction, not cycle 0. Fine X via HMP0 +
+   HMOVE compensates.
+2. **HMOVE itself takes 8 cycles to execute** and triggers a
+   "missing horizontal blank" — if HMOVE runs after pixel 56 of
+   the current scanline, the right-hand side of the next scanline
+   has 8 black pixels.
+3. **Your delay loop has variable cycle count** depending on
+   whether the branch crosses a page boundary.
+
+Use a known-good X-position routine like the one in
+`src/platforms/atari2600/lib/`. Don't roll your own unless you
+need pixel-perfect placement.
+
+## "Joystick reads as 'always pressed'"
+
+`SWCHA` is **active low**. Bit value `0` = pressed, `1` =
+released. You must INVERT before AND-masking:
+
+```asm
+LDA SWCHA
+EOR #$FF       ; or: ASL into carry, BCS = not pressed
+AND #$80       ; P1 up
+BEQ .not_up
+; ... move up ...
+```
+
+The `default.asm` template uses `ASL` + `BCS` which checks the
+high bit directly without explicit inversion — also valid, just
+different idiom.
+
+## "ROM works in stella but wrong on real hardware"
+
+Real 2600s are picky. Common gotchas:
+
+1. **Vector table not at $FFFC.** RESET must point to your code's
+   entry. `org $FFFA ; .word START ; .word START ; .word START`
+   is the canonical setup.
+2. **WSYNC timing assumes 76 cycles per scanline.** If you have
+   a code path that runs > 76 cycles between WSYNCs, that
+   scanline overflows and the next line is short. Real hardware
+   doesn't forgive this; stella sometimes does.
+3. **Page-crossing branches.** A taken branch that crosses a
+   page boundary takes 4 cycles instead of 3. Drift = scanline
+   misalignment.
+
+## "Music plays the wrong notes"
+
+AUDF0/AUDF1 frequency values are NOT Hz. They're divisor values
+where:
+
+```
+freq_hz = 30030 / (audf + 1)
+```
+
+(approx, for AUDC tone shape 4 — pure tone.)
+
+So `AUDF0 = 7` → ~3.75 kHz. Higher AUDF = lower pitch. Most
+tutorials list a lookup table; the bundled `lib/` directory has
+one.
+
+## "Game logic doesn't fit in VBLANK"
+
+37 scanlines × 76 cycles = ~2800 cycles for ALL game logic per
+frame. If you need more, you can:
+
+- Spread logic across vblank + overscan (37 + 30 = 67 lines = 5092
+  cycles).
+- Skip-frame logic that only runs every N frames.
+- Move expensive computation into the kernel's "idle" lines (the
+  ones where no rendering happens because sprites are off-screen).
+
+## "Building a sprite kernel for vertical movement is hard"
+
+It is. The 2600 has no scrolling, no tilemap, no Y register on
+the TIA. To move a sprite down, you must change which scanline
+GRP0 starts being non-zero on. The hello-style approach is:
+
+```asm
+LDY #192
+.draw:
+  STA WSYNC
+  TYA
+  SEC
+  SBC P_Y          ; how many lines past the player's top?
+  CMP #8           ; within sprite height?
+  BCS .blank
+  TAY
+  LDA SPRITE,Y     ; row Y of the sprite shape
+  STA GRP0
+  ...
+```
+
+This costs ~15 cycles per scanline (~20% of the 76-cycle budget).
+For multiple sprites at different Y, the cost multiplies. Real
+games use careful kernel layouts ("the 2600 way") to limit
+sprites to specific Y bands. See the `lib/player_kernel.asm`
+snippet for one approach.
+
+## "First build is slow but later ones are fast"
+
+Expected. dasm cold-load is ~500ms. Steady-state builds < 100ms.

package/src/platforms/atari2600/UPSTREAM_SOURCES.md

@@ -0,0 +1,49 @@
+# Atari 2600 — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/atari2600/templates/*.asm`).
+2. **Bundled runtime** — `src/platforms/atari2600/lib/*.asm`
+   (kernel_skeleton, player_kernel, playfield_kernel,
+   read_joystick, vectors).
+3. **Bundled cc65 atari2600 libsrc** (R58) at `src/platforms/
+   atari2600/lib/cc65-src/`. (Note: cc65 doesn't generate practical
+   2600 code; we use **dasm** for 2600. The cc65 libsrc here is the
+   small bit cc65 ships for 2600 — mostly reference, since real
+   2600 dev is asm.)
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | dasm | https://dasm-assembler.github.io/ |
+   | stella2014 libretro core | https://github.com/libretro/stella2014-libretro |
+   | stella proper | https://stella-emu.github.io/ |
+
+## 2600 hardware docs
+
+- **Stella Programmer's Guide** (the canonical, by Steve Wright):
+  https://atariage.com/2600/programming/Stella_Programmers_Guide.pdf
+- **AtariAge 2600 programming**: https://atariage.com/forums/forum/50-atari-2600-programming/
+- **TIA reference**: https://www.qotile.net/files/2600_advanced_prog_guide.txt
+- **Atari Compendium**: http://www.cs.cmu.edu/~chuck/infopg/atari/c25.html
+
+## The race-the-beam model
+
+The 2600 has NO framebuffer. Every scanline is composed in real time
+by writing TIA registers as the beam scans. The CPU has ~76 cycles
+per scanline (~3 µs total) to (a) decide what's drawn on that line,
+(b) write the right TIA registers BEFORE the beam reaches each
+pixel column. Miss a cycle window → graphics glitch.
+
+The bundled `kernel_skeleton.asm` is the canonical "NTSC 3 vsync +
+37 vblank + 192 visible + 30 overscan" frame structure. Read it
+before writing anything.
+
+## When to use what
+
+- "How do I draw two sprites at different Y positions?" → Stella
+  Programmer's Guide § "Players" + `player_kernel.asm`
+- "TIA register layout" → `lib/vcs_constants.h` + Stella PG appendix
+- "Why does my joystick read drift?" → `read_joystick.asm` +
+  `SWCHA`/`SWCHB` docs in Stella PG
+- "dasm syntax" → dasm-assembler.github.io

package/src/platforms/atari2600/lib/README.md

@@ -0,0 +1,67 @@
+Atari 2600 starter snippets
+===========================
+
+Hand-vetted boilerplate for the dasm assembler (the standard 2600 toolchain).
+All snippets target the `processor 6502` directive and assume the cart is
+4 KB anchored at `$F000` (the most common arrangement; the 2600's "cart"
+mapping puts the file's last 4 KB at $F000-$FFFF and mirrors $1000-$1FFF
+on the address bus).
+
+For larger banked carts (8K F8, 16K F6, 32K F4) the same code can live in
+each bank, but each bank must end with the same vector table at $FFFA-$FFFF
+since only the currently-banked-in region's vectors are visible.
+
+COPY-PASTE templates, not linkable modules
+-------------------------------------------
+
+dasm builds a single flat 4 KB ROM. These snippets are meant to be
+**inlined** into your own source — copy the routines/tables you want
+into your `main.asm`. They do NOT carry `org` directives (except
+`kernel_skeleton.asm`, which IS the top-level ROM layout and owns
+`org $F000` + `org $FFFA`). If you `include` two snippets that each
+had their own `org`, dasm errors with "Origin Reverse-indexed"
+because their fixed addresses overlap your main code. So: treat
+each snippet's labelled routines + data tables as code you paste
+into place, not files you link together.
+
+Files
+-----
+
+- **vcs_constants.h** — TIA + RIOT register names + bit masks. `include` at top.
+- **kernel_skeleton.asm** — vsync + vblank + 192 visible scanline + overscan
+  template. THIS is your ROM's spine: it owns `org $F000` + `org $FFFA`.
+  Drop new logic into the `; --- per-frame logic here ---` slot.
+- **player_kernel.asm** — single-player ("p0") rendered against a solid
+  background. Shows the minimal GRP0 / WSYNC pattern + a real
+  `POS_OBJ_P0` horizontal-positioning macro (SBC-15 technique).
+- **playfield_kernel.asm** — asymmetric playfield drawn from a per-line
+  byte table — the foundation for level/map-style displays.
+- **score_kernel.asm** — 1-2 digit score band via PF1 in SCORE mode
+  (tens digit on the left half in P0 color, ones on the right in P1
+  color). Ships digit shapes 0-9 + SCORE_PREP (pointer build) +
+  SCORE_KERNEL_BAND (single-PF1-write composite render).
+- **read_joystick.asm** — read joystick 0 from SWCHA (RIOT $280) into a
+  zp byte. Top-of-file comment documents the "re-load A between bit
+  checks" pattern (the classic "left works, right doesn't" bug).
+- **vectors.asm** — the 6-byte tail at $FFFA. Reset goes to your `START`
+  label; NMI/IRQ are usually unused on the 2600 (BRK can fire IRQ).
+
+Toolchain
+---------
+
+Build via `build({output:'rom', platform: "atari2600", source: "..."})`. Server
+spawns `dasm` (bundled WASM) and emits a `.bin` ready for `loadRomFromPath`.
+
+Foot-guns
+---------
+
+1. **TIA register names overlap with RIOT.** `$00-$2C` is TIA; `$280-$297`
+   is RIOT (port I/O + timer). Don't write `$80` and expect SWCHA — use
+   the long form `STA SWCHA` (or `STA $280`).
+2. **WSYNC is a write-only signal**, not a delay loop. `STA WSYNC` blocks
+   the CPU until the next horizontal blank — exactly one scanline.
+3. **No frame buffer.** The TIA renders the screen line-by-line by reading
+   register state as the beam moves. Set a register late in a scanline →
+   it affects that line, not the next. This is "racing the beam."
+4. **Vectors mirror inside the bank.** $FFFC == $1FFC == $3FFC etc. Always
+   reference the absolute address.

package/src/platforms/atari2600/lib/cc65-src/crt0.s

@@ -0,0 +1,49 @@
+; Atari VCS 2600 startup code for cc65
+;
+; Florent Flament (contact@florentflament.com), 2017
+
+        .export         _exit
+        .export         __STARTUP__ : absolute = 1
+
+        .import         __RAM_START__, __RAM_SIZE__
+        .import         copydata
+        .import         _main
+
+        .include        "zeropage.inc"
+
+
+.segment "STARTUP"
+start:
+; Clear decimal mode
+        cld
+
+; Initialization Loop:
+; * Clears Atari 2600 whole memory (128 bytes) including BSS segment
+; * Clears TIA registers
+; * Sets system stack pointer to $ff (i.e top of zero-page)
+        ldx     #0
+        txa
+clearLoop:
+        dex
+        txs
+        pha
+        bne     clearLoop
+
+; Initialize data
+        jsr     copydata
+
+; Initialize C stack pointer
+        lda     #<(__RAM_START__ + __RAM_SIZE__)
+        ldx     #>(__RAM_START__ + __RAM_SIZE__)
+        sta     c_sp
+        stx     c_sp+1
+
+; Call main
+        jsr     _main
+_exit:  jmp     _exit
+
+
+.segment "VECTORS"
+.word   start                   ; NMI
+.word   start                   ; Reset
+.word   start                   ; IRQ

package/src/platforms/atari2600/lib/cc65-src/ctype.s

@@ -0,0 +1,5 @@
+; Character specification table.
+;
+; uses the "common" definition
+
+        .include "ctype_common.inc"

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