Prepare public CoCo 3 documentation and portable VCC Plus workflow

This commit is contained in:
Brian Holman committed 2026-11-11 16:43:19 -07:00
1 parent e9574b6f0d
commit 4aa739780c
16 files changed
+572 -913

No files matched your search

+114 -121
View File
@@ -1,102 +1,55 @@
# Quadrapassel for CoCo
A CoCo 3 implementation of Quadrapassel in C,
using CMOC and the installed VCC Plus development tools.
Build this candidate with the **Release** configuration.
A falling-block game for the **Color Computer 3 with 128 KB or more**, written
in C using CMOC and the VCC Plus development tools. Play with the keyboard or a
standard analog joystick, choose Modern or Classic (40.2) scoring, and save your
high scores to disk.
**Status: CoCo 3 implementation in progress. A playable stage has run in official
VCC Plus 3.6.0 (51), with earlier gameplay/persistence checks on 3.5.5 (48). Persistent high scores/settings have saved and reloaded after cold boot on the
official 512 KB MC6809 playtest. Brian also reported successful play on a physical
512 KB CoCo 3 on November 11, 2026. A clean game disk is available; actual
128 KB qualification is pending.**
- **[Download the game disk - QUADPSL05.DSK](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel/raw/commit/49bc78158a5e17ba717381a3a2cbb4ab35c36dfe/QUADPSL05.DSK)**
- **[Read the illustrated player's manual and download its PDF](https://vccplus.brianholman.com/games/quadrapassel/)**
- **[Browse or clone the public source repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel)**
| Target | Experience |
The disk link identifies the exact build-05 delivery. The repository also contains
its [Markdown manual and real emulator screenshots](docs/manual/QUADRAPASSEL.md).
## Play
1. Keep the downloaded original and make a writable copy for playing.
2. Insert or mount that copy in drive 0 of a CoCo 3 with Disk BASIC.
3. Type `DOS` and press Enter. Wait for loading and score reading to finish.
4. Choose **START** at the title.
The game has been verified in **128 KB CoCo 3 emulation** and played successfully
on a **physical 512 KB CoCo 3**. The presentation is 320 × 192 with 16 palette
colors, including seven distinct piece colors. More RAM does not select a
separate game edition or resolution.
| Input | Action |
| --- | --- |
| CoCo 3, 128 KB | Primary target: complete game, seven distinct piece colors, keyboard and joystick |
| CoCo 2, 64 KB | Future adaptation; not included in this candidate |
| CoCo 3, 512 KB or more | Runs the baseline game; enhancements only when they offer a measured benefit |
| Left/Right or A/D | Move sideways; hold to repeat |
| Down or S | Soft drop |
| Up or W | Rotate in the preferred direction |
| Q / E | Counterclockwise / clockwise rotation |
| Space | Hard drop |
| H | Hold or swap the piece |
| P or BREAK | Pause and open Actions |
| Enter | Select a menu choice |
| Joystick left/right, down | Move sideways, soft drop |
| Joystick up or secondary fire | Hard drop once per press/neutral cycle |
| Primary fire tap/release | Rotate once on release |
| Primary fire held about 400 ms | Open Actions, including Hold and Settings |
Deliveries use `QUADPSLxx.DSK`, with a two-digit build number and a convenient
DOS launcher and a documented manual launch path. RAM sizes above are **KB**.
The default joystick port is Right; Settings also offers Left and Off. Keyboard
menu selection does not disable the selected joystick. The manual explains menu
controls, initials entry, calibration and the differences between keyboard Up
and joystick Up.
## Player’s manual
High scores and settings are saved in `QPSAVE0.DAT` and `QPSAVE1.DAT` on your
playing disk. Each new numbered delivery begins with empty scores and default
settings. Preserve older score disks; a new disk does not import their records.
Let saves finish before resetting, ejecting or copying the disk.
Read the detailed [online manual](https://vccplus.brianholman.com/games/quadrapassel/)
for every screen, keyboard and joystick controls, both scoring rules and all 34
scoreboards. Its shared VCC Plus reading edition includes a reviewed PDF download.
The authoritative [Markdown and screenshot source](docs/manual/QUADRAPASSEL.md)
includes 17 actual emulator captures; [reproduction steps](docs/manual/README.md)
use the common VCC Plus documentation process.
## Start here
- [START_HERE.md](START_HERE.md): prompt for a separate chat within the existing VCC Plus project.
- [SPECIFICATION.md](SPECIFICATION.md): self-contained game behavior and acceptance requirements.
- [AGENTS.md](AGENTS.md): development boundaries and required exception review.
- [VCC Plus workflow](docs/VCC_PLUS_WORKFLOW.md): approved official build 51, MCP, manuals, API and archive access, and testing.
- [Implementation stages](docs/IMPLEMENTATION_PLAN.md): deliverables and verification checkpoints.
- [Provenance](docs/PROVENANCE.md): source revision, credits, licenses and reference data.
Use standard CMOC APIs first. Brian approved a narrowly scoped C graphics
exception; its exact scope and measured evidence are in [DECISIONS.md](docs/DECISIONS.md).
Other low-level exceptions still require review before implementation.
VCC Plus internals remain outside scope. The supplied specification is the
behavioral reference, with Brian's explicit read-only exception for checking
the Mac port's scoring source recorded in AGENTS.md.
## Current development checks
The current priority is the complete CoCo 3 game with 128 KB support. CoCo 2 work
will follow after that version is working and tested. See the
[implementation status](docs/IMPLEMENTATION_STATUS.md),
[MCP setup](docs/MCP_SETUP.md), and [memory layout](docs/MEMORY_LAYOUT.md).
Host complements to the official-app build/playtest workflow:
```sh
python3 tools/test_rules.py
python3 tools/test_components.py
python3 tools/test_video.py
```
Keyboard: arrows or A/D move, Down/S soft drop, Up/W preferred rotation, Q/E
counterclockwise/clockwise, Space hard drop, H hold, P pause, Enter select, BREAK
back/pause. The title also accepts Space. A short joystick fire press rotates on
release; holding fire for 400 ms opens actions, including Hold and Settings.
Joystick Up or the secondary button hard-drops like Space. The secondary button
drops once on press; release it before another drop. Down remains soft drop.
High scores are designed to reload from `QPSAVE0.DAT`/`QPSAVE1.DAT` on the game
disk. The two-slot store covers all difficulty/normal-or-difficult categories and
reports write failures. Guest save/reload has passed on official build 48 / MC6809 / 512 KB. See the
[128 KB manual check](docs/TESTING_128K.md) for the remaining target validation.
## Credits and license
Based on [GNOME Quadrapassel](https://gitlab.gnome.org/GNOME/quadrapassel) and
[Brian Holman's macOS port](https://github.com/bkholman/quadrapassel-macos).
Preserve the original authors and component notices listed in
[PROVENANCE.md](docs/PROVENANCE.md).
Specification text and derived piece/reference data are provided under
**GPL-3.0-or-later**; see [COPYING](COPYING). The supplied title image is a design
reference with a separate notice in the provenance document. No Mac application,
ROM, emulator implementation, or third-party sound payload is included.
## Run the current CoCo 3 disk
Mount a writable copy of [QUADPSL05.DSK](QUADPSL05.DSK) in drive 0 and type
`DOS`. Keep the downloaded original pristine. The current build targets the
CoCo 3; CoCo 2 adaptation is deferred. Allow disk loading and explicit saves to
finish before the next action. High scores/settings use QPSAVE0.DAT and
QPSAVE1.DAT; QPTEXT.DAT contains read-only menu text.
Each numbered build starts with empty high scores and default preferences.
Existing personal score disks remain untouched; scores are not copied into the
new build. The current delivery is **build 05**; the next changed delivery will
be build 06. See [build records](docs/BUILDS.md). The official recipe still uses
Quadrapassel.DSK as its clean staging artifact.
The separately verified manual fallback on the 512 KB test machine is:
The manual loading alternative from Disk BASIC is:
```basic
PCLEAR1
@@ -104,38 +57,78 @@ LOADM"QUAD.BIN"
EXEC
```
Audio is explicitly muted between brief effects, including during analog
joystick sampling, using standard CMOC library calls. See
[audio validation](docs/AUDIO_VALIDATION.md) for direct MCP capture results and
the remaining actual-application retest.
## Build with the downloaded VCC Plus app
## November 11 visual update
Get the public [VCC Plus for Mac](https://vccplus.brianholman.com/downloads/)
release and the complete repository files. The installed app supplies CMOC,
Make, Perl and the disk tools needed by this project; no Homebrew installation
is required for the app's build workflow.
The menu and HUD now use Pierre Sarrazin's public-domain CardGame font, with
attribution and original source retained. Modern blocks have dark gray outlines
(RGB 1,1,1); the background remains black. The title credit is
`(c) 2026 Brian Holman` (rendered in the font's uppercase character set).
The font/border pixel fixtures and enforced memory bounds pass. Current official
app qualification and disk identities are recorded in [the latest update](docs/TITLE_AND_SCORING_UPDATE.md).
1. Open **Develop → C Development…** in VCC Plus and open this existing project
folder, containing `main.c`, `Makefile` and `vccplus-project.json`.
2. Keep the supplied project settings and Makefile. Select **Release**.
3. Choose **Build Disk**. Read the build result and memory-bound check.
4. Use **Show Build Products** to locate that build's `Quadrapassel.DSK` and
`QUAD.bin`. The app builds in its own work area.
5. Use **Launch Disk** only when you are ready to replace the guest program;
save existing guest work and attend to media/restart prompts first.
Settings names the scoring choices **Modern** and **Classic (40.2)**. Switching
changes the next game and defaults to keeping existing high scores. Both
formulas match the supplied Mac source. The reported normal-window buzz remains
unconfirmed fixed; isolated audio is quiet between effects.
Release is required for the delivered memory layout. Do not increase linker
limits or reduce the stack reserve to make another configuration fit. A fresh
anonymous checkout has reproduced the delivered build using the public VCC Plus
3.6.1 bundled Release toolchain. See the [build workflow](docs/VCC_PLUS_WORKFLOW.md)
for native building, ChatGPT connections and validation.
Build 04 corrects a bundled CMOC optimizer error that supplied the wrong
horizontal calibration byte, causing constant right movement. It also includes
stable button sampling and preserves joystick readiness across keyboard-confirmed
scene changes. Native right-port emulated joystick checks pass for left/right,
four lasting T-piece turns, and steering after keyboard pause/resume. Actual
physical controller/CoCo and left-port retests remain pending. CoCoMan was a
read-only reference; its assembly and VCC-specific APIs were not imported.
See [the target diagnosis](docs/CMOC_JOYSTICK_ARGUMENTS.md) and
[joystick validation](docs/JOYSTICK_FIX.md).
If you prefer the command line, use the toolchain from the installed app. With
VCC Plus in the standard Applications folder, run from a complete checkout:
Build 05 adds Fire 2 hard drop once per press, retaining joystick Up and Fire 1.
Official VCC Plus 3.6.1 (54) Release and actual standard right-port joystick
snapshots pass press/hold/release/repress, steering, lasting rotation and steering
after keyboard pause/resume. Host adapter checks cover both ports. See
[secondary-button validation and acceptance steps](docs/SECONDARY_BUTTON.md).
Physical controller/CoCo, left-port guest and 128 KB qualification remain pending.
```sh
git clone https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel.git
cd Quadrapassel
env PATH="/Applications/VCC Plus.app/Contents/Resources/Toolchain/bin:/usr/bin:/bin" make
```
The Makefile defaults to Release and builds `Quadrapassel.DSK`. An explicit
`make VCC_CONFIGURATION=Release disk` selects the same configuration/action.
The native workspace should still be set to **Release** when building there.
For optional host-side rule, input, persistence and rendering regressions:
```sh
python3 tools/test_rules.py
python3 tools/test_components.py
python3 tools/test_video.py
```
Those developer checks require Python and a suitable host C compiler; they are
separate from building or playing through the installed app.
## Develop with ChatGPT
[Start here](START_HERE.md) provides a portable prompt for an existing checkout.
The [MCP setup guide](docs/MCP_SETUP.md) explains scoped C-project access,
installed manual searches and the separate Archive Library connection. Discover
and verify the tools exposed by your installed app rather than copying an old
project ID or connection file.
Read [AGENTS.md](AGENTS.md), the [behavioral specification](SPECIFICATION.md),
[provenance](docs/PROVENANCE.md) and [memory contract](docs/MEMORY_LAYOUT.md)
before changing the implementation. Dated investigation/build records preserve
their original observations; the current manual and these entry guides describe
the supported product and workflow.
## Independent implementation, credits and license
This clean-room CoCo implementation was written anew in C from a behavioral
specification to be functionally similar to Quadrapassel for Linux and Mac.
No Linux or Mac application source code is incorporated into the CoCo game.
The name was retained for branding continuity. The specification and reference
piece/scoring data preserve their GPL provenance and contributor credits.
Game source and documentation are **GNU GPL version 3 or later**; see [COPYING](COPYING)
and [PROVENANCE.md](docs/PROVENANCE.md). GNOME Quadrapassel's original contributors,
Brian Holman's Mac and CoCo work, Federico Poloni's Bastet algorithm, and Pierre
Sarrazin's font and CMOC libraries are acknowledged. Individual third-party
components retain their own notices; the CardGame font subset is public domain.
**© Brian K. Holman 2026.**