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

+4 -6
View File
@@ -2,9 +2,7 @@
## November 10, 2026 — C graphics exception
Brian's explicit decision, relayed by the coordinating chat **Deploy VCC Plus
Gitea** (`01a1c3a8-8bde-77f0-b8af-d0d29b874c7c`): **“Approve the C graphics
exception.”** The approved wording was:
The project owner approved the following limited implementation scope:
> C code for screen-memory mapping and drawing changed regions, using CMOC/BGraph
> where practical, with no assembly or emulator changes and explicit 128 KB validation.
@@ -18,9 +16,9 @@ Retain the public-API fallback and compare measured drawing and visible input.
This approval does **not** authorize hand-written assembly, custom sound/input/
interrupt drivers, emulator source access or changes, custom app builds, or a
replacement MCP integration. Official VCC Plus 3.5.5 (48) and reference boundaries
remain required. Further exceptions need review. Actual 128 KB testing remains
separate from the 512 KB MCP worker; Brian offered to perform that manual check.
replacement MCP integration. Use stock VCC Plus and the public reference boundaries in AGENTS.md. New
exceptions require review by the owner of the working fork. The 128 KB baseline
has since been verified; changes affecting memory require fresh target checks.
### Evidence prompting review
+34 -72
View File
@@ -1,82 +1,44 @@
# Implementation stages and review checkpoints
# Development and review checklist
Status at handoff: **planning documents only**. No game probe, executable or disk
has been built, and no CoCo compatibility check has passed yet. The implementation
prompt is for a separate VCC Plus project chat using ChatGPT-6.1 Sol with High
reasoning, after Brian reviews the prompt.
The CoCo 3 game is implemented. This document is a checklist for modifications,
not a product roadmap. Start with [README](../README.md), [AGENTS](../AGENTS.md),
the [behavioral specification](../SPECIFICATION.md), and the
[current status](IMPLEMENTATION_STATUS.md).
## Stage 1 — establish the supported API path
## Establish the baseline
- Verify official 3.5.5 build 48 and the correct Quadrapassel MCP connection.
- Read manuals/API/archive material through the advertised tools; record access.
- Create a minimal standard CMOC project in this repo and reproduce its disk build.
- Prove seven-color graphics, text, moving/erased blocks, keyboard, both joystick
ports, timing, short sound, disk access and return to text using standard APIs.
- Run on actual 128 KB configuration; measure draw time and input response.
- Produce an initial linked memory budget and capture the actual guest display.
- Build an unchanged checkout with stock VCC Plus using Release and the project Makefile.
- Keep a writable test disk separate from existing personal score disks.
- Read the installed CMOC/API manuals and discover the selected project's live MCP capabilities.
- Record the source revision, configuration, artifact hash and actual guest machine/RAM.
This stage decides whether standard APIs satisfy the target. It does not presume
custom graphics code. If an API gap or measured cost requires an exception,
request the review described below before implementing it.
## Make a focused change
## Stage 2 — playable shared rules engine
Keep game rules separate from display, input and disk adapters. Prefer standard
CMOC APIs. The existing bounded C graphics exception is documented in
[DECISIONS](DECISIONS.md); it does not justify unrelated low-level changes.
For a new exception, explain the player-visible need, standard API evidence,
alternatives, affected files, memory effects and validation to the fork's owner
before implementing it.
Implement the 10 by 20 board, exact piece definitions, spawn/collision, rotation
and kicks, gravity and controls, simultaneous clears, scoring and levels, next,
hold, shadow and game over. Use small deterministic fixtures from this repo.
Add normal weighted selection, seed repeatability and the optional difficult-piece
mode. Test invalid states and score widths appropriate to CMOC.
## Validate affected behavior
Keep rules independent of rendering and input sampling so CoCo 2 and CoCo 3 share
them. Host tests may complement guest tests; they do not replace a real CMOC build.
- Rules: spawn/collision, all rotation states, kicks, rejected moves, gravity, drops, clears, hold and shadow.
- Scoring: both formulas, resulting-level multiplication, bottom clears, score width and category identity.
- Selection: repeatable seeds, weighted selection and difficult-piece simulation without state corruption.
- Input: repeat timing, shared keyboard/button lines, both ports, calibration, pause/release and menu guards.
- Storage: save/reload, read-only/corrupt/partial data, recovery, reset/cancel and active-game eligibility.
- Display/audio: readable text, all screens, changed-region rendering and quiet intervals between effects.
- Memory: enforced code/data bounds, stack reserve, BASIC workspace and safe disk I/O.
## Stage 3 — complete player experience
Host tests complement actual guest play. Check 128 KB operation when a change
affects memory. A keyboard check does not establish joystick behavior; a 512 KB
run does not establish a new build's 128 KB behavior. Report unavailable checks
honestly and preserve useful fixtures and unmodified guest screenshots.
Add the title treatment, menus, all-keyboard and all-joystick operation, settings,
styles, sound, credits, and bounded persistent scores with the reset semantics
in the specification. Test sound-enabled latency, pause transitions, read-only
media and recoverable writes. Refine within standard APIs before considering
approved low-level alternatives.
## Deliver a variant
## Stage 4 — CoCo 2 and single-disk packaging
Add the lower-color display using standard APIs with patterns/clear outlines.
Keep all game rules and essential controls. Package the supported launcher and
both targets (if separate executables) on one disk. Verify DOS and manual boot,
safe machine selection, free disk space and score saving.
Provide the exact CoCo 2 test checklist to Brian for XRoar, preserving pending
status until results return. Verify baseline behavior on a 512 KB CoCo 3 too;
do not add an enhanced variant merely to fill a third tier.
## Stage 5 — acceptance and handoff
Run the specification's relevant acceptance cases with version/configuration
records. Add selected actual guest screenshots to `docs/screenshots/`, the built
disk at `Quadrapassel.DSK`, source/build settings, loading instructions, controls,
credits and a compatibility table. Record measured memory/disk use and timing.
Do not mark the project complete while required target checks remain pending.
Keep implementation commits/pushes within Brian's authorization. Initial planning
document publication does not authorize a public release or visibility change.
## Required exception proposal
Before any assembly or implementation outside standard CMOC APIs, send a concise
proposal to the coordinating chat **Deploy VCC Plus Gitea** for Brian and that chat
to review. This is a user-requested permission step, not a routine stage gate.
Use this structure:
1. **Need:** player-visible problem and affected target.
2. **Standard API evidence:** functions/configuration tried, reproducible check,
measurement or documented missing capability.
3. **Alternatives:** options that remain within standard APIs and their tradeoffs.
4. **Proposed exception:** exact routine/API/assembly, files, size and memory effects.
5. **Validation:** correctness, responsiveness, both target machines, restoration
of display/input/disk state, and fallback.
6. **Decision requested:** smallest useful approval scope.
Wait for an explicit decision from Brian or a decision relayed after their joint
review. Continue unaffected work. Record approvals in `docs/DECISIONS.md` when
there is an approved exception; do not create a fictional approval record.
Keep licensing and component notices, update the manual for changed controls or
rules, and document the build and loading commands. Number changed game deliveries
without overwriting old downloads or personal disks. Commit, push and publish only
within the fork owner's requested scope.
+34 -215
View File
@@ -1,224 +1,43 @@
# CoCo 3 implementation status — November 11, 2026
# Quadrapassel for CoCo — current status
The current disk contains a playable CoCo 3 game with standard CMOC sound,
settings and disk-backed high scores. Actual 128 KB qualification remains
pending; CoCo 2 adaptation is deferred at Brian's direction.
Build 05 is a complete CoCo 3 game for **128 KB or more**. It has been
successfully played on a physical 512 KB CoCo 3 and verified in VCC Plus
with 128 KB. Keyboard and joystick controls, two scoring systems, settings,
and disk-backed high scores are included.
## Current secondary-button addition — build 05
## Current delivery
QUADPSL05.DSK adds Fire 2 hard drop once per press; Up and Fire 1 remain.
Official installed VCC Plus 3.6.1 (54) Release and disposable MC6809/512 KB
standard right-port joystick tests pass held/released/repressed drops,
left/right, lasting rotation, Up drop and keyboard pause/resume then joystick
movement. Host adapter tests cover both ports; rules, persistence and video
checks pass. Code/const end $7AFE, static end $13FD, stack reserve1024.
Disk SHA-256:
`d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
Run stopped with its disk retained and zero writes; personal media unchanged.
Physical controller/CoCo, guest left port, this candidate's HD6309 and 128 KB
remain pending; normal-window buzz remains open. See SECONDARY_BUTTON.md.
- Disk: `QUADPSL05.DSK`, 161,280 bytes.
- SHA-256: `d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
- Binary SHA-256: `ed5460993770f80bd1560001892ef34d4845ddf9eafe40fc732d1033a9c84290`.
- Code/read-only data ends at $7AFE; static data ends at $13FD; stack reserve is 1,024 bytes.
- Fresh numbered disks contain no personal high-score database.
## Previous joystick correction — build 04
## Reproducible stock-toolchain build
QUADPSL04.DSK works around a demonstrated bundled CMOC -O2 calibration-argument
load error. Official native build53 Release and right-port emulated joystick
left/right, four lasting T turns and steering after keyboard resume pass.
Physical controller/CoCo, left port and 128 KB remain pending; buzz remains open.
Disk SHA-256:
`1cddb6bdf17857b915e96a6929e14181bad05cfae73278a4919add26fea0ba45`.
Code/const end $7AD4; static end $13FD; stack reserve 1024 bytes. Details:
[Target diagnosis](CMOC_JOYSTICK_ARGUMENTS.md).
On November 11, 2026, an anonymous HTTPS clone was built with the unmodified
VCC Plus 3.6.1 (53) toolchain from the official downloaded application. The
command was `make VCC_CONFIGURATION=Release disk`, with PATH restricted to the
application’s Toolchain/bin and macOS /usr/bin:/bin. No pre-existing objects,
generated assets, Homebrew tools, local connection files or other checkout
were used. The Makefile also defaults to Release: a second clean build with
plain `make` reproduced those same binary and disk hashes. Explicit Debug
configuration remains separate. The results match the delivery above.
## Withdrawn internal joystick candidate — build 03
## Validation scope
QUADPSL03.DSK adds stable before/after button sampling, a standard-CMOC
interrupt-protected input transaction, and preserved joystick readiness across
keyboard-confirmed scene transitions. Official build 53 Release and isolated
MC6809/512 KB keyboard smoke/audio checks pass. Actual joystick qualification
is recorded separately in JOYSTICK_FIX.md. Disk SHA-256:
`80c511fe9c9b1a0faaeffa688dec6d73de39280f8eb3c9ce584727fc396f09ca`.
Code/const end $7ACD; static end $13FD; stack reserve 1024 bytes.
The rules, input adapter, persistence, renderer and memory-bound checks have
passed. Native emulator right-port checks cover steering, lasting rotations,
Up and secondary-button hard drops, held/released/repressed buttons, and
joystick use after keyboard pause/resume. The user’s successful 128 KB emulator
and physical 512 KB runs establish those configurations; they are not a claim
that every controller, CPU upgrade or video standard has been exhaustively tested.
## Earlier joystick correction — build 02
The intended audio is brief event effects with quiet idle intervals. Isolated
audio captures are quiet between effects. A continuous buzz in a normal emulator
session remains a reported configuration-dependent issue; it was not present
on the tested physical CoCo. See [audio evidence](AUDIO_VALIDATION.md).
QUADPSL02.DSK fixes shared fire/keyboard input lines and arms joystick axes
independently. Both reported failure patterns were reproduced in host regressions
and pass after correction. Standard CMOC APIs are retained. Official VCC Plus
3.6.1 (53) Release build and MC6809/512 KB keyboard/gameplay smoke checks pass;
Brian subsequently confirmed actual joystick failure after loading it with DOS. Details, source references and final
identity: [JOYSTICK_FIX.md](JOYSTICK_FIX.md).
Clean disk SHA-256:
`4e3af2440a3195ee5864498e39a779362988257d8a39cfc1c413157ace287a3c`.
Code/constants end $7AF6, static data end $13F6; original stack/bounds retained.
The normal-window buzz remains open. Old personal score disks are untouched.
## Earlier numbered delivery
Brian requested `QUADPSLxx.DSK` with a two-digit build number and fresh high
scores. The first is **QUADPSL01.DSK**, byte-identical to the clean official
artifact below. No QPSAVE files are included; old personal score disks remain
untouched. That delivery is historical; the current build is recorded above. See [BUILDS.md](BUILDS.md).
## Current title, scoring-label and audio follow-up
The standard Release candidate now has an eight-pixel gap before the title
copyright, the credits entry `Brian Holman - Mac & Coco`, and explicit
**Scoring Rules: Modern / Classic (40.2)**. Keep high scores is the default;
no personal records were erased. Inspection of Brian's supplied Mac source
confirmed the existing scoring formulas, including the Classic 40.2 bottom-row
bonus. All 25 cases also pass through actual piece drops.
Official build 51, project revision 2, build
`DFDE8C57-3165-44B5-9027-E8B2F16DDF28`, artifact
`BB277DE8-07A2-437B-9998-FFD1FB2C36C5`, zero diagnostics.
Clean disk SHA-256:
`4ac171e87c51dfd99b302b9e035a91a59c030144e5ae0661a6d2dfc84ba3a63f`.
Code/constants end $7AF4; static data end $13DE. The normal-window buzz persists
in Brian's prior candidate after restart and stops when paused; it remains
unconfirmed fixed. An extra standard-library mute after input sampling passes
worker silence/effect checks. Details, captures and score-preservation proof:
[TITLE_AND_SCORING_UPDATE.md](TITLE_AND_SCORING_UPDATE.md).
## Previous font candidate
The November 11 font/border/copyright candidate passed an official VCC Plus
3.6.0 (51) Release build and MC6809 / 512 KB disposable playtest. The font uses
Pierre Sarrazin's public-domain CardGame data, with attribution. Modern outlines
are dark gray while the background stays black. Title text is
`(c) 2026 Brian Holman`, displayed in the font's uppercase character set.
- Project `84772EFC-B651-4A98-B09E-932247575EA7`, revision 1.
- Build `FAD8FBEA-F07D-4FE8-AE45-E569EEA5E5CC`, artifact
`4566B606-6576-482A-BA3E-BCC673EC729B`; no compiler diagnostics.
- Binary 26,589 bytes, SHA-256
`9eec745d50544884d74211492f0118360d79212f05864d9e81fa43a1a56ed041`.
- Pristine DSK SHA-256
`12f0ee508d5b48bbbe44d1f2b701eb31ae5bd5d3cbb863e1005540524d5dbfb3`.
- Code/constants end $7AFE; static data end $13DD. Existing limits and
1,024-byte stack reserve retained. Further growth needs compaction.
- Pixel tests compare against the unmodified upstream font; palette, all seven
Modern tile colors, Plain/Clean behavior and edge-cell clipping pass under
AddressSanitizer/UndefinedBehaviorSanitizer.
- Actual title, settings and gameplay framebuffer captures inspected. Hold/drop
exercised; a normal settings save wrote the disposable disk successfully.
- Captured idle audio is zero in both channels; movement has a brief effect and
silent final 500 ms. Owned run stopped.
- New private disk copy preserves both existing high-score files byte-for-byte.
Details, screenshots, saved-disk identity and remaining limits:
[FONT_UPDATE.md](FONT_UPDATE.md). Persistence code and gameplay rules are unchanged;
prior cold-boot score evidence below remains applicable to that unchanged code.
Actual 128 KB and physical joystick qualification remain pending.
## Previous audio candidate — November 10 build identity
- Base Git revision: `8a4b44bc7358b1a999296d14d8c5272e57b65992`, main, with
uncommitted implementation. No implementation commit or push was requested.
- Official application: VCC Plus 3.5.5 (48), supported C-project MCP connection.
- Previous code build: project revision 16, Release,
build `CFC0A2F2-9247-4B1C-9CF8-8CC1AFE896B6`,
artifact `261716EE-81C8-487D-A7BF-E5C9F51BC044`.
- Binary: 26,370 bytes,
SHA-256 `5c9f3be05fde79e09a5a583740e676f2fb06eddc136dd9d419f62f12da6bebfe`.
- Previous pristine `Quadrapassel.DSK`: 161,280 bytes,
SHA-256 `d23bc2a1aa60970becaf7ff8be064efc8ea47a5043adf9661d9a6c22bcedfd9b`.
This matched that official MCP artifact, not a saved playtest copy.
- Linked code/constants end at $7AE8 (24 bytes before the enforced $7B00 limit).
Writable static data ends at $1318 (232 bytes before $1400). The stack reserve
is 1,024 bytes; detailed contract and qualification limits are in MEMORY_LAYOUT.md.
- The pristine disk has 50 free granules and no save files. Two 35-sector save
files need four granules each. DOS loader tracks are reserved by the template.
## Implemented
- All 28 piece states, safe above-board behavior, specified kicks, gravity,
hard/soft drop, persistent Hold swap, shadow and simultaneous compaction.
- Modern/Classic 32-bit saturating scoring, level transitions and Relaxed mode.
- Version-1 xorshift32 seeded stream, inverse-square balancing, prefill and
Difficult Pieces metric/selection. Difficult search is currently synchronous.
- Keyboard controls, a complete one-button joystick input state machine with
optional Fire 2 hard drop, settings,
seed editor, pause/actions/confirmation screens, score browser and initials.
- Code-drawn title and cached tiles; menu focus updates without full redraws.
Scene text is a bounded, checksummed disk asset sharing the display cache.
- Standard CardGame `initSound`/`beep` effects, with the standard bsound mute
helper closing audio around joystick sampling and between effects. No custom driver.
- Versioned QPSAVE0.DAT/QPSAVE1.DAT store for all 34 categories, ten records each,
initials and scoring-rule markers. CRC/range/length validation, generation
selection, older-slot recovery, header-last commits and readback verification.
Only those two named files are written; errors are visible and play can continue.
## Evidence and limits
| Check | Result |
| --- | --- |
| Host rule fixtures, sanitizer build | Passed: 28 states, all kick fixtures, bounds/top-out, compaction, 25 scoring cases, gravity, Hold, RNG/prefill and Difficult metrics |
| Host input fixtures, sanitizer build | Passed: repeat/conflicts/edges, fire timing, hysteresis, diagonal and disconnected-stick keyboard behavior |
| Host persistence fixtures, sanitizer build | Passed: 34 categories, stable ties, rule markers, 32-bit values, CRC, read-only reset, all 36 logical torn-write boundaries and recovery |
| Official Release build and memory bounds | Passed, final build above, no compiler diagnostics |
| MC6809 / 512 KB | Passed: DOS title, gameplay, movement/rotation/Hold/hard drop, settings, cached settings redraw and fast menu focus |
| Settings save and cold-boot reload | Passed on revision 12: Sound OFF and Custom Seed ON reloaded from the same disposable disk |
| Earned high score save and cold-boot reload | Passed on revision 12: seed zero, 12 authored placements, one line/40 points, initials BRH, Modern marker in difficulty-0 Normal category; survived another cold boot |
| Clean BASIC return and manual fallback | Passed on revision 13: Quit returned OK; PCLEAR1, LOADM"QUAD.BIN", EXEC reached the title |
| HD6309 / 512 KB | Revision 16 idle/effect audio checks and prior title/gameplay framebuffer smoke passed in reset emulation mode; not a native-mode qualification |
| Physical CoCo 3 / 512 KB | Brian reported successful gameplay on November 11, 2026 ("It worked great"); RAM confirmed as 512 KB. Exact disk hash, CPU upgrade status and individual audio/save/joystick checks were not specified |
| CoCo 3 / 128 KB | Pending actual application/manual test; MCP workers remain fixed at 512 KB |
| Physical joystick ports and joystick-only usability | Pending; logical fixtures/neutral samples are not physical-port passes |
| Guest read-only/corrupt media and interrupted FAT/directory writes | Pending; logical host fault tests do not establish these physical disk cases |
| Direct guest audio, idle/mute and bounded effects | Passed captured windows on 6809 and 6309; actual-app reported noise retest pending; see AUDIO_VALIDATION.md |
| Current input/render latency, sound-on worst case, clears and Difficult search | Not fully qualified; earlier renderer probe timing is not a complete-game timing pass |
| PAL/50 Hz, physical Intel, CoCo 2 | Not qualified by these runs |
| Debug/Probe configurations with the final split layout | Not qualified; use Release for this disk |
The earned-score run was `9AFA5124-4FDE-4E3D-95EE-228FCE945951`.
Its retained writable disk SHA-256 is
`44ca3987b8d3a1e02ee41f1a0de8bd587be5a6835f8bdc5186b22138e6be0355`.
That disk is separate from the pristine deliverable. All owned runs are stopped.
Final menu/cache and 6309 changes did not alter the validated persistence codec.
## Capture interpretation
Presented-frame PNGs sometimes omitted unchanged screen content during these
runs. The supported paused `capture_playtest_graphics` preview showed the title,
HUD/frame and cached settings intact in the current physical HSCREEN 2 buffer.
Visual verification therefore uses these direct guest-framebuffer previews in
addition to ordinary screenshots. No emulator internals were inspected and no
emulator change is required for the current disk.
Selected evidence is under docs/screenshots/, including
high-score-saved-512k.png, high-score-reloaded-512k.png,
title-clean-512k.png, gameplay-framebuffer-512k.png,
settings-cached-framebuffer-512k.png and
gameplay-6309-framebuffer-512k.png. Reference art is not runtime evidence.
Next qualification: follow TESTING_128K.md, measure complete-game latency and
Difficult search separately, then physical joystick/read-only/fault cases.
Further feature growth needs code compaction before exceeding the enforced limit.
## Latest user feedback and sound correction
Brian reported good keyboard pacing, then constant audio noise even while idle.
The standard-library audio routing correction and direct MCP stereo WAV checks
are recorded in [AUDIO_VALIDATION.md](AUDIO_VALIDATION.md). The isolated worker
did not reproduce the original constant noise; the actual application needs a
retest. The save codec and gameplay rules were not changed.
## November 11 — physical CoCo 3 playtest
Brian reported playing Quadrapassel successfully on a real Color Computer 3
and described it as working great. He confirmed the RAM size as **512 KB**.
This is user-reported physical-hardware gameplay evidence, separate from the
isolated emulator runs. It does not establish a 128 KB pass or separate passes
for the audio correction, persistence, joystick ports or every game option.
The exact tested disk/build and detailed machine configuration were not supplied.
## November 11 — follow-up after actual build-02 joystick failure
Brian confirmed loading build 02 with DOS and reported continued inability to
move left and cancelling fire rotations. Build 02 has not passed joystick
acceptance. The next candidate uses standard CMOC interrupt protection and a
stable before/after button scan, and preserves neutral readiness across scene
transitions. CoCoMan was consulted read-only with Brian's explicit permission;
its custom assembly and VCC API were not imported. See JOYSTICK_FIX.md. Actual
right/left-port and 128 KB checks remain pending, as does normal-window buzz.
The [player’s manual](manual/QUADRAPASSEL.md) is the current product guide.
Detailed dated engineering records remain available in this repository and Git
history; earlier pending-test statements describe their original test dates.
+81 -82
View File
@@ -1,98 +1,97 @@
# MCP kickoff and connection inventory
# Connect this project through MCP
Verified November 10, 2026 against installed official VCC Plus **3.5.5 (48)**.
Keep private grant files and tokens outside Git. This is a connection record,
not permission to inspect emulator implementation or another game's project.
VCC Plus shares a selected project through its supported local Model Context
Protocol connection. Use the official downloaded app, this checkout and your own
connection. Create a scoped connection for the project you selected and verify
its current identity before building or testing.
| Connection | Live tools used | Verification |
## Prepare the C-project connection
1. Open this existing game project in **Develop → C Development…** and select
**Release**. Check that `main.c`, the supplied Makefile and project resources
belong to this checkout.
2. In **Assistant…**, review the files and permissions to share. Select **Use
Project Makefile** for its declared recipe. Select **Allow Disposable
Playtests** only when you want the assistant to run isolated copies of the disk.
3. Save a fresh private connection and add it to ChatGPT through the supported
workflow described by the installed manuals. Keep VCC Plus and the shared
workspace open while using it.
4. Discover the tools currently exposed. Make a real project/capabilities request
before changing files or building. Verify project identity, revision, input
files, recipe, Release configuration and the declared disk action.
A configured server, a displayed tool list and successful project access are
three different checks. Tool discovery alone does not establish that the editor
is still open or the connection still authorizes its current project.
## Check three kinds of access separately
| Access | What to verify | What it is for |
| --- | --- | --- |
| Quadrapassel C project | `get_capabilities`, `read_project_inputs`, `refresh_project`, `build_project`, `get_build`, owned-playtest tools | Project `A1AFAA7E-C427-4437-8D1C-EB68D8C225EF`; this repository's root Makefile, files and hashes |
| Installed manuals/API (through the C connection) | `search_help`, `read_topic` | Read HSCREEN/HSET, keyboard, joystick, timer, SOUND, beep and PCLEAR topics |
| Archive Library (separate connection) | `search_archive`, `get_archive_citation` | Both succeeded; found Tandy's Color Computer 3 Extended Basic, PDF pages 152–153 |
| C project | The intended project and current source/build identity | Read/edit proposals, declared Make builds and any approved owned tests |
| Manual Library | A real search followed by reading a returned topic | Installed CMOC API contracts and VCC Plus usage guidance |
| Archive Library | Its own read-only connection and a successful search/citation | Historical CoCo manuals, publications and hardware references |
At this chat's start no VCC Plus tools appeared in its tool catalog. Connections
were exported through the installed app's normal native interface. Its public
manual, `vibe-coding-with-chatgpt/01-first-connection.html`, explicitly permits
ordinary STDIO MCP through `/Applications/VCC Plus.app/Contents/Helpers/vcc-mcp`
with the two arguments `--grant` and the private grant filename. The unmodified
installed helper is used by a small MCP client; no alternative server, private
bridge or integration endpoint is used.
Project connections include manual access; Archive Search has its own connection
exported from the Archive Library panel. Do not infer that Archive access is
missing just because it is absent from a C connection's tool list. Keep a
publication/page citation when using an archived source.
Archive Library has its own link button and **Save Archive Search Connection…**
flow. Brian explicitly approved this connection on November 10. Its advertised
build-48 tools return citations/locations, rather than full page text. Use the
Archive Library native reader for the original page when needed. Do not infer
that Archive MCP is unavailable from the C connection's tool inventory.
Common public project tools include `get_capabilities`, `read_project_inputs`,
`refresh_project`, `build_project` and `get_build`; owned-run and capture tools
are present only for supported, granted capabilities. Manual and Archive tools
have their own returned schemas. These names are discovery examples, not an
instruction to assume a tool exists or hardcode its arguments.
For future kickoff checks, distinguish **configured**, **tools discovered**, and
**successful request**. Inventory each required connection separately before
implementation or web fallback. Confirm the intended project and current revision
before builds. Connection identity and advertised tools may change after a new
export; discover them again, rather than inventing tool names or endpoints.
## Build and test the selected revision
Example verified Archive reference:
Ask the assistant to identify what it can actually do, then:
- Title: *Color Computer 3 Extended Basic (Tandy)*.
- Citation: `sha256:26d4ca51f3477263f3e85269091104079ae88ad83c842cef0e3bc531324e7f5e:pdf_page:152`.
- Read in Archive Library: printed page 143, “Adding Pages (The PCLEAR Command)”.
It describes the default four PMODE pages and reserving fewer pages.
1. Review or refresh changed project inputs through the supported native flow.
Keep the ordinary helper connected while a review is awaiting a decision.
2. Build the current revision's declared **Release** disk action. Poll the build
result, inspect diagnostics/memory bounds and retain the artifact identity.
3. Start an approved disposable run from that exact artifact. Poll startup and
check its actual RAM/CPU/disk configuration before making a test claim.
4. Apply ordinary guest input with release intervals, inspect real frames and
save behavior, and capture bounded audio when available. Stop the owned run
and retain its disk receipt when finished.
Initial hardware-reference web lookups occurred before discovering the separate
Archive connection. That was a discovery error, not a demonstrated Archive gap.
Brian asked that the kickoff feedback be sent to **Deploy VCC Plus Gitea**; the
approved concise feedback was delivered there. No emulator update is requested.
Do not copy mutation request IDs from older runs, use another project's grant,
or assume a past screenshot came from the current build. Keep observations bound
to the project revision, build/artifact and test configuration.
## November 11 reconnection
## If access stops working
Brian approved installed official VCC Plus 3.6.0 (51) and an idle desktop window.
The same repository was opened through C Development and its private project
connection renewed outside Git. A successful `get_capabilities` returned project
`84772EFC-B651-4A98-B09E-932247575EA7`, session
`185C8449-CB9B-4A38-81C8-D43CDA4A3ABE`, app build 51, approved Make recipe,
and the expected Quadrapassel files. This connection still advertises fixed
512 KB disposable workers, MC6809/HD6309, graphics and audio captures.
Archive access is separate and was not needed for this local font adaptation.
Check whether the app and the intended C workspace remain open, whether sharing
is enabled for that project, and whether the private export is still current.
Changing projects, closing the shared workspace, revoking access or exporting a
replacement connection can end an earlier connection. Reconnect through the
native panel and repeat discovery instead of guessing a private endpoint.
After Brian's November 11 restart, the old private grant expired. The same
project connection was renewed through the supported interface. Current project
`3D6A502C-E06D-46BC-9D19-191D741A16B9`, revision 2, built and ran successfully
on official build 51. get_machine_status read normal-session configuration;
no writable disks or peripherals were removed to satisfy native-run blockers.
The new candidate used only disposable playtests.
A tool list can be available while a live request fails. If the environment blocks
access to the app's local service, check the supported connection and applicable
local app/service permission. An actual permission block is different from a
missing tool. Report the observed error; do not replace the app or weaken system
security to hide it. Continue source/documentation work that does not need the
connection until access is restored.
Brian approved official VCC Plus 3.6.1 (53) and an idle desktop window for the
joystick investigation. The renewed connection verified project
7D6E1D9C-DF7C-4B15-B64D-6B30732417CB, revision 2, built successfully and ran the
frozen artifact. Its playtest_input schema still supports only keyboard keys,
not analog axes/fire injection. No native joystick pass is inferred from it.
Capabilities vary between public app releases. If joystick injection, a CPU/RAM
choice, graphics inspection or audio capture is absent, use the supported native
workflow or a clearly identified user-controlled test for that part. Never treat
keyboard input as analog joystick evidence or a worker's 512 KB configuration as
an additional 128 KB test.
Build 03 used that project at revision 3 on official build 53. Keep the official
STDIO helper connected while a refresh awaits native review: with the one-shot
helper disconnected the review window was not presented. Closing C Development
invalidated this private grant after all owned runs stopped. Reconnect through
the official interface when more MCP work is needed.
## Keep sharing private and scoped
Only real result folders belong in outputDirectories. An attempt to exclude
numbered DSK files there was accepted by MCP inventory but broke native project
opening (reported as missing assets/ui-text.tsv). File exclusions were removed;
explicit resourceInputs names the two real text inputs. Native project loading
and Release disk build then passed. Root delivery disks remain project resources:
freeze them during owned tests and create/update delivery filenames after the run
stops. Personal media/backups are never reset to satisfy source identity.
Keep connection exports, tokens and credentials outside the repository and out of
chat text. Do not add them to commits, screenshots, public issues or manuals.
Use only the ordinary official helper/client procedure in the installed manual;
no replacement server, private endpoint or emulator-source inspection is needed.
Revoke a connection when its work is finished, and preserve writable test disks
and personal media independently of the connection's lifetime.
Build04 was built and qualified through the native installed build53 C Development
workflow after the grant ended. Native builds FC462D93 / A7A18927 succeeded.
Launch Disk mounted a separate working copy; explicit cold restart plus DOS was
required because the prior graphics game was still in RAM. A new mounted filename
or C workspace's latest-build badge alone does not prove the guest reloaded it.
Build05 final checks use official build54's newly exported native connection,
project273E195B-8BFC-495F-A1F8-E1469759B910 revision0. Discovery returned29 tools,
playtest_joystick_input and input_diagnostics; actual standard port/axis/fire2
steps and get_playtest_input were used successfully. The official local helper
required local-service execution permission; without that permission it returned
host_unavailable despite local tools/list succeeding. This was resolved without
replacing the grant or changing the emulator. All owned runs stopped; the native
workspace was released to Core for the next project's scoped connection. Private
grant files remain outside Git. See SECONDARY_BUTTON.md for exact evidence.
The public [connection lesson](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
and [existing C-project example](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
provide the supported user-facing setup steps. For the game-specific build and
media rules, use [VCC_PLUS_WORKFLOW.md](VCC_PLUS_WORKFLOW.md).
+10 -13
View File
@@ -20,12 +20,10 @@ The numeric cases in [scoring.json](reference/scoring.json) express the referenc
scoring rules and regression expectations, including new-level multiplication.
These files are data for the new implementation, not a bundled Vala application.
The implementation chat is intentionally restricted to this self-contained
specification and allowed public/reference material. The source links and hashes
above preserve attribution; they do not authorize that chat to inspect the Mac
source or its development chat. This is a black-box boundary around the emulator
and a specification-based implementation workflow, not a claim of legally
independent provenance from the GPL game.
The CoCo game is an independently authored C implementation of this behavioral
specification. Linux/Mac application implementation is not incorporated. The
specification and derived reference data retain their GPL provenance; this
clean-room implementation does not erase their attribution or licensing.
## Credits and licensing
@@ -37,7 +35,7 @@ Holman (macOS port)**. The difficult-piece selection describes its algorithm as
originating in **Federico Poloni's Bastet**. Retain these credits in the port.
The specification and derived piece/scoring reference data are distributed under
GPL-3.0-or-later. Future game code derived from them should preserve that license
GPL-3.0-or-later. The game code preserves that license
and the relevant notices. The Mac fork's separate libgnome-games-support library
has its own LGPL-3.0-or-later terms; that library is not included here.
@@ -65,12 +63,12 @@ are required for this reference treatment.
The specification identifies behavior adapted for the CoCo: conventional
persistent hold swapping, bounded score storage and rule markers, a compact
deterministic PRNG rather than GLib stream compatibility, one-button joystick
menus, lower-color CoCo 2 graphics, approximate tone sequences, and safe handling
menus, approximate tone sequences, and safe handling
of pieces above the board. They must not be described as byte-for-byte Mac parity.
Hardware feasibility, timing, physical palette appearance, API performance and
disk layout are still to be demonstrated by the implementation. The arithmetic
memory estimates and reference tests do not establish a working CoCo build.
Current compatibility and reproducible build results are recorded in
[IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md). Earlier design estimates
and reference fixtures are distinct from guest execution evidence.
## CMOC example references consulted during implementation
@@ -100,8 +98,7 @@ ten digits and twelve punctuation glyphs. No drawing engine or assembly was
imported. Existing lowercase input maps to uppercase glyphs. The new C renderer
uses the original six visible columns/seven rows in each eight-pixel cell.
Brian explicitly permitted inspecting the supplied Mac scoring source on
November 11. The read-only checkout at revision
The scoring reference was checked on November 11 against revision
`be8769a403e506edb930372f963a9c4c83a0881e` confirms the existing Modern and
Classic (40.2) formulas. `scoring_through_drop` in tests/rules_test.c adapts the
GPL-3.0-or-later setup in its tests/test-scoring.vala to exercise actual piece
+12 -8
View File
@@ -1,11 +1,16 @@
# Manual CoCo 3 / 128 KB check
# CoCo 3 / 128 KB verification
Use the official installed VCC Plus application. The MCP worker is fixed at
512 KB; its results below do not establish a 128 KB pass.
128 KB operation has been verified in the actual VCC Plus application. A
physical 512 KB CoCo 3 has also successfully played the game. The checklist
below remains available for repeatable checks of modified builds.
Use the official installed VCC Plus application. An isolated MCP test may use a different RAM configuration; record the
actual configuration rather than assuming it matches the normal emulator.
1. Preserve your current setup and media. In a separate disposable test setup,
select CoCo 3, 128 KB, MC6809 and ordinary stock speed. Use RGB/NTSC initially.
2. Mount a **writable copy** of the pristine top-level `Quadrapassel.DSK` in drive
2. Mount a **writable copy** of the pristine `QUADPSL05.DSK` (or newly built `Quadrapassel.DSK`) in drive
0. Do not overwrite a disk containing your own programs or scores. Type `DOS`.
3. Confirm the title, menus and seven piece colors appear. Start a game; test
movement, rotation, soft/hard drop, Hold and pause/resume. Check that the board
@@ -27,9 +32,8 @@ Use the official installed VCC Plus application. The MCP worker is fixed at
The fallback launch sequence is `PCLEAR1`, then `LOADM"QUAD.BIN"`, then `EXEC`.
Do not use PCLEAR0: official build-48 Disk BASIC rejected it with `?FC ERROR`.
The fallback was separately verified on the clean MC6809/512 KB build; actual
128 KB qualification remains pending.
The fallback was separately verified on the clean MC6809/512 KB build.
Please record the disk hash, machine/RAM/CPU, video standard, results and a
representative guest screenshot. The game targets 128 KB by address layout; a
manual pass is needed before claiming actual compatibility.
representative guest screenshot. For changed builds, repeat the checks rather than treating an earlier
compatibility result as proof of every new change.
+97 -128
View File
@@ -1,152 +1,121 @@
# VCC Plus development workflow
# Build and test with VCC Plus
## Required installed app
Use the official [VCC Plus for Mac download](https://vccplus.brianholman.com/downloads/)
and the complete [Quadrapassel source repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel).
The public installed app supplies CMOC, Make, Perl, libraries and disk tools for
this project. Homebrew and a separate emulator/toolchain build are not required
for the installed C-workspace workflow.
Use `/Applications/VCC Plus.app`, **version 3.6.1, build 54**. Brian requested the final
Quadrapassel test after Core installed it on November 11, 2026. Earlier build53
checks remain historical. The installed
Info.plist was verified. Earlier build-48 evidence remains historical.
Verify again at implementation start.
If the app differs, report it and wait for Brian to approve a different version.
Do not downgrade, overwrite, or build a replacement app.
## Open the existing project
Use the official app's supported MCP sharing/export flow for the Quadrapassel
project. No custom VCC Plus executable, private helper protocol, substitute MCP
server, injected code, private endpoints or emulator modifications are authorized.
The fact that a binary or source checkout exists on the machine is not permission
to use it. This game is a client of the installed product.
1. Obtain the complete repository in a writable local folder. Do not download
only `main.c`: the game also needs headers, platform/rules files, text assets,
generator scripts, the Makefile and `vccplus-project.json`.
2. Choose **Develop → C Development…** in VCC Plus and open that existing project.
Keep the supplied settings rather than creating a new Hello Disk project over it.
3. Select **Release**. The game uses its declared Make recipe and `disk` action.
4. Choose **Build Disk**. The configured Build target also produces the disk;
use the action displayed by your installed workspace.
5. Read the complete result, including diagnostics and the memory-bound check.
Use **Show Build Products** to find the build's `Quadrapassel.DSK` and `QUAD.bin`.
VCC Plus builds in a separate work area, so the latest result need not appear
beside the original source files.
## Reference access through MCP
Release uses the optimization needed by the bounded memory layout. Preserve
`--data=0E00`, `--limit=7B00` and the 1024-byte stack reserve. The additional link-map
check enforces code/constant addresses `$1400..$7AFF` and static-data addresses
`$0E00..$13FF`.
Do not weaken these guards to make Debug or a larger edit fit.
1. Discover the tools advertised by the intended connection. Query capabilities
and confirm the selected project/root, files, revision, approved build recipe,
available build configurations and runtime controls.
2. Use `search_help` and `read_topic` for the installed manuals and API reference.
Suggested first queries: `hscreen hset palette`, `joystick`, `keyboard`,
`CMOC graphics memory`, `sound`, `disk project DOS` and `MCP playtest`.
Search/read may need separate short queries; follow the returned schema.
3. Use the advertised historical archive search and document-reading tools when
present. Consult relevant CMOC, CoCo graphics, keyboard, joystick and disk
references. Read cited sections rather than relying on search snippets.
4. Record the actual tool names and document/topic identities in the implementation
notes. Tool availability may differ from this planning-time inventory.
A fresh anonymous checkout has rebuilt the exact build-05 binary and disk using
the public VCC Plus 3.6.1 bundled Release toolchain. The pristine disk hash is
`d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
See [BUILDS.md](BUILDS.md) for delivery identities and
[MEMORY_LAYOUT.md](MEMORY_LAYOUT.md) for the section contract.
**Planning-time limitation:** the available older project-specific connection
returned `host_unavailable`. Its advertised documentation tools were
`search_help`/`read_topic`; a live build-48 archive search was not verified during
specification preparation. This is not a claim that build 48 lacks archive support.
The implementation chat must discover and use the correct official connection.
Report unavailable access and ask for that connection to be enabled if necessary;
do not request emulator features or create a replacement integration to fill a gap.
## Launch without losing another program
Allowed fallback references include the public manuals in
`/Applications/VCC Plus.app/Contents/Resources/ManualLibrary`, public headers in
`/Applications/VCC Plus.app/Contents/Resources/Toolchain/share/cmoc/include`,
and public examples shipped in the official app. Read public API contracts, not
private headers or library implementation files. The installed public manual's
`programming-in-c/examples/beacon.c` demonstrates `hscreen`, `hset`, palette and
standard BGraph use; it is a reference, not permission to copy raw register access
from an example without the exception review.
Save guest programs, source drafts and pending media changes before launching.
**Launch Disk** uses the built disk and the project's declared `DOS` command;
attend to the app's normal floppy-replacement and restart confirmations. Use a
writable test copy and preserve personal score disks.
Pierre's programs and other examples under
`/Users/bholman/Development/Personal/VCC/CMOC/Repositories/` are also permitted
read-only references. Inspect the selected example's license before reusing code.
Search within that folder or an individual example, not the parent VCC directory.
Do not read the Mac Quadrapassel implementation or private VCC Plus material.
Mounting a different disk does not replace the program in RAM. For a new build,
start it from a clean Disk BASIC state and actually load it with `DOS`. Verify the
running artifact as well as the mounted filename. The manual loading alternative
is `PCLEAR1`, `LOADM"QUAD.BIN"`, then `EXEC`.
Useful public references include the [XRoar author's manual](https://www.6809.org.uk/xroar/doc/xroar.shtml)
for CoCo 2 validation and [Chris Lomont's CoCo hardware reference](https://www.lomont.org/software/misc/coco/Lomont_CoCoHardware.pdf)
when a public hardware description is needed. Reading these is allowed; implementing
raw hardware access still requires the approval process in `AGENTS.md`.
The game supports **CoCo 3 with 128 KB or more**. 128 KB emulation and physical
512 KB CoCo 3 play have been verified. Set up the intended machine and record its
actual RAM/CPU/video configuration when testing a change.
## Standard APIs before optimization
## Connect ChatGPT to this C project
Begin with the public CMOC `coco.h` interface:
Open **Assistant…** in the C workspace, review the shared files, and select
**Use Project Makefile**. Allow disposable playtests when isolated execution is
wanted. Save a new private connection using the supported export process and
connect it to your assistant. Do not post its token or connection file in source,
issues or chat messages.
| Need | Initial public API candidates |
| --- | --- |
| CoCo 3 display | `hscreen`, `hset`, `palette`, `paletteRGB`, `rgb` / `cmp` |
| CoCo 2 display | `pmode`, `pcls`, `screen`; documented standard graphics-library routines |
| Keyboard | `isKeyPressed`, `inkey`, documented keyboard helpers |
| Joystick | `readJoystickPositions`, `readJoystickButtons`, named port/button constants |
| Timing/speed | `getTimer`, `setTimer`, `setHighSpeed` with their documented contracts |
| Sound | `sound` or documented standard CMOC sound-library APIs |
| Disk | Documented standard CMOC disk/file libraries selected through Project Settings |
Begin with live discovery and a real capabilities request. Confirm this project's
files, revision, approved recipe, declared configuration and disk action. Use only
the tool names and argument schemas returned by the installed connection. The
[MCP setup guide](MCP_SETUP.md) gives a portable checklist; it does not require
a machine-specific connection.
Check actual header/manual contracts and return codes. Do not infer exact behavior
from names. In particular, the public `coco.h` joystick button prose and its named
bit constants have inconsistent ordering in the inspected header; confirm both
physical ports in the API probe instead of hardcoding a guess.
For an owned disposable run:
`hscreen`/`hset` use BASIC's graphics workspace. They are distinct from the
VCC-specific `vcc/gime.h` helper whose documented contract requires at least
512 KB. The latter is not the baseline and would need exception review. Do not
infer that 128 KB needs a custom renderer just because that helper needs more RAM.
1. Build the current revision's declared disk action in **Release** and inspect
its result. Bind later observations to its artifact identity.
2. Start a fresh owned playtest of that artifact and poll startup as documented.
A supported retained test disk can be selected only with its matching receipt.
3. Send ordinary guest input, including release intervals. Capture real guest
graphics/audio when those capabilities are advertised. Never change guest
memory/registers to manufacture a score or screen.
4. Test the affected controls, gameplay, saves and return paths. Use advertised
read-only inspection when appropriate; do not invent unavailable debug values.
5. Stop the owned run and retain its writable test-disk receipt. Do not stop
another person's game or delete its media.
Compose ordinary game rendering with standard APIs first, update changed cells,
and measure. Direct framebuffer access, custom register code, assembly or a
nonstandard extension remains gated even when an example contains it. Prefer a
manual machine/target choice to an unapproved raw detection routine.
Disposable-worker choices depend on the installed app. If a worker advertises
512 KB, that describes the test configuration, not the game's minimum memory.
Do not describe a 512 KB run as an additional 128 KB check. Likewise, actual
joystick states and keyboard aliases are different test evidence. Use supported
native input or a user-controlled physical test when a capability is absent.
## Project, build and playtest sequence
Before pointer/keyboard automation, obtain a current idle, unlocked desktop window
unless the user has already granted one for that work. Keep personal machine
settings and media separate from disposable tests.
Create the game project using the installed C Development workflow and its public
project template. Keep source and settings in this repository. The official app
can create a standard disk-project recipe; keep that recipe and its resource/DOS
configuration reproducible. Do not add game code to the emulator repository.
## Documentation and references
The previously advertised MCP pattern is listed below as a discovery aid, not a
promise that every build-48 connection has the identical tool set:
Use **Help → Manual Library…** and discover its search/read tools through the
project connection. For historical CoCo material, **Archive Library…** has its
own read-only sharing connection. Verify each access separately before falling
back to an unrelated source. Public installed CMOC headers/examples are also
valid API references; emulator internals are outside this game's workflow.
1. `get_capabilities` and project input/file readers identify the shared project.
2. Make normal repository edits or use the advertised reviewed edit proposal flow.
New files, assembly (only after approval), or Make changes must use a supported
project update/review path. Refresh and inspect the resulting revision.
3. `build_project` takes the current project/revision, an advertised `build` or
`disk` action and declared configuration. Poll `get_build`; inspect the build
log. Do not invent target names or bypass recipe review.
4. Start an isolated playtest from the returned artifact. Poll its run status.
Match source revision and artifact identity before accepting a result.
5. Exercise keyboard input, capture the guest screen/graphics and capture bounded
guest audio with the advertised tools. Use documented guest debugger inspection
when useful. Do not reach into emulator implementation state.
6. Stop the owned run through the supported tool. Preserve writable disk results
and useful evidence. Do not operate another project's connector or live session.
Public manual chapters describing the interface and sequence:
A CLI invocation of the installed bundled toolchain can supplement diagnosis if
documented, but it is not a substitute for building and running through the
official VCC Plus workflow. Do not silently substitute Homebrew or another compiler.
- [Build a disk from a folder](https://vccplus.brianholman.com/manuals/programming-in-c/disk-project/)
explains Build, Build Disk, Launch Disk and Show Build Products.
- [Make the first connection](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
explains private connection exports and verifying real access.
- [Build a quiz and give ChatGPT the keyboard](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
demonstrates opening an existing public C project and its Make/disposable loop.
## Memory and input qualification
Use standard documented CMOC APIs before new hardware-specific code. The existing
bounded C graphics renderer is a recorded exception; see [AGENTS.md](../AGENTS.md)
and [DECISIONS.md](DECISIONS.md) for its scope. Preserve component licenses.
The planning-time `start_playtest` contract described a fixed **512 KB** isolated
machine with a 6809/6309 choice. Recheck build 48's actual advertised schema. If it
still cannot select 128 KB, test that memory size through the official app's normal
Machine Settings interface in an isolated user-approved session. Its installed
user manual lists 128 KB as a supported memory selection. A 512 KB playtest alone
does not establish 128 KB compatibility.
## Numbered delivery and save data
No joystick injection tool was present in the planning-time inventory. Check the
actual build-48 connection. Use normal supported app input or Brian's joystick /
XRoar testing where MCP cannot supply it. Keyboard events are not evidence that
analog sampling, dead zones or both joystick ports work.
The recipe's `Quadrapassel.DSK` is a clean staging image. Delivered builds use
`QUADPSLxx.DSK`, with a two-digit number; each changed delivery gets a new filename
and starts with empty high scores/default settings. Verify that neither QPSAVE
file is included before copying to a new numbered filename, compare hashes, and
record the result in [BUILDS.md](BUILDS.md).
Before desktop pointer/keyboard automation, obtain Brian's current idle-desktop
grant. Use only supported isolation and preserve active media/settings. Do not
launch another ordinary instance that competes for the same saved state. If a
safe isolation path is unavailable, continue independent work and request a
specific manual check rather than changing the installed app.
For XRoar, give Brian a pristine DSK copy, exact machine/RAM/clock/ROM requirements,
loading steps, controls, expected results and an evidence checklist. Do not
redistribute private ROMs. Separate user-confirmed CoCo 2 results from VCC Plus
CoCo 3 compatibility runs. Keep screenshots limited to the guest display.
## Numbered game delivery
Brian's latest November 11 convention is `QUADPSLxx.DSK`, beginning with 01,
with empty high scores/default preferences for each new delivery. Keep the
official recipe and MCP artifact at its existing staging name, Quadrapassel.DSK.
Verify no QPSAVE data is present, copy to a new numbered filename without
overwriting, compare hashes, and record it in BUILDS.md. Old personal disks
remain untouched; automatic score migration is no longer part of delivery.
Never overwrite an existing numbered or personal disk to deliver a build. Preserve
mounted media, score disks and backups during cleanup. Score migration is a
separate requested action, not an automatic part of a game update.
+31 -38
View File
@@ -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 real title screen, with Start, Settings, Controls, Scores, Credits, and Quit](images/title.png)
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
![Controls screen with keyboard help and right/left joystick readings](images/controls.png)
**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.
![Eight-digit hexadecimal seed editor with the current digit marked](images/seed-editor.png)
@@ -412,7 +417,7 @@ Letter entry uses A–Z. Type one letter and let the selected field advance and
![A real earned high score saved in its category, with its scoring-rule marker](images/scores-saved.png)
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 CoCo Credits screen preserving original and component acknowledgements](images/credits.png)
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.
+2 -3
View File
@@ -3,9 +3,8 @@
`QUADRAPASSEL.md` is the plain GFM source for the online and PDF player guide.
`manual.json` supplies its shared cover/hero metadata. `images/` contains 17
unchanged guest-framebuffer PNGs; `screenshots.json` records their hashes,
configuration and public capture receipts. No Mac/reference screenshots or
retouched game states are used. The earned example is AAA / 40 / Modern,
difficulty 0 / Normal, on an independently retained disposable disk.
configuration and public capture receipts. The
scoreboard example is AAA / 40 / Modern, difficulty 0 / Normal.
The manual is © Brian K. Holman 2026, GNU GPL-3.0-or-later. Preserve the exact
spaced copyright wording in the manuscript/metadata and component acknowledgements.
+5 -2
View File
@@ -5,7 +5,10 @@
"copyright": "© Brian K. Holman 2026",
"edition": "Player’s manual · Game build 05 · November 2026",
"hero_image": "images/title.png",
"hero_caption": "Real CoCo title screen captured in VCC Plus 3.6.1 (54). Game disk build 05.",
"hero_caption": "Quadrapassel for CoCo",
"running_title": "Quadrapassel for CoCo · Player’s manual",
"brand": "VCC Plus Documentation"
"brand": "VCC Plus Documentation",
"disk_url": "https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel/raw/commit/49bc78158a5e17ba717381a3a2cbb4ab35c36dfe/QUADPSL05.DSK",
"source_url": "https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel",
"access_note": ""
}