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

+248
View File
@@ -0,0 +1,248 @@
# Capital Quest for CoCo
Capital Quest is a geography quiz about the 50 United States and their capitals. Follow the highlighted state on a color map, choose its capital or type the answer yourself, and watch the map record your progress. Every game asks about all 50 states once, in a shuffled order.
Start with multiple choice to learn the names and locations. Switch to typed answers when you want to recall a capital without seeing the choices. After the last question, review the states you missed and try another journey.
By Brian K. Holman. © Brian K. Holman 2026.
## Get the game running
Use the **Download game disk** link supplied with this manual to obtain `CAPITAL.DSK`. The [online player guide](https://vccplus.brianholman.com/games/capital-quest/) offers the reading edition and reviewed PDF download. You can play the ready-made disk without compiling the source. The **Source code** link provides the editable project; see [Make your own changes](#make-your-own-changes).
### Machine setup
Capital Quest needs this setup:
| Item | Required setup |
| --- | --- |
| Computer | Color Computer 3 |
| RAM | 512 KB or more |
| Processor | MC6809; HD6309 also tested in VCC Plus |
| System | CoCo 3 BASIC with Disk BASIC and an FD-502 floppy controller |
| Disk | `CAPITAL.DSK` in floppy drive FD0, the CoCo's drive 0 |
| Display | RGB is the tested color presentation |
| Input | Keyboard |
| Sound | Built-in CoCo sound; no sound cartridge needed |
Use VCC Plus's normal CoCo 3 Disk BASIC setup and select at least 512 KB of RAM. This edition has been tested in VCC Plus 3.6.1 with both emulated processors. These emulator checks do not establish compatibility with a physical CoCo.
The 512 KB requirement comes from the graphics design. The game keeps one picture visible while drawing the next picture in a second buffer. Those buffers occupy a reserved 64 KB area outside a 128 KB machine's RAM. The game does not use all 512 KB, but this edition cannot run with only 128 KB.
### Load the disk in VCC Plus
1. Start VCC Plus and select the machine setup above.
2. Open **Media → Floppy Disks…** and insert your copy of `CAPITAL.DSK` into **FD0**.
3. Save any existing work in the emulated CoCo before restarting it. Choose **Cold Restart** through the app's machine controls, then let BASIC reach its `OK` prompt.
4. Click the CoCo display to give it keyboard focus. Type `DOS` and press `Enter`.
5. When the Capital Quest title screen appears, press `1` for multiple choice or `2` to type the capitals.
The disk's DOS loader starts the game. If you need to load it explicitly, enter this command at the Disk BASIC prompt:
```text
LOADM"CAPITAL.BIN":EXEC
```
The game does not write to its disk, so a write-protected copy is suitable for play. Keep your original download as a clean copy. You do not need to format the disk or add any files to it.
## Choose a mode
The title screen shows the national map and four choices. It is also where **Play Again** returns you after a completed quiz.
| Key | Title-screen action |
| --- | --- |
| `1` | Start a 50-question multiple-choice quiz |
| `2` | Start a 50-question typed-answer quiz |
| `C` | Read the credits |
| `Q` | Quit to BASIC |
![The Capital Quest title screen offers multiple choice, typed answers, credits, and Quit.](images/title.png)
Choosing either quiz mode starts with zero points and a fresh map. All 50 states appear once. The state order is shuffled for each game; repeated play can still produce familiar stretches by chance. There is no difficulty menu, player-name entry, or timer that reduces your score. The two modes use the same states, capitals, map colors, and scoring.
The title map is light teal throughout. It does not carry over the colored answer history of a previous game.
## Read the map
The top of a question screen identifies the mode, question number, and current score. Beneath the map, the game names the state and asks for its capital. Read that state name even when a very small state is hard to pick out on the national map.
| Map color | Meaning |
| --- | --- |
| Light teal | You have not answered this state yet |
| Dark purple | You answered this state correctly |
| Red | You answered this state incorrectly or revealed its answer |
| Yellow | This is the state in the current question |
The colors describe your answers, not regions of the country. They do not group states by geography, time zone, or political boundaries. A correct answer after a spelling correction counts as correct and becomes purple.
![The progress map uses teal for unanswered states, purple for correct answers, red for misses, and yellow for the current question.](images/progress-map.png)
The current state stays yellow while its answer feedback is visible. When the next question opens, the state you just answered changes to purple or red and the next state becomes yellow. The ordinary right-hand panel shows the four-color legend.
### Northeast detail
For selected northeastern states, a larger **NORTHEAST** view replaces the legend. A yellow outline on the national map marks the enlarged area. Both views use the same progress colors, so you can see the small current state without losing its national location.
![The Northeast detail enlarges small states while the national overview remains visible.](images/northeast.png)
### Alaska and Hawaii
Alaska and Hawaii appear as labeled insets on the national map. A Hawaii question also opens an enlarged **HAWAII** view on the right. The island shapes are simplified to fit the display.
![A Hawaii question shows an enlarged island view beside the national map.](images/hawaii.png)
The national map and its insets are learning aids. Alaska, Hawaii, and the enlarged views are not drawn to one common scale. Very small islands may disappear at the CoCo's screen resolution.
## Play multiple choice
Press `1` at the title screen. Each question presents four different capitals in numbered positions: `1` and `2` on the upper row, `3` and `4` on the lower row. Exactly one belongs to the highlighted state.
Press the number beside your answer. You do not need to press `Enter`. The game accepts that choice once, shows whether it was correct, gives the capital, and then moves on automatically.
![A multiple-choice question places four numbered capital choices below the highlighted state.](images/multiple-choice.png)
The correct answer starts in any of the four positions. On each following question, it is chosen randomly from the other three positions. For example, if the correct answer was `3`, it can be `1`, `2`, or `4` next, but it cannot be `3` again immediately. This follows the correct answer's position, even if you chose a different number. A new quiz starts this rule afresh.
### Answer feedback
A correct answer displays **CORRECT!** and plays a rising pair of tones. An incorrect answer displays **NOT THIS TIME.** and plays a lower, falling pair. In both cases, the screen states the correct capital.
![Correct-answer feedback confirms the result and names the capital.](images/correct-feedback.png)
After the sound, multiple-choice mode leaves about 1.5 seconds to read the feedback, then opens the next question. You do not need `Space` or `Enter` to continue.
Release the number key after choosing. A held key cannot submit an answer to the next question; let go before pressing its answer. You can take as long as you need while a question is waiting for a choice.
## Type the capital
Press `2` at the title screen. The question appears without answer choices. Type the capital in the entry line, then press `Enter` to submit it.
Letters and spaces form the answer. Periods are also accepted for the supported **St. Paul** spelling. The underscore marks the end of your entry. `Backspace` removes the last character; continue typing to append a replacement. This is an end-of-line editor, not a movable text cursor.
![Typed-answer mode shows an editable answer line and the keys for submission, correction, or reveal.](images/typed-entry.png)
### What counts as a match
Capital Quest ignores letter case. `Denver`, `DENVER`, and `denver` all match. Leading and trailing spaces are ignored, and repeated spaces between words are treated as one space. For example, an answer with extra spaces around **Salt Lake City** is accepted.
For Minnesota, **Saint Paul**, **St Paul**, and **St. Paul** are accepted. The period belongs in the abbreviated spelling shown here. Other punctuation changes and informal nicknames are not automatically accepted.
An exact match or accepted alias earns one point. Pressing `Enter` on a blank answer records a miss. Entering a different state's known capital is also a miss, even if its spelling happens to resemble the expected answer.
### A close spelling
If the entry is close to the expected spelling, the game may offer a second look. The screen says **That looks close. Check your spelling** and offers:
| Key | Spelling-prompt action |
| --- | --- |
| `R` | Return to the entry and edit the answer you already typed |
| `V` | Reveal the correct capital and record a miss |
No point has been awarded at this prompt. Press `R`, use `Backspace` to remove the wrong ending, and type the correction. Press `Enter` again when ready. You do not have to retype the entire answer if only its ending needs changing.
![The close-spelling prompt offers Retry or Reveal and says that no point has been awarded yet.](images/spelling-retry.png)
The spelling aid is a limited safety net. It does not recognize every possible typo. Short or substantially different answers can be marked incorrect immediately. Keep checking the state name: a correctly spelled capital for another state is not a spelling correction.
An accepted answer after `R` still earns one point. The results also count it under **correct after spelling correction**. That count describes part of your correct total; it is not a bonus added on top.
### Reveal an answer
While editing a typed answer, press the CoCo's `BREAK` key to reveal the capital and record the question as incorrect. In VCC Plus, the Mac's `Esc` key supplies CoCo Break. The feedback names the capital, and the map will mark the state red on the next question.
At the close-spelling prompt, use `V` to reveal instead. Revealing never earns a point. It can be useful when you want to see the answer and continue learning rather than keep guessing.
### Entry length
The entry holds at most 39 characters, including spaces and periods. Extra characters are ignored and a message says **39 characters maximum. Backspace to edit.** Use `Backspace` to shorten the entry, or submit it with `Enter`. No state capital needs an entry this long.
### Continue after a typed answer
Typed feedback uses the same result messages, capital display, and tones as multiple choice. It stays visible until you are ready to continue.
![Incorrect typed-answer feedback gives the correct capital and waits for Space before continuing.](images/incorrect-feedback.png)
Release the key you used, read the answer, and press `Space` for the next question. The game does not advance typed feedback automatically. During entry, a space is part of the capital's name; it advances only when the feedback screen asks you to continue.
## Understand your score
Each state is worth one point. A correct multiple-choice selection, a correct typed answer, or an accepted spelling correction earns that point. A wrong answer, blank submission, or reveal earns zero. There are no speed bonuses, time penalties, or negative points.
The score beside the question number is your correct-answer total so far. At the end, **YOUR RESULTS** shows:
- Your number correct out of 50.
- Your percentage: the correct total multiplied by two.
- How many correct answers followed a spelling correction.
- How many states you missed and can revisit.
For example, 40 correct answers produce 80 percent and 10 states to revisit. The maximum is 50 out of 50, or 100 percent. Each state contributes at most one point.
![The results screen shows the correct total, percentage, spelling-correction count, and options to review, replay, or quit.](images/results.png)
| Key | Results-screen action |
| --- | --- |
| `R` | Review the missed states |
| `P` | Return to the title screen to choose another quiz |
| `Q` | Quit to BASIC |
## Review missed states
Press `R` at the results screen. **MISSED STATES** lists up to three missed questions per page, in the order they appeared during your game. Each entry shows the state, your recorded answer, and its correct capital.
A directly revealed typed answer is shown as **[revealed]**. A blank entry is shown as **[blank]**. If you used `V` after a close spelling, the review can show the text you had entered before revealing.
![Missed-answer review lists the state, the player's answer, and the correct capital, with paging controls below.](images/missed-review.png)
Press `N` when **NEXT PAGE** is offered. Press `B` to return to the results screen. On the last page, only `B` is needed. If you answered every state correctly, the review says **A perfect trip! No missed states.**
Reviewing does not ask the questions again and does not change your score. It lets you study the completed game's misses before replaying or quitting.
## Replay, quit, and saved progress
At the results screen, `P` returns to the title. Choose `1` or `2` for a new quiz. The new game clears the score, answer history, spelling-correction count, and map colors, and shuffles all 50 states again. You can change modes between games.
`Q` quits from the title or results screen. The game uses the CoCo 3's high-speed clock during play. Quitting restores BASIC's text display and normal clock speed, prints **Thanks for playing Capital Quest!**, and returns to BASIC. There is no separate quit command during an unfinished quiz. In typed mode, `Q` is an ordinary answer letter.
Capital Quest does not save games, results, high scores, or preferences to disk. Your current quiz and review exist only in the running session. Quitting, restarting the machine, or beginning a new quiz loses them. Take a screenshot of the results if you want a record.
There is no in-game settings screen or joystick mode. Use the keyboard controls in this guide. Display scaling and sound volume are controlled by VCC Plus rather than by a game settings menu.
## Credits and licenses
Press `C` at the title screen to open **A MAP FOR EVERY STATE**. Press `Space` to return. The screen identifies the map source, its Creative Commons license, the adapted map work, and the font author.
![The credits screen identifies Fla-shop.com's map, its CC BY 4.0 license, the adaptations, and Pierre Sarrazin's font.](images/credits.png)
The map is **© Fla-shop.com**, used under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). The original map and its source information are available from [Fla-shop.com's United States SVG map](https://www.fla-shop.com/svg/usa/).
The game adapts that map through state-region assignment, reduced resolution, simplified boundaries, recoloring, run-length encoding, and Northeast and Hawaii detail views. The insets are not to a common scale. The map's inclusion does not imply endorsement by its creator.
Pierre Sarrazin's **font5x8** is public domain. The disk boot helper is adapted from his public-domain **autostart.c 0.1.2**. CMOC, LWTOOLS, and the linked libraries retain their own authorship and notices. The source distribution includes `assets/CREDITS.md` and the component notice files; preserve them when sharing modified copies. The [matching library-source companion](https://vccplus.brianholman.com/dl/software/CoCoLibrary/Sources/Exclusives/CapitalQuest/2026-11-11/43fcd00f12ef/Capital-Quest-Library-Sources.zip) provides the linked runtime, graphics, keyboard, and font sources with their original notices.
This manual is © Brian K. Holman 2026 and is released under the **GNU General Public License, version 3 or later**. The project includes the full license text. The map retains its CC BY 4.0 terms, and the public-domain font and boot helper retain their separate status.
## Make your own changes
The **Source code** link accompanying this manual provides the editable C project. Keep an untouched copy of the approved disk and work in a separate, writable copy of the source. You can change the quiz's presentation or use it as a small learning project while preserving its licenses and attribution.
In VCC Plus, choose **Develop → C Development → Open** and select the extracted project folder containing `vccplus-project.json` and `Makefile`. Select **Release** and choose **Build**. The declared build target produces the game disk. Use **Show Build Products** to find `build/CAPITAL.dsk` and `build/CAPITAL.bin` in the workspace's build snapshot, then test your new disk with the machine setup in [Get the game running](#get-the-game-running).
VCC Plus supplies the supported compiler and build tools for this workflow. You do not need Xcode, Homebrew, or a separate compiler installation merely to open and build this project in the app. Asset regeneration and optional host-side tests have additional requirements described in the source README; the generated drawing and state data are already included for ordinary builds.
If you connect ChatGPT to your personal project copy, review which files the connection shares and enable the project's Makefile workflow when building through that connection. Keep private connection files out of anything you share. Review suggested edits, build them, and test a separate disk copy before replacing a game you want to keep.
## Troubleshooting
| What you see | What to check |
| --- | --- |
| **Requires 512 KB CoCo 3 in BASIC.** | Select a CoCo 3 with at least 512 KB, start in ordinary BASIC text mode, and cold restart before loading. A 128 KB setup is insufficient for this edition. |
| `DOS` does not start Capital Quest | Confirm that the complete `CAPITAL.DSK` is in FD0 and that the machine has Disk BASIC with its floppy controller. Cold restart and try `DOS` again. The explicit `LOADM` command above is another loading route. |
| The game does not respond to keys | Click the CoCo display or use VCC Plus's **Input → Focus CoCo Display** command. Release the previous key before pressing a new one. |
| Typed feedback seems to be stuck | Read the feedback, release the previous key, and press `Space`. Typed feedback waits for you; multiple-choice feedback advances automatically. |
| A typed capital is marked wrong | Check the named state, the spelling, and the accepted Saint Paul forms. Case and extra spaces are ignored, but arbitrary abbreviations and punctuation are not. |
| There is no sound | Check the app's sound controls, Mac volume, and selected audio output. The feedback uses built-in CoCo sound and does not require an add-on sound cartridge. |
| The map's colors seem unexpected | Yellow is the current question, teal is unanswered, purple is correct, and red is incorrect. The current state remains yellow through feedback. |
| **Graphics timer stopped.** | The game could not complete a display update and has exited. Return to the standard BASIC setup, cold restart, and load the disk again. |
| A previous score is missing | Scores are not saved. A new quiz, quit, or machine restart clears the session's results. |
Before restarting, preserve any other work in the emulated computer. Keep a clean downloaded disk and a separate copy for your own builds so that troubleshooting does not replace a project or program you want to retain.