CoCoCapitalQuiz/README.md

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. Development included builds and gameplay tests through VCC Plus’s public MCP interface.

Download

Download the ready-to-run 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:

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.

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 for baseline emulator coverage, feedback tests for the sound and automatic-advance checks, and credits 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:

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