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