# 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.

## Download

Download the ready-to-run [CAPITAL.DSK](CAPITAL.DSK) included at the repository
root. Mount a copy in VCC Plus with a **512 KB CoCo 3 / 6809 Disk BASIC** setup,
then type **DOS**, or `LOADM"CAPITAL.BIN":EXEC`.

## 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.
Both modes play a rising tone for a correct answer and a lower, falling tone
for an incorrect answer, using the CoCo's built-in sound output. No sound
cartridge is needed. Multiple-choice feedback advances automatically after
the tone and a 1.5-second reading pause. In typed mode, **Space** advances after
feedback. Release answer keys before answering the next question; a held key
cannot submit another answer.

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`, `src/ui.c` and the root-level
`quiz.h`, `ui.h` and `map_data.h` headers. Keeping project headers beside
`main.c` also makes them available to VCC Plus's isolated build snapshots. Generated drawing
and state C files are retained for toolchain-only builds. Generated build outputs
are ignored; the root-level `CAPITAL.DSK` is the checked-in playable release.
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 baseline emulator coverage, [feedback tests](docs/FEEDBACK_TESTING.md)
for the sound and automatic-advance checks, 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.

## Sample screens

Screenshots of Capital Quest running in VCC Plus.

### Title and mode selection

![Title screen with a U.S. map and choices for multiple-choice or typed answers](docs/images/title.png)

### Multiple choice

![Multiple-choice question asking for Ohio's capital, with Ohio highlighted on the map](docs/images/multiple-choice.png)

### Results

![Results screen showing 47 out of 50 correct answers and a score of 94 percent](docs/images/results.png)