Files
Quadrapassel/README.md
T

142 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Quadrapassel for CoCo
A CoCo 3 implementation of Quadrapassel in C,
using CMOC and the installed VCC Plus development tools.
Build this candidate with the **Release** configuration.
**Status: CoCo 3 implementation in progress. A playable stage has run in official
VCC Plus 3.6.0 (51), with earlier gameplay/persistence checks on 3.5.5 (48). Persistent high scores/settings have saved and reloaded after cold boot on the
official 512 KB MC6809 playtest. Brian also reported successful play on a physical
512 KB CoCo 3 on November 11, 2026. A clean game disk is available; actual
128 KB qualification is pending.**
| Target | Experience |
| --- | --- |
| CoCo 3, 128 KB | Primary target: complete game, seven distinct piece colors, keyboard and joystick |
| CoCo 2, 64 KB | Future adaptation; not included in this candidate |
| CoCo 3, 512 KB or more | Runs the baseline game; enhancements only when they offer a measured benefit |
Deliveries use `QUADPSLxx.DSK`, with a two-digit build number and a convenient
DOS launcher and a documented manual launch path. RAM sizes above are **KB**.
## Player’s manual
Read the detailed [online manual](https://vccplus.brianholman.com/games/quadrapassel/)
for every screen, keyboard and joystick controls, both scoring rules and all 34
scoreboards. Its shared VCC Plus reading edition includes a reviewed PDF download.
The authoritative [Markdown and screenshot source](docs/manual/QUADRAPASSEL.md)
includes 17 actual emulator captures; [reproduction steps](docs/manual/README.md)
use the common VCC Plus documentation process.
## Start here
- [START_HERE.md](START_HERE.md): prompt for a separate chat within the existing VCC Plus project.
- [SPECIFICATION.md](SPECIFICATION.md): self-contained game behavior and acceptance requirements.
- [AGENTS.md](AGENTS.md): development boundaries and required exception review.
- [VCC Plus workflow](docs/VCC_PLUS_WORKFLOW.md): approved official build 51, MCP, manuals, API and archive access, and testing.
- [Implementation stages](docs/IMPLEMENTATION_PLAN.md): deliverables and verification checkpoints.
- [Provenance](docs/PROVENANCE.md): source revision, credits, licenses and reference data.
Use standard CMOC APIs first. Brian approved a narrowly scoped C graphics
exception; its exact scope and measured evidence are in [DECISIONS.md](docs/DECISIONS.md).
Other low-level exceptions still require review before implementation.
VCC Plus internals remain outside scope. The supplied specification is the
behavioral reference, with Brian's explicit read-only exception for checking
the Mac port's scoring source recorded in AGENTS.md.
## Current development checks
The current priority is the complete CoCo 3 game with 128 KB support. CoCo 2 work
will follow after that version is working and tested. See the
[implementation status](docs/IMPLEMENTATION_STATUS.md),
[MCP setup](docs/MCP_SETUP.md), and [memory layout](docs/MEMORY_LAYOUT.md).
Host complements to the official-app build/playtest workflow:
```sh
python3 tools/test_rules.py
python3 tools/test_components.py
python3 tools/test_video.py
```
Keyboard: arrows or A/D move, Down/S soft drop, Up/W preferred rotation, Q/E
counterclockwise/clockwise, Space hard drop, H hold, P pause, Enter select, BREAK
back/pause. The title also accepts Space. A short joystick fire press rotates on
release; holding fire for 400 ms opens actions, including Hold and Settings.
Joystick Up or the secondary button hard-drops like Space. The secondary button
drops once on press; release it before another drop. Down remains soft drop.
High scores are designed to reload from `QPSAVE0.DAT`/`QPSAVE1.DAT` on the game
disk. The two-slot store covers all difficulty/normal-or-difficult categories and
reports write failures. Guest save/reload has passed on official build 48 / MC6809 / 512 KB. See the
[128 KB manual check](docs/TESTING_128K.md) for the remaining target validation.
## Credits and license
Based on [GNOME Quadrapassel](https://gitlab.gnome.org/GNOME/quadrapassel) and
[Brian Holman's macOS port](https://github.com/bkholman/quadrapassel-macos).
Preserve the original authors and component notices listed in
[PROVENANCE.md](docs/PROVENANCE.md).
Specification text and derived piece/reference data are provided under
**GPL-3.0-or-later**; see [COPYING](COPYING). The supplied title image is a design
reference with a separate notice in the provenance document. No Mac application,
ROM, emulator implementation, or third-party sound payload is included.
## Run the current CoCo 3 disk
Mount a writable copy of [QUADPSL05.DSK](QUADPSL05.DSK) in drive 0 and type
`DOS`. Keep the downloaded original pristine. The current build targets the
CoCo 3; CoCo 2 adaptation is deferred. Allow disk loading and explicit saves to
finish before the next action. High scores/settings use QPSAVE0.DAT and
QPSAVE1.DAT; QPTEXT.DAT contains read-only menu text.
Each numbered build starts with empty high scores and default preferences.
Existing personal score disks remain untouched; scores are not copied into the
new build. The current delivery is **build 05**; the next changed delivery will
be build 06. See [build records](docs/BUILDS.md). The official recipe still uses
Quadrapassel.DSK as its clean staging artifact.
The separately verified manual fallback on the 512 KB test machine is:
```basic
PCLEAR1
LOADM"QUAD.BIN"
EXEC
```
Audio is explicitly muted between brief effects, including during analog
joystick sampling, using standard CMOC library calls. See
[audio validation](docs/AUDIO_VALIDATION.md) for direct MCP capture results and
the remaining actual-application retest.
## November 11 visual update
The menu and HUD now use Pierre Sarrazin's public-domain CardGame font, with
attribution and original source retained. Modern blocks have dark gray outlines
(RGB 1,1,1); the background remains black. The title credit is
`(c) 2026 Brian Holman` (rendered in the font's uppercase character set).
The font/border pixel fixtures and enforced memory bounds pass. Current official
app qualification and disk identities are recorded in [the latest update](docs/TITLE_AND_SCORING_UPDATE.md).
Settings names the scoring choices **Modern** and **Classic (40.2)**. Switching
changes the next game and defaults to keeping existing high scores. Both
formulas match the supplied Mac source. The reported normal-window buzz remains
unconfirmed fixed; isolated audio is quiet between effects.
Build 04 corrects a bundled CMOC optimizer error that supplied the wrong
horizontal calibration byte, causing constant right movement. It also includes
stable button sampling and preserves joystick readiness across keyboard-confirmed
scene changes. Native right-port emulated joystick checks pass for left/right,
four lasting T-piece turns, and steering after keyboard pause/resume. Actual
physical controller/CoCo and left-port retests remain pending. CoCoMan was a
read-only reference; its assembly and VCC-specific APIs were not imported.
See [the target diagnosis](docs/CMOC_JOYSTICK_ARGUMENTS.md) and
[joystick validation](docs/JOYSTICK_FIX.md).
Build 05 adds Fire 2 hard drop once per press, retaining joystick Up and Fire 1.
Official VCC Plus 3.6.1 (54) Release and actual standard right-port joystick
snapshots pass press/hold/release/repress, steering, lasting rotation and steering
after keyboard pause/resume. Host adapter checks cover both ports. See
[secondary-button validation and acceptance steps](docs/SECONDARY_BUTTON.md).
Physical controller/CoCo, left-port guest and 128 KB qualification remain pending.