Prepare public CoCo 3 documentation and portable VCC Plus workflow
This commit is contained in:
1 parent
e9574b6f0d
commit
4aa739780c
16 files changed
+572
-913
No files matched your search
+31
-38
@@ -4,15 +4,20 @@
|
||||
|
||||
Build a careful stack, leave room for the next piece, and turn a falling-block puzzle into a high-score chase. **Quadrapassel for CoCo** brings a familiar game to the Color Computer 3 with seven distinct piece colors, keyboard and analog joystick controls, two scoring systems, and high scores saved to disk.
|
||||
|
||||
This manual describes **game disk build 05**, `QUADPSL05.DSK`. The game build number is separate from the VCC Plus emulator version. Screenshots are real guest-framebuffer captures of this build running in VCC Plus 3.6.1 (54), using a disposable MC6809 / 512 KB session. They are not mockups, Mac screenshots, or pictures of a proposed interface.
|
||||
This player’s manual covers **game disk build 05**, `QUADPSL05.DSK`, for a **Color Computer 3 with 128 KB or more**. The screenshots show the actual CoCo game and its menus.
|
||||
|
||||
**© Brian K. Holman 2026**
|
||||
|
||||
### Get the game and source
|
||||
|
||||
- **[Download the game disk — QUADPSL05.DSK](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel/raw/commit/49bc78158a5e17ba717381a3a2cbb4ab35c36dfe/QUADPSL05.DSK)**. Keep the original and play from a writable copy so the game can save your settings and records.
|
||||
- **[Browse the source code](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel)**. The repository contains the GPL-licensed CoCo game, documentation, and component acknowledgements.
|
||||
|
||||
### A clean-room CoCo implementation
|
||||
|
||||
The CoCo game was written anew in C from a behavioral specification, with the goal of being functionally similar to Quadrapassel for Linux and Mac. No Linux or Mac application source code is incorporated into the CoCo game. The Quadrapassel name was deliberately retained for branding continuity, and this implementation uses the GNU GPL, like the reference game.
|
||||
|
||||
The behavioral specification and reference piece/scoring data preserve their GPL provenance and the original contributors' acknowledgements. This is an independent CoCo implementation, with deliberate adaptations for its machine, controls, display, and storage. It is not a claim that every behavior, random sequence, visual effect, or platform feature is identical to the Linux or Mac applications. Font and library contributions have their own acknowledgements in [Copyright, license, and credits](#copyright-license-and-credits).
|
||||
The rules and reference piece/scoring data preserve their GPL provenance and original contributor acknowledgements. The CoCo edition adapts the controls, display, and storage for the Color Computer while retaining the familiar falling-block experience. Font and library contributions are acknowledged in [Copyright, license, and credits](#copyright-license-and-credits).
|
||||
|
||||
### How to use this manual
|
||||
|
||||
@@ -24,9 +29,9 @@ The names in this manual match the game's menus. Key-shaped labels represent key
|
||||
|
||||
### Machine and media
|
||||
|
||||
The current edition is for a **Color Computer 3 with Disk BASIC and a writable game disk**. The design target is 128 KB; the current detailed emulator checks use 512 KB. Brian has also reported successful play on a physical 512 KB CoCo 3. Actual 128 KB qualification remains pending. This manual does not present a 512 KB test as proof of a 128 KB pass.
|
||||
Play on a **Color Computer 3 with 128 KB or more, Disk BASIC, and a writable game disk**. Use a compatible disk drive or disk-image setup that lets the game read its resources and save your records. The game has been successfully played on a physical 512 KB CoCo 3 and verified in VCC Plus with 128 KB.
|
||||
|
||||
A CoCo 2 adaptation is not included in this disk. Additional RAM does not unlock a separate higher-resolution edition of this game: the current CoCo 3 presentation uses its 320 × 192, 16-color graphics mode. Seven colors identify the pieces; other palette entries support text, background, outlines, and shadow.
|
||||
The game uses a **320 × 192, 16-color display**. Seven colors identify the pieces; the remaining palette entries support text, background, outlines, and the landing shadow. The same presentation is used on 128 KB and larger CoCo 3 systems.
|
||||
|
||||
You can play with the keyboard, a standard analog joystick in either CoCo port, or a combination. **Right** is the default joystick port. One fire button is enough for all essential actions. A second button adds a convenient hard drop. In an emulator, assign the host controller to the intended CoCo port; a USB controller's physical connector is not itself a CoCo joystick-port selection.
|
||||
|
||||
@@ -51,13 +56,13 @@ LOADM"QUAD.BIN"
|
||||
EXEC
|
||||
```
|
||||
|
||||
Changing a mounted disk does not replace the program already in RAM. When testing a new build, return to a clean Disk BASIC start and load it again. In an emulator, confirm the newly loaded program as well as the mounted filename. Follow the emulator's normal restart and unsaved-media safeguards.
|
||||
When changing game disks, return to Disk BASIC and load the chosen disk with `DOS`. Mounting a different disk leaves the previous program in memory until you load again. In an emulator, use its normal restart and unsaved-media safeguards.
|
||||
|
||||
### The title screen
|
||||
|
||||

|
||||
|
||||
The title is drawn from the game's own lettering and block shapes. It is the main navigation point:
|
||||
The title screen is the main navigation point:
|
||||
|
||||
| Choice | What it does |
|
||||
| --- | --- |
|
||||
@@ -96,11 +101,11 @@ The game has four rotation states for each type. Some shapes are symmetric: an O
|
||||
|
||||
A sideways press moves one column immediately. If held, movement repeats after about 200 ms, then about every 40 ms. If opposite directions are held together, the first held direction stays in control until released.
|
||||
|
||||
Rotation tries the requested orientation, with small horizontal adjustments near a wall or stack. If none fits, the piece stays in its previous position. This edition does not use modern spin bonuses or the modern SRS rotation system. An attempted move that cannot fit does not push settled blocks out of the way.
|
||||
Rotation tries the requested orientation, with small horizontal adjustments near a wall or stack. If none fits, the piece stays in its previous position. Settled blocks stay fixed while you position the falling piece. See [Modern and Classic scoring](#modern-and-classic-scoring) for the awards earned by clearing rows.
|
||||
|
||||
Normal gravity moves the piece downward at the current level's pace. When a gravity step cannot move it down, the piece locks. There is no additional modern lock-delay mechanic. A hard drop goes directly to the lowest valid position and locks immediately; a soft drop increases the downward pace while held.
|
||||
Normal gravity moves the piece downward at the current level's pace. When a gravity step cannot move it down, the piece locks immediately. A hard drop goes directly to the lowest valid position and locks immediately; a soft drop increases the downward pace while held.
|
||||
|
||||
A game ends if the next piece cannot spawn, or if locking would leave occupied squares above the board. This protects the board boundaries as well as defining the end of play.
|
||||
A game ends if the next piece cannot spawn, or if locking would leave occupied squares above the board. Keep the stack below the spawning area to stay in play.
|
||||
|
||||
### Next, Hold, and landing shadow
|
||||
|
||||
@@ -175,13 +180,13 @@ Let the stick return to its physical center before starting. If the piece drifts
|
||||
|
||||
The game uses a center dead zone and hysteresis so small changes around neutral do not cause rapid direction changes. Up-drop is rearmed by returning the vertical axis to neutral. On diagonals, the dominant axis helps prevent a sideways gesture from accidentally triggering an Up hard drop.
|
||||
|
||||
In VCC Plus, configure the controller's host mapping as well as the game's port. Ensure the primary and secondary physical buttons are assigned to the emulator's Fire 1 and Fire 2. A two-button game mapping cannot create a secondary switch on a physical one-button CoCo joystick.
|
||||
In VCC Plus, configure the controller's host mapping as well as the game's port. Ensure the primary and secondary physical buttons are assigned to the emulator's Fire 1 and Fire 2. Secondary fire requires a controller with a second independent button; one-button controllers use joystick Up for hard drop.
|
||||
|
||||
### Controls and readings screen
|
||||
|
||||

|
||||
|
||||
**RIGHT XY** and **LEFT XY** are sampled axis values in the game's 0–63 range. The center is normally around 31. **BUTTONS** is the raw button bitmask; 15 is the usual fully released value. This screen displays readings sampled when it is drawn; it is not a continuously animated controller diagnostic. Reopen it for a fresh sample.
|
||||
**RIGHT XY** and **LEFT XY** show axis readings in the game's 0–63 range. The center is normally around 31. **BUTTONS** is the button bitmask; 15 is the usual fully released value. Each time you open Controls, the screen takes a fresh set of readings. Reopen it after moving or centering the stick to compare values.
|
||||
|
||||
## Pause, actions, and confirmations
|
||||
|
||||
@@ -220,7 +225,7 @@ Choose an item with `↑` / `↓` or the stick. Use `←` / `→` to change it;
|
||||
| **STYLE** | Plain, Modern, Clean. Changes block edging without changing rules. | Immediately. |
|
||||
| **GRID** | On/Off. Adds visible cell outlines. | Immediately. |
|
||||
| **LANDING SHADOW** | On/Off. Shows the current piece's hard-drop destination. | Immediately. |
|
||||
| **SOUND** | On/Off. Enables short event effects. There is no required continuous background music. | Immediately. |
|
||||
| **SOUND** | On/Off. Enables short event effects, with silence between actions. | Immediately. |
|
||||
| **PREFERRED ROTATION** | CCW or CW. Sets keyboard Up/W and primary-fire tap direction. | Immediately. |
|
||||
| **DIFFICULT PIECES** | On/Off. Uses an adversarial, Bastet-inspired selector instead of ordinary weighted balancing. | Next game; also chooses a separate score category. |
|
||||
| **CUSTOM SEED** | On/Off. Uses the stored repeatable CoCo seed instead of a timer-based starting seed. | Next game. |
|
||||
@@ -258,7 +263,7 @@ Normal selection uses weighted balancing, not a seven-piece bag. Pieces that hav
|
||||
|
||||
Difficult Pieces evaluates which types offer poor placements on the settled board and usually chooses one of the less helpful results, with a small randomized element. It can also choose a starting rotation. It is intended to be harder, and its records are separated from Normal selection. It does not alter the two scoring formulas.
|
||||
|
||||
A Custom Seed reproduces the CoCo initial board and piece-selection stream when the same relevant starting options and actions are used. Use the same difficulty and Difficult Pieces choice when comparing runs. Hold changes when the preview is consumed, and Difficult Pieces depends on the board you build, so identical seed text alone does not promise identical later play after different decisions. The CoCo generator is not required to match Linux or Mac random streams.
|
||||
A Custom Seed reproduces the CoCo initial board and piece-selection stream when the same relevant starting options and actions are used. Use the same difficulty and Difficult Pieces choice when comparing runs. Hold changes when the preview is consumed, and Difficult Pieces depends on the board you build, so identical seed text alone does not promise identical later play after different decisions. Seeds identify repeatable challenges within the CoCo edition.
|
||||
|
||||

|
||||
|
||||
@@ -412,7 +417,7 @@ Letter entry uses A–Z. Type one letter and let the selected field advance and
|
||||
|
||||

|
||||
|
||||
The saved example is an earned result from the disposable capture session. It is demonstration data, not a record installed on your personal disk or included in the pristine build-05 delivery.
|
||||
A saved entry shows its initials, score, and M/C scoring-rule marker in the chosen category. New game disks begin with empty boards for your own records.
|
||||
|
||||
### Changing scoring rules safely
|
||||
|
||||
@@ -428,7 +433,7 @@ Changing **SCORING RULES** opens a separate decision screen:
|
||||
|
||||
Erasing scores is a deliberate database action, not a requirement for changing the scoring preference. If you erase while a game is active, that game can continue, but its result is made ineligible for later high-score saving. Start a new game to compete under the new rule. Back up the disk before using Erase if you might want the old boards again.
|
||||
|
||||
There is no automatic migration from the Linux or Mac scoreboard. Records on a different game disk are also separate unless an explicit, supported migration is performed.
|
||||
Each game disk keeps its own CoCo high-score records. Back up that disk to preserve them when moving to another machine or disk-image setup.
|
||||
|
||||
## Game over and starting again
|
||||
|
||||
@@ -459,15 +464,13 @@ A read-only or failing disk can allow play while preventing new settings/records
|
||||
|
||||
## Troubleshooting and common questions
|
||||
|
||||
### I mounted build 05, but the behavior looks like an older build
|
||||
### Loading the intended game disk
|
||||
|
||||
The disk filename identifies the mounted media, not the code already in memory. Return through the normal emulator/BASIC safeguards and actually load the intended disk with DOS. Avoid running an old in-memory game against a newly mounted disk's resources.
|
||||
Return to Disk BASIC, mount the intended disk, and enter `DOS`. Keep the same game disk mounted while playing so the program can read its screen text and save settings and scores to the correct place.
|
||||
|
||||
### The joystick will not move left, drifts, or stops working after a menu
|
||||
### Joystick response and drift
|
||||
|
||||
Check that the game's Joystick setting matches the physical CoCo port. Center the stick and use Calibrate Neutral if needed. In an emulator, check the host controller assignment, dead zone, and Fire 1/2 mapping too. Release controls after a screen change. Keyboard menu selection is supported and should not disable the joystick in build 05. Select Joystick Off temporarily to distinguish a controller issue from a keyboard/game issue.
|
||||
|
||||
Build 05 includes the earlier input correction as well as secondary-button hard drop. Its emulator checks use actual standard port/axis/button snapshots. Those checks do not substitute for testing your physical controller and real CoCo.
|
||||
Check that the game's Joystick setting matches the physical CoCo port. Center the stick and use Calibrate Neutral if needed. In an emulator, check the host controller assignment, dead zone, and Fire 1/2 mapping too. Release controls after a screen change. You can use the keyboard for menus and continue playing with the selected joystick. Select Joystick Off temporarily to distinguish a controller issue from a keyboard/game issue.
|
||||
|
||||
### Fire seems to rotate late, or holding it opens a menu
|
||||
|
||||
@@ -475,7 +478,7 @@ The primary-button short action happens on **release**, so the game can distingu
|
||||
|
||||
### A piece only has two visible orientations
|
||||
|
||||
I, S, and Z are symmetric in two of their four table states, and O remains square. Test a T, L, or J if you want to see four visibly different turns. A successful primary tap should leave the piece rotated after release; it should not cancel a preceding turn.
|
||||
I, S, and Z are symmetric in two of their four table states, and O remains square. Rotate a T, L, or J to see four visibly different turns. A successful primary tap should leave the piece rotated after release; it should not cancel a preceding turn.
|
||||
|
||||
### My score seems unexpectedly large
|
||||
|
||||
@@ -489,13 +492,9 @@ The destination is the game's starting difficulty plus Normal/Difficult Pieces s
|
||||
|
||||
No. Choose Keep High Scores to retain them. Their M/C markers remain intact, and ranking uses their unconverted numbers. Erase All High Scores is optional and affects every category.
|
||||
|
||||
### Can I use 512 KB for a sharper edition?
|
||||
|
||||
The current game uses the same 320 × 192, 16-color presentation on its supported CoCo 3 configuration. Extra RAM does not select a separate resolution or font. Modern borders and the readable font are already part of the baseline edition.
|
||||
|
||||
### There is a continuous buzz
|
||||
|
||||
The intended audio consists of brief event effects, with silence between them. There is no continuous soundtrack requirement. Try Sound Off and note whether the noise occurs on the title, during play, or only after an action. Brian reported a normal-emulator buzz that was absent on his real CoCo 3; isolated captured audio has been quiet between effects. That does not establish a fix for every normal-window setup. Preserve the machine/controller/audio configuration when reporting it rather than assuming the game should hum continuously.
|
||||
Game audio consists of brief effects for movement, rotation, landing, row clears, and game over, with silence between events. If you hear a continuous buzz, try **SOUND OFF**. If the noise continues, check the emulator or machine's audio output and controller configuration. When asking for help, include the machine or emulator, audio settings, controller assignment, and whether the noise begins at the title or during play.
|
||||
|
||||
## Screen directory
|
||||
|
||||
@@ -517,24 +516,18 @@ The intended audio consists of brief event effects, with silence between them. T
|
||||
|
||||
## Copyright, license, and credits
|
||||
|
||||
**Manual: © Brian K. Holman 2026.** This Markdown manual and its authored documentation material are provided under **GNU GPL version 3 or later**, alongside the CoCo project. Third-party notices remain in force for their respective contributions. The real screenshots show the independently written CoCo game; reference images from the Mac application are not used as emulator evidence.
|
||||
**© Brian K. Holman 2026.** Quadrapassel for CoCo and this manual are provided under the **GNU General Public License, version 3 or later**. Third-party copyrights and license notices remain in force for their respective contributions.
|
||||
|
||||
The CoCo title screen retains its in-game notice, **(c) 2026 Brian Holman**. The manual's author/copyright wording above is intentionally its own notice.
|
||||
The game's title-screen copyright notice is **(c) 2026 Brian Holman**.
|
||||
|
||||

|
||||
|
||||
The game acknowledges GNOME Quadrapassel and the contributors **J. Marcin Gorycki, Lubomir Rintel, Robert Ancell, John Ward, and Will Warner**, together with **Brian Holman — Mac & CoCo**. The difficult-piece algorithm is inspired by **Federico Poloni's Bastet**. Those credits recognize the behavioral lineage; they do not mean Linux/Mac application code is incorporated into this CoCo implementation.
|
||||
|
||||
**Pierre Sarrazin** is credited for the font, CMOC, and supporting libraries. The menu/HUD font uses an unchanged subset of his public-domain CardGame font, also used by Color8; its original notice and source files are retained in the project. Standard CMOC/CardGame/bsound/decbfile APIs and the supplied DOS-loader template have their own component notices. The project preserves these rather than labelling every component with one blanket license. No third-party sound recordings, Mac binaries, private ROMs, or emulator source are part of this manual.
|
||||
**Pierre Sarrazin** is credited for the font, CMOC, and supporting libraries. The menu/HUD font uses an unchanged subset of his public-domain CardGame font, also used by Color8; its original notice and source files are retained in the project. Standard CMOC/CardGame/bsound/decbfile APIs and the supplied DOS-loader template have their own component notices. The project preserves these rather than labelling every component with one blanket license.
|
||||
|
||||
The game's GPL license permits redistribution and modification under its stated terms and provides the full warranty disclaimer. Keep the license and relevant notices with source distributions. See the project's **COPYING** file for the complete license and the [GNU GPL version 3 text](https://www.gnu.org/licenses/gpl-3.0.html) for an online copy. This manual is a user guide, not a replacement for that license text.
|
||||
|
||||
### Edition and screenshot record
|
||||
### Edition
|
||||
|
||||
This edition documents **game disk build 05**. All 17 screenshots are unmodified
|
||||
captures of that CoCo program in VCC Plus 3.6.1 (54), MC6809 / 512 KB. The
|
||||
project’s screenshot manifest retains the source, disk, capture, and image
|
||||
identities. Changed preferences and the earned AAA / 40-point demonstration
|
||||
record belong only to the disposable capture disk; personal records were left
|
||||
alone. These captures do not qualify CoCo 2, actual 128 KB operation, or every
|
||||
physical-controller setup.
|
||||
Player’s manual for **Quadrapassel for CoCo, game disk build 05** (`QUADPSL05.DSK`). For Color Computer 3 systems with **128 KB or more**, Disk BASIC, and writable game media. Keyboard and standard analog joystick controls are supported.
|
||||
Reference in new issue
Block a user