Prepare Capital Quest public edition and player manual

This commit is contained in:
Brian Holman committed 2026-11-11 19:27:51 -07:00
1 parent 46f4b9cae0
commit afa6f3c2a0
40 files changed
+1072 -106

No files matched your search

+85 -84
View File
@@ -1,113 +1,114 @@
# Capital Quest — 50 States and Capitals
# Capital Quest for CoCo
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.
A map-based geography quiz about all 50 United States and their capitals, designed
by Brian Holman with assistance from ChatGPT/Codex. Play with four capital choices
or type each answer. Review the states you missed when the journey ends.
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.
![Capital Quest title and mode selection](docs/manual/images/title.png)
## Download
## Play
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`.
Use a **Color Computer 3 with 512 KB or more, BASIC, an FD-502 Disk BASIC
controller, and a keyboard**. RGB is the tested display presentation. MC6809 and
HD6309 have been tested in VCC Plus; this is not physical-hardware qualification.
The two graphics pages reserve 64 KB outside a 128 KB machine's RAM, so this
edition requires 512 KB even though it does not use all installed memory.
## Build and play
Download [CAPITAL.DSK](CAPITAL.DSK), preserve your existing guest work, insert a
copy into **FD0**, and **Cold Restart**. At the Disk BASIC `OK` prompt, type `DOS`
and press Enter. Alternatively use `LOADM"CAPITAL.BIN":EXEC`. The game does not
write to its disk, and a write-protected copy is suitable for 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.
Read the [complete player manual](docs/manual/CAPITALQUEST.md) for every screen,
control and answer rule. The [online guide](https://vccplus.brianholman.com/games/capital-quest/)
is the shared reading edition.
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.
- Title: **1** multiple choice, **2** typed answers, **C** credits, **Q** quit.
- Multiple choice: **1–4**. The correct slot is random, excluding the previous
question's correct slot. The first question may use any slot. Feedback advances
automatically after its tones and reading pause.
- Typed answers: letters, spaces and periods; **Backspace** edits and **Enter**
submits. Case and extra spaces do not matter. Saint Paul, St Paul and St. Paul
are accepted. A close spelling offers **R** to retry or **V** to reveal.
**Esc/CoCo Break** reveals while editing. **Space** advances after feedback.
- Map: **teal** unanswered, **purple** correct, **red** incorrect, **yellow**
current. Northeast and Hawaii details use the same colors.
- Results: **R** review, **N** next review page, **B** back to results, **P** play
again, **Q** quit to BASIC. Release keys between presses. Scores and progress
are not saved; a new quiz clears them.
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.
## Build your own copy in VCC Plus
## Reproduce from the command line
1. Download/extract the source project or clone this repository into a new,
writable folder. Preserve a clean disk and any source changes you already have.
2. In VCC Plus, choose **Develop → C Development…**, then open the folder that
contains `Makefile`, `main.c` and `vccplus-project.json`.
3. Select **Release**, then **Build**. The declared target builds the disk.
4. Use **Show Build Products** to find `build/CAPITAL.dsk` and `build/CAPITAL.bin`
in that build's snapshot. Mount a copy with the setup above and run `DOS`.
The workbench is the supported build/test path. An equivalent offline build
uses the *installed* app's bundled tools, without an emulator source checkout:
The project uses VCC Plus's bundled CMOC 0.1.100, LWTools 4.25, Make, Perl and
libraries. Ordinary game builds need no Xcode, Command Line Tools, Homebrew or
system Perl. Generated map/state C files are included. Opening source does not
build or run it automatically. Read [provenance and notices](docs/PROVENANCE.md)
before redistributing modifications.
An equivalent command-line build uses the installed app's tools:
```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.
`Release` uses `-O2`; `Debug` retains frame pointers with `-O2` to fit the same
memory budget. `Test` uses `-O2` and seed **2709**. Clean before switching
configurations in one working folder because the Makefile shares `obj/`:
```sh
python3 tools/prepare_assets.py # offline map/data generation
make test # host logic and geometry checks
make clean
make VCC_CONFIGURATION=Test disk
```
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.
Code/static data are linked at `$2000`, below `$7800`, with a separate 2 KB stack
allowance below `$8000`. Graphics use the public GIME library's two reserved
physical pages at `$40000–$4FFFF`.
For the complete public-MCP regression suite, export a private connection with
both Make and disposable playtests enabled, then run:
## Editable inputs and optional tests
`main.c`, `src/quiz.c` and `src/ui.c` implement play. `data/states.tsv`,
`data/map-seeds.json` and `assets/usa-source.svg` are the editable data/artwork
inputs. `src/states.c` and `src/map_data.c` are generated and retained. Root-level
headers remain available to isolated C-workspace builds.
Python 3 is required only for optional asset regeneration and test scripts:
```sh
PYTHONDONTWRITEBYTECODE=1 python3 tests/playtest.py /private/path/connection.json \
--evidence /tmp/capital-quiz-evidence
python3 tools/prepare_assets.py
make test
```
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.
`make test` additionally needs a host C compiler. It checks state shuffles,
unique choices, nonrepeating correct slots, matching, scoring, reset and geometry.
These extra prerequisites do not apply to an ordinary in-app disk build.
## Sample screens
For assistant-assisted development, review **Assistant… → Files shared**, enable
**Use Project Makefile** and **Allow Disposable Playtests** where appropriate,
and export a fresh private connection outside the project. Discover the actual
advertised tools and project revision before building. Private grants, tokens,
ROMs and personal media never belong in a source download. The optional
`tests/playtest.py PRIVATE_GRANT --evidence /outside/project/evidence` driver
uses the supported public MCP interface and keeps full captures outside the
watched source folder.
Screenshots of Capital Quest running in VCC Plus.
## License, credits and development history
### Title and mode selection
Game source is **GPL-3.0-or-later**; see [LICENSE](LICENSE). The adapted map remains
**© Fla-shop.com, CC BY 4.0**. Pierre Sarrazin's font and disk boot helper retain
their public-domain notices. Linked compiler/runtime libraries retain their
component terms. Preserve [assets/CREDITS.md](assets/CREDITS.md), the component
notices, and the corresponding-source information in [docs/PROVENANCE.md](docs/PROVENANCE.md).
![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)
The [original development brief](https://vccplus-git.brianholman.com/VCCPlusApps/CoCoCapitalQuiz/src/branch/main/CHATGPT_PROMPT.md) is historical project evidence,
not instructions to overwrite a downloaded project. Dated records in `docs/`
describe their named milestones; older tool limitations are not current app
compatibility claims. The player manual describes the delivered game.