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