Prepare public CoCo 3 documentation and portable VCC Plus workflow
This commit is contained in:
1 parent
e9574b6f0d
commit
4aa739780c
16 files changed
+572
-913
No files matched your search
+34
-72
@@ -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.
|
||||
Reference in new issue
Block a user