# Capital Quest — 50 States and Capitals

A C geography quiz for a **512 KB Color Computer 3 / Motorola 6809**, built with
**VCC Plus 3.5.0** and its bundled CMOC toolchain. A 320×192, 16-color national
map highlights the current state. Northeast and Hawaii detail views retain
the national overview.

The application was generated with **ChatGPT Codex** using **GPT-6.1 Sol High**,
following the project brief in [CHATGPT_PROMPT.md](CHATGPT_PROMPT.md). Development
included builds and gameplay tests through VCC Plus’s public MCP interface.

## Build and play

1. In VCC Plus, choose **Develop → C Development → Open**, and select this folder.
2. Select **Release**, then **Build** (the declared target builds the disk).
3. Use **Show Build Products** to find `build/CAPITAL.dsk` and `CAPITAL.bin` in
   the workbench's build snapshot. A delivered copy is also in this checkout's
   ignored `build/` folder after the implementation session.
4. Mount your own copy of `CAPITAL.dsk` in a 512 KB 6809 Disk BASIC machine.
   Type **DOS**, or `LOADM"CAPITAL.BIN":EXEC`. Keep personal media separate.

Title: **1** multiple choice, **2** type the capital, **C** credits, **Q** quit.
Multiple choice: **1–4**. Typed answers: letters/spaces/periods, **Backspace**
(CoCo Left) and **Enter**. The Mac's Escape maps to CoCo Break and reveals an
answer. A near spelling offers **R** to edit the existing answer or **V** to
reveal. Only an exact/accepted alias earns a point. A successfully corrected
answer earns one point and increments the separate correction count.
Release keys between presses; **Space** advances after feedback.

After all 50 questions: **R** paginated missed-answer review, **N** next review
page, **B** results, **P** play again, **Q** return to BASIC. Replay returns to
the mode menu. Normal games mix BASIC timer values, waiting-loop timing and
start input into the random seed. The program uses the CoCo 3's documented
high-speed clock during play and restores normal speed on exit.

## Reproduce from the command line

The workbench is the supported build/test path. An equivalent offline build
uses the *installed* app's bundled tools, without an emulator source checkout:

```sh
export PATH="/Applications/VCC Plus.app/Contents/Resources/Toolchain/bin:$PATH"
make clean
make VCC_CONFIGURATION=Release disk
```

`Release` uses `-O2`. `Debug` retains frame pointers while using `-O2` to
fit the complete game in the same strict memory budget. `Test` uses `-O2`
and seed **2709** for reproducible
ordinary gameplay. Clean before switching configurations because the Makefile
uses a common object directory. VCC Plus builds fresh snapshots automatically.

Code and static data are linked at `$2000`, limited to below `$7800`, with a
2 KiB stack allowance below `$8000`. The public GIME library reserves physical
`$40000–$4FFFF` for its two graphics pages. No raw graphics/MMU register writes,
SVG parsing, dynamic allocation or disk writes occur during quiz play.

```sh
python3 tools/prepare_assets.py  # offline map/data generation
make test                       # host logic and geometry checks
```

The editable inputs are `data/states.tsv`, `data/map-seeds.json`,
`assets/usa-source.svg`, `main.c`, `src/quiz.c` and `src/ui.c`. Generated drawing
and state C files are retained for toolchain-only builds. Build outputs are
ignored. The public MCP JSON-RPC client in `tools/vcc_mcp.py` takes an exported
private grant path; keep that grant outside Git. See [test evidence](docs/TESTING.md)
for actual emulator coverage and limitations, and [credits](assets/CREDITS.md)
for map attribution and licenses.

For the complete public-MCP regression suite, export a private connection with
both Make and disposable playtests enabled, then run:

```sh
PYTHONDONTWRITEBYTECODE=1 python3 tests/playtest.py /private/path/connection.json \
  --evidence /tmp/capital-quiz-evidence
```

This builds the advertised Test configuration, plays two complete quizzes with
ordinary physical keys, checks actual framebuffer text and state fill pixels,
and retains the test disks. Evidence stays outside the checkout until tests
finish so VCC Plus's watched source revision remains stable.