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

+10 -22
View File
@@ -1,21 +1,20 @@
# Quadrapassel for CoCo — implementation specification
Revision: November 10, 2026. This is an implementation contract, not a claim that
the CoCo game is already built. The Mac source was reviewed to prepare this
document; the implementation chat uses this document without access to that source.
Current CoCo 3 behavioral specification. The independent C implementation uses
this specification as its functional reference. The specification was prepared
from behavioral analysis; Linux/Mac application source is not incorporated.
Provenance and the exact reference revision are in [docs/PROVENANCE.md](docs/PROVENANCE.md).
## 1. Product requirements and priorities
Build a responsive falling-block game for a stock 6809 CoCo, predominantly in C
using standard CMOC APIs. Develop and test with **official VCC Plus 3.5.5 (48)**
installed in `/Applications`. No custom emulator build or MCP integration.
using standard CMOC APIs. Develop and test with the stock downloaded **VCC Plus** and its supported
CMOC toolchain, published APIs and MCP connections.
| Priority | Requirement |
| --- | --- |
| Primary | CoCo 3 with 128 KB: full rules, seven distinct piece colors, keyboard and joystick |
| Compatibility | CoCo 2 with 64 KB: same rules and controls, accepted color/detail reduction |
| Optional | CoCo 3 with 512 KB or more: baseline works; enhancements only for a demonstrated benefit |
| Expanded RAM | CoCo 3 with 512 KB or more: same complete baseline game |
Use one standard floppy image. Prefer one shared rules engine and, where practical,
one executable. Separate display-specific executables on the same disk are allowed
@@ -272,16 +271,9 @@ CoCo 3: begin with standard CMOC `hscreen(2)` / `hset()` and palette APIs for th
redrawing the entire screen unnecessarily. Measure before proposing a different
drawing method. Preserve BASIC graphics workspace and return to text cleanly.
CoCo 2: begin with standard `pmode(3, buffer)`, `pcls()` and `screen()` plus
documented CMOC graphics-library operations. PMODE 3 is 128 by 192 with four
colors and a 6,144-byte framebuffer. Distinguish pieces by patterns/outlines as
well as the available colors; all seven logical piece types remain intact.
Do not rely on artifact colors or a 6847T1-only feature for basic readability.
Offer Plain (flat), Modern (dark outlines, default), and Clean (light edging)
styles as low-cost approximations. Grid outlines default off. Avoid allocating
separate full-screen bitmaps per theme. CoCo 2 may reduce decorative details,
but that must be disclosed, not presented as seven-color output.
separate full-screen bitmaps per theme.
### Sound
@@ -364,10 +356,7 @@ used/free granules; an initial program/assets target below 128 KiB is a planning
budget, not a claim of available capacity. No second disk is required to play.
Use the installed VCC Plus disk-project workflow and documented DOS-launch option.
Autodetect CoCo 2 vs CoCo 3 with a documented standard CMOC mechanism when possible;
do not perform a destructive RAM probe. Provide a boot-time manual display/target
choice if safe detection is unavailable. Optional 512 KB enhancements may require
manual selection; baseline operation must be safe without probing expanded RAM.
Baseline operation must be safe on 128 KB without probing expanded RAM.
If boot glue would require writing custom assembly or raw hardware code, request
review first; use the existing supported loader when sufficient.
@@ -396,9 +385,8 @@ Do not publish placeholder loading commands as tested instructions.
after the relevant edge (button rotation uses its release edge). Report p95 and
worst values, separately for ordinary play, clears, sound and Difficult Pieces.
A missed target prompts analysis/review, not unauthorized assembly.
8. Configuration: separate evidence for CoCo 3 128 KB; baseline on 512 KB; 64 KB
CoCo 2 in XRoar/hardware; PAL/NTSC timing if both claimed. A CoCo 3 compatibility
run of the CoCo 2 executable is labeled accordingly. Brian may supply XRoar evidence.
8. Configuration: separate evidence for CoCo 3 128 KB and 512 KB; physical
hardware and emulator checks are distinct. Test PAL/NTSC timing if both claimed.
9. Delivery: top-level built `Quadrapassel.DSK`; source/build recipe; actual guest-only
title and gameplay PNGs; concise run instructions, controls and credits; recorded
revision/build/configuration, disk hash, memory budget, and test matrix.