Prepare Capital Quest public edition and player manual
This commit is contained in:
1 parent
46f4b9cae0
commit
afa6f3c2a0
40 files changed
+1072
-106
No files matched your search
@@ -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.
|
||||

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

|
||||
|
||||
### Multiple choice
|
||||
|
||||

|
||||
|
||||
### Results
|
||||
|
||||

|
||||
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.
|
||||
Reference in new issue
Block a user