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

+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.