114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
### Multiple choice
|
||
|
||
|
||
|
||
### Results
|
||
|
||
|