Files
CoCoCapitalQuiz/README.md
T

115 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Capital Quest for CoCo
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.
![Capital Quest title and mode selection](docs/manual/images/title.png)
## Play
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.
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.
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** 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.
## Build your own copy in VCC Plus
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 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 VCC_CONFIGURATION=Release disk
```
`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
make clean
make VCC_CONFIGURATION=Test disk
```
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`.
## 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
python3 tools/prepare_assets.py
make test
```
`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.
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.
## License, credits and development history
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).
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.