# Project context for Nyuller subagent

You are implementing one phase of a C64 game called "Nyuller."
(quick-draw duel between a rabbit and a kid on a scooter, first to 5
wins). You will be given a specific phase task. This document is the
context you need to do the work.

## Project layout (read-only)

```
/home/ballz/work/teletype/nyuller/
├── oscar64/                # Oscar64 C cross-compiler (git submodule)
│   ├── bin/oscar64         # The compiler binary (built by make)
│   └── include/            # Runtime headers (c64/, c128/, gfx/, stdio.h, etc.)
├── docs/c64/               # Downloaded C64 reference material
│   ├── vic/                # VIC-II register map, graphics modes, cebix article
│   ├── cia/                # CIA 1 + CIA 2 register maps
│   ├── sid/                # SID register map, ADSR, filter
│   ├── kernal/             # KERNAL jump table, full PRG text
│   ├── memory/             # Memory map, zeropage, hardware internals
│   ├── interrupts/         # Raster IRQ, IRQ/NMI flow, joystick
│   ├── sprites/            # Sprite (MOB) programming
│   └── cpu/                # 6510 overview
├── OSCAR64.md              # How the Oscar64 compiler works + C64 best practices
├── PROG_C64.md             # C64 hardware reference (synthesized)
├── GAME.md                 # The game design spec
├── tasks.md                # The phased implementation plan (your roadmap)
├── source_images/          # The 5 source PNGs for the game screens
└── src/                    # YOUR CODE GOES HERE
    ├── helloworld.c        # Existing minimal working program
    ├── build.sh            # Legacy build script (replaced by Makefile)
    └── build/              # Output directory (gitignored)
```

## Build and test (this is the ONLY way to verify your work)

```sh
cd /home/ballz/work/teletype/nyuller
make                     # show help with all targets
make compile             # compile → build/nyuller.prg
make run                 # compile + run in oscar64 emulator (HEADLESS, fast)
make play                # compile + launch VICE in background
make kill                # kill any detached VICE
```

**The oscar64 built-in emulator (`make run`) is the only test tool.** VICE
does not work in this headless environment (no display, blank
screenshots, manual ROM fetching). Do not waste time on VICE.
The `run` target runs the same `.prg` file the C64 will run, with no
setup, no ROMs, and at high speed.

`make` will auto-build the oscar64 compiler if it's missing.
It runs `cd src && oscar64 -i=…/include -o=…/build/nyuller.prg main.c`
to compile, and `cd src && oscar64 -i=…/include -o=…/build/nyuller.prg -e main.c` to run.

The build artifacts in `build/` are: `helloworld.prg` (the C64 program),
`helloworld.asm` (6502 listing), `helloworld.map` (region/section/object
placement), `helloworld.lbl` (VICE monitor labels — still useful even
though we don't use VICE), `helloworld.int` (intermediate code).

## CRITICAL: the 4-color-per-4×8-cell multicolor constraint

The 5 source PNGs have well more than 2 colors per 8×8 cell. They
**must** be displayed using **multicolor bitmap mode** (VIC-II
`$D011` BMM=1, `$D016` MCM=1): 160×200 with 2 bits per pixel, 4 colors
per 4×8 cell, same 8000-byte bitmap size. Per-cell only 4 colors are
available; the asset pipeline must quantize each 4×8 cell independently
to 4 colors from the 16-color C64 palette (black, white, red, cyan,
purple, green, blue, yellow, orange, brown, light red, dark grey,
medium grey, light green, light blue, light grey).

The bitmap goes to 8 KB at $E000-$FFFF (or wherever the linker
places it after `mmap_set(MMAP_RAM)` + `mmap_set(MMAP_NO_ROM)`).
The 1000-byte attribute table (one entry per 4×8 cell, low nibble =
foreground color, high nibble = the 2-bit background register selector
$21-$24) goes to $D800-$DBE7.

## C64 hardware facts you'll need

- **CPU**: MOS 6510 (6502 + 6-bit I/O port at $00/$01). 1 MHz PAL.
  Banks BASIC/KERNAL/CHAREN via writes to $01.
- **VIC-II** at $D000-$D3FF. 47 registers, mirrored every 64 bytes.
  The 16-color palette is fixed (see docs/c64/vic/vic_registers.md).
  The raster counter is 9 bits: $D012 is the low 8, bit 7 of $D011
  is bit 8.
- **SID** (6581) at $D400-$D41C. 3 voices, ADSR envelopes, filter.
  Volatile freq registers, no NaN, master volume at $D418.
- **CIA 1** at $DC00: keyboard, joystick, paddles, datasette,
  IRQ timer. Joystick bytes are active-low: bit 4 = fire.
  - Port 1 (right joystick, Hare) = $DC01
  - Port 2 (left joystick, Scoot) = $DC00
- **CIA 2** at $DD00: serial bus, RS-232, NMI, **VIC bank bits**
  (low 2 bits of PRA select one of 4 VIC banks).
- **KERNAL** at $E000-$FFFF. Jump table at $FF81-$FFF3.
  IRQ vector at $0314 (default → $EA31, the standard KERNAL ISR).
  NMI vector at $0318 (default → $FE47, the soft-reset / RESTORE handler).
- **Color RAM** at $D800-$DBE7: 4-bit wide (low nibble only).
- **Character ROM** at $D000-$DFFF in banks 0 and 2; can be relocated
  to RAM by changing $D018.
- **PAL timing**: 312 lines, 50 Hz. The "stable raster" line for IRQs
  is line 311 (right after vertical blank, before any badlines).
- **Badlines** cost 40 cycles every 8 text lines. Cycle-accurate
  code has to know this.

## Oscar64 patterns to use

- `mmap_trampoline()` once at startup, then `mmap_set(MMAP_RAM)` to
  bank out BASIC + KERNAL (gives you ~38 KB contiguous RAM at
  $0900-$A000). `mmap_set(MMAP_NO_ROM)` also banks out CHAR ROM
  ($D000 becomes I/O, not char data — needed for the bitmap at $E000).
- `#pragma region(name, start, end, , , {sections})` to remap
  memory (you probably won't need this for the first pass — the
  default layout works).
- `#pragma stacksize(N)` and `#pragma heapsize(N)` to size those.
- `#pragma compile("foo.c")` is what `#include <stdio.h>` etc. use
  to drag in implementation files. You never list multiple `.c`
  files on the command line; the headers do it.
- `__assume(x < 8)` etc. to give the optimizer value-range hints.
  Helps the 6502 backend use 8-bit ops instead of 16-bit.
- `__striped` qualifier for arrays where the 6502's lack of
  indirect-with-offset hurts.
- `p""` prefix for PETSCII string literals (not ASCII). The C64's
  char ROM is not ASCII.
- `__hwinterrupt` for ISRs (saves A/X/Y, exits with RTI).
- `__native` for a function you want to force to native 6502 code.
- `__zeropage` for global variables you want placed in ZP
  (or use `-Oz` to auto-place).
- The runtime headers in `./oscar64/include/` are the right way to
  touch hardware: `#include <c64/vic.h>` (VIC-II struct at $D000),
  `#include <c64/cia.h>` (joystick reading helpers),
  `#include <c64/memmap.h>` (mmap_set, mmap_trampoline),
  `#include <c64/rasterirq.h>` (raster IRQ API — use this, don't
  write your own IRQ handler from scratch),
  `#include <c64/sprites.h>` (sprite setup, alignment),
  `#include <gfx/bitmap.h>` (hires drawing helpers),
  `#include <stdio.h>` / `<conio.h>` for text I/O.

## Game-specific design (full version in GAME.md)

| Element | Value |
|---------|-------|
| Title screen | `source_images/screen_title.png` — full-screen image with "Nyuller" logo |
| Waiting 1 | `source_images/screen_waiting1.png` — 1.2 sec, "ping" jingle |
| Waiting 2 | `source_images/screen_waiting_2.png` — random 2-5 sec, suspense music |
| DRAW | white screen, big counter incrementing each frame, sharp stab |
| Win Hare | `source_images/screen_win_hare.png` — Hare won (player 1) |
| Win Scoot | `source_images/screen_win_scoot.png` — Scoot won (player 2) |
| Score bar | top 8 pixels of the screen, "HARE 0..0 SCOOT" (5 pips per side) |
| Match | first to 5 wins, then reset to title |
| Player 1 (Hare) | left side, joystick port 1, fire = `(PEEK(0xDC01) & 0x10) == 0` |
| Player 2 (Scoot) | right side, joystick port 2, fire = `(PEEK(0xDC00) & 0x10) == 0` |
| State machine | TITLE → READY → WAIT → DRAW → WIN_P1/P2 → (back to READY or GAMEOVER) |
| Game timer | 50 Hz PAL, line 311 for the raster IRQ |
| Random | use `PEEK(0xD41B)` (SID oscillator 3, effectively random) |

## Commit conventions

- One commit per phase, with a clear `Phase N: <summary>` prefix.
- Don't commit generated build artifacts in `build/` (gitignored).
- Generated data files (e.g. `src/data/processed/*.bin`) are checked
  in so the build doesn't depend on Python being installed.

## What to do if you get stuck

1. Re-read the relevant section of `OSCAR64.md`, `PROG_C64.md`,
   `GAME.md`, or `tasks.md` (your phase section).
2. Look at the Oscar64 samples: `../oscar64/samples/`. They're
   small, focused, and have working patterns. Good ones to look at:
   - `../oscar64/samples/memmap/allmem.c` — mmap_set usage
   - `../oscar64/samples/rasterirq/colorbars.c` — raster IRQ
   - `../oscar64/samples/memmap/easyflash.c` — memory layout
   - `../oscar64/samples/hires/lines.c` — hires drawing
   - `../oscar64/samples/sprites/` — sprite setup
3. Look at the runtime headers you need to use:
   `ls /home/ballz/work/teletype/nyuller/oscar64/include/c64/` etc.
4. Read the relevant docs/c64/ file for the chip you're working on.
5. Do NOT spend time on VICE, xvfb, environment setup, or anything
   not in this project. The build environment is set up.

## Output for this phase

When you're done, report back:
1. What you built (1-2 sentence summary)
2. The output of `make run` (proves it compiled and runs)
3. The git commit hash and one-line summary
4. Any concerns or follow-up work for the next phase