22 KiB
Quadrapassel for CoCo — implementation specification
Current CoCo 3 behavioral specification. The independent C implementation uses this specification as its functional reference. The specification was prepared from behavioral analysis; Linux/Mac application source is not incorporated. Provenance and the exact reference revision are in docs/PROVENANCE.md.
1. Product requirements and priorities
Build a responsive falling-block game for a stock 6809 CoCo, predominantly in C using standard CMOC APIs. Develop and test with the stock downloaded VCC Plus and its supported CMOC toolchain, published APIs and MCP connections.
| Priority | Requirement |
|---|---|
| Primary | CoCo 3 with 128 KB: full rules, seven distinct piece colors, keyboard and joystick |
| Expanded RAM | CoCo 3 with 512 KB or more: same complete baseline game |
Use one standard floppy image. Prefer one shared rules engine and, where practical, one executable. Separate display-specific executables on the same disk are allowed if memory layout makes that simpler. Do not duplicate the rules between variants. Memory figures are KB. Do not require 512 KB for the seven colors or core gameplay.
Standard CMOC first is a requirement, not just a preference. The exception process in AGENTS.md applies before any assembly, custom hardware/framebuffer code, VCC-specific extension API, or other implementation outside standard CMOC. Published documentation may be read to assess an exception; this does not approve it.
2. Board, pieces and coordinates
- The board has 10 columns and 20 visible rows, indexed from
(0,0)at top left. Empty cells and the seven piece colors are distinguishable logical values. - An active piece has a type, rotation state
0..3, and an origin(x,y)for its 4 by 4 definition. Settled cells do not include the active piece or its shadow. - Use the exact four states for each piece in
docs/reference/pieces.json. Rows run top to bottom;
columns left to right;
#is occupied. Do not replace this table with a modern rotation system. Repeated states for S, Z, I and O are intentional.
| Type index | Piece | Reference color |
|---|---|---|
| 0 | L | Red |
| 1 | J | Green |
| 2 | T | Blue |
| 3 | S | Light gray |
| 4 | Z | Yellow |
| 5 | I | Purple |
| 6 | O | Orange |
The seven-color requirement means seven distinct piece colors, not seven total screen colors. Black, text, borders and shadow can use additional palette slots. Exact modern Mac RGB values are not required; choose readable CoCo approximations.
To spawn a piece, compute the minimum occupied column xmin, occupied width w,
and minimum occupied row ymin from its current state. Set
x = floor((10-w)/2)-xmin, y = -ymin. Thus its first occupied row starts at board
row zero even when its 4 by 4 definition has an empty first row. Test collision at
spawn. If any visible occupied cell overlaps a settled cell, end the game.
Movement rejects a result with an occupied cell outside columns 0..9, below
row 19, or overlapping a settled cell at row zero or below. Cells above row zero
are allowed while moving/rotating, but must never index the board array. If locking
would leave an occupied cell above the board, end the game safely; do not write
out of bounds. This is an explicit safety rule for the CoCo implementation.
3. Movement, rotation and locking
Left/right moves one column immediately, then repeats after 200 ms, then every 40 ms while held. A blocked move does not alter the board. If opposing directions are held, the first held direction wins until released; then use the remaining direction. Alias keys for the same action share one logical held state. Rotation, hold and hard drop are edge actions, without automatic repeat.
Counterclockwise rotation advances the table state by +1 modulo 4; clockwise
uses -1 modulo 4. Try horizontal adjustments in this order: 0, +1, -1, +2, -2.
If the current piece origin has y < 0, also use a downward adjustment of one row
for every candidate; otherwise use zero. Accept the first valid candidate. If
all fail, retain the exact previous piece and origin. There are no other kicks,
floor kicks, spin bonuses, or modern SRS rules.
Gravity interval in milliseconds is round(80 + 800 * 0.75^(level-1)), with the
source's minimum clamp of 10 ms. In practice the formula approaches 80 ms.
Use an integer lookup or integer calculation; a floating-point library is not
required. Preserve elapsed time when converting to 50/60 Hz ticks so rounding
does not accumulate major speed differences.
Pressing soft drop attempts one downward move immediately, then uses an 80 ms gravity interval while held. Release restores normal gravity. Hard drop moves to the lowest valid row and locks immediately. Neither type of drop awards points. On an ordinary gravity tick, lock when the downward move fails; there is no extra modern lock-delay/reset mechanic.
On lock: place cells, identify all full rows, record whether original row 19 is among them, remove those rows simultaneously, compact survivors downward while preserving order, insert empty rows at the top, update lines/score/level, reset the hold allowance and spawn the next piece. Visual effects must not change this ordering or block controls unnecessarily.
4. Next piece, hold and landing shadow
Show one next piece and a separate held piece. Ordinary new pieces and pieces retrieved from hold start in rotation zero at their computed spawn location.
Hold is usable once per locked piece. With no held piece, store the active type, activate the preview, and generate a new preview. With a held piece, swap active and held types without consuming or replacing the next preview. A second hold before a lock does nothing. A replacement that cannot spawn ends the game.
Intentional CoCo correction: the reviewed Mac implementation's nonempty-hold branch clears the held slot and overwrites the next slot. This specification uses the conventional persistent hold swap described above, rather than carrying that anomaly into the new game. Test the queue preservation explicitly.
Landing shadow is off by default. When enabled, show the lowest valid placement of the current piece without changing game state. Use a subdued outline/stipple appropriate to the display; the Mac reference opacity is 37.5%, not a CoCo alpha blending requirement. Recompute after movement, rotation, hold and board changes.
5. Piece selection and repeatability
Normal selection is weighted balancing, not a seven-piece bag. Keep a count
for each type, initially zero. Let m be the lowest count and
r[i] = max(1, count[i]-m). Select a type proportionally to weight 1/(r[i]*r[i]),
then increment that type's count. Lower-frequency types become more likely;
duplicates and runs remain possible. Rebase all counts by their minimum when
needed to prevent overflow. A documented fixed-point approximation is acceptable
if tests preserve the intended weighting and no type becomes permanently excluded.
Seeded games accept a 32-bit seed and reproduce the same initial board and piece stream in the CoCo port. A documented compact PRNG is allowed; bit-for-bit GLib/Mac random-stream compatibility is not required. Keep cosmetic randomness separate. Support a test-supplied explicit piece sequence for rule fixtures; do not expose test hooks as undocumented end-user features. Freeze the PRNG and draw ordering once CoCo seed fixtures are published, or version changes clearly.
Also provide optional Difficult Pieces, off by default. For each type and each of its four rotations, consider horizontally reachable positions from the spawn row, drop the candidate and evaluate the resulting compacted board:
metric = 5000 * rows_cleared - 5 * sum(column_heights)
A column height is 20 - first_occupied_row, or zero for an empty column. Retain
the best metric for each type. Add a random integer in [-2,1] to each best metric
(the source's upper bound is exclusive despite its comment), then stably sort
types by ascending metric. Draw an integer 0..98: <75 selects the worst,
<92 the second worst, <98 the third worst, otherwise the fourth worst.
Choose a uniformly random rotation 0..3 for that difficult piece. A type with
no valid placement ranks worst. Simulations must have no effects on actual score,
sound, preview, input or persistence. Document the candidate-board timing and
freeze it in tests; use the settled board at preview-generation time.
This search can be staged across updates in C if needed. Measure it separately; do not solve its cost with unapproved assembly or silently remove the option.
6. Difficulty, levels and scoring
Difficulty is an integer from -1 through 15, default 0. For d >= 0,
level = d + 1 + floor(total_lines/10). For d = -1 (Relaxed), level stays at one.
Start with max(d,0) bottom rows prefilled. For each such row, select one random
column that must remain empty. Each other cell independently has a 50% chance of
being filled with one of the seven colors. Rows above are empty. Thus prefill
never starts with a full row. Initial score and cleared-line count are zero.
After a clear, add the number of cleared rows to the line count before computing the level used for scoring that clear. The active game's rule is immutable.
| Rows cleared | Regular points multiplied by level |
|---|---|
| 0 | 0 |
| 1 | 40 |
| 2 | 100 |
| 3 | 300 |
| 4 | 1200 |
If the cleared rows include the original bottom row, add:
- Modern (default):
100 * level * rows_cleared. - Classic (40.2):
10000 * level, once for that clear.
There is no bonus merely for moving a row down into the bottom position, and no
additional all-clear, combo, spin, or drop score. Use a minimum 32-bit score type.
Handle numeric overflow explicitly rather than wrapping negative; document the
display/storage limit. Do not accidentally use CMOC's 16-bit int for scores.
Authoritative numeric cases are in docs/reference/scoring.json. Examples at level one: bottom-row clears of 1/2/3/4 rows give 140/300/600/1600 Modern and 10040/10100/10300/11200 Classic. A single bottom-row clear from nine prior lines at difficulty zero advances to level two and gives 280 or 20080.
7. Controls and menus
Keyboard
| Input | Action |
|---|---|
| Left/Right or A/D | Move with repeat |
| Up or W | Rotate in preferred direction, default counterclockwise |
| Q / E | Rotate counterclockwise / clockwise |
| Down or S | Soft drop while held |
| Space | Hard drop |
| H | Hold |
| P | Pause/resume |
| Enter | Start from title/game over; select in menus |
| BREAK | Pause/open actions while playing; cancel/back in menus |
No Mac Command shortcuts are required. A live New Game or Quit action must offer a cancelable confirmation. Releasing keys while paused must not leave stuck movement after resume. Clear transient input on menu/state transitions and require release before a held confirm key can activate a second screen.
Standard analog joystick
Support right and left ports, default right, using standard CMOC joystick APIs. The primary experience must work with one button and no keyboard assistance. Do not require a USB-specific mapping, a second button or a VCC-only extension.
Default mapping to implement and usability-test:
- Left/right: movement with the same repeat timing as keyboard.
- Down: soft drop while held.
- Up: one hard drop, rearmed only after returning to neutral.
- Secondary button (optional two-button controller): hard drop on press, like Space; once per press, with release required before another drop. Ignore it in menus and when the joystick is Off. This addition was approved November 11, 2026; the complete one-button control path remains available.
- Short button press/release: rotate in the preferred direction, once on release.
- Button held for 400 ms: pause and open the actions menu, without triggering a rotation on release. That menu provides Resume, Hold, Rotate Other Way, Settings, New Game and Quit. Hold/Rotate Other Way performs that action and resumes; disable Hold if already used. This makes every essential action available with a one-button controller.
- Menus: up/down choose, button selects after a release guard; include a visible Back/Cancel entry. Left/right adjusts settings where relevant.
The short-press/long-press scheme is a CoCo adaptation, not behavior claimed for the Mac port. Measure release-to-rotation latency; tune usability in ordinary C. Document any mapping refinement and preserve access to all actions.
Sample input regularly. Calibrate neutral explicitly at the player's request;
do not silently recenter a deliberately held stick during play. For 0..63 axes,
a reasonable starting dead zone is center ±6, with activation beyond ±10 and
hysteresis back into the inner zone. Clamp near endpoints. On diagonals, prioritize
the dominant axis for edge actions so a horizontal motion does not accidentally
hard-drop. Require neutral between upward edge actions. Missing/disconnected
controllers must not prevent keyboard use or cause uncontrollable menu movement;
allow joystick input to be disabled. Validate actual axis/button readings, not
keyboard presses presented as joystick evidence.
8. Screens, appearance and sound
Title and layout
Use the supplied image as visual inspiration: dark background/grid, bright falling-block shapes and a large readable title. The game title is Quadrapassel for CoCo. Show Start, Settings, Controls, Scores and Credits, with keyboard and joystick selection. Adapt to native resolution; do not embed a scaled Mac screenshot or claim the reference is a running CoCo. A small animation is desirable if responsive. Full gameplay does not wait for an unskippable title animation. Do not require streaming image assets.
Keep all 20 rows visible. Show score, level, cleared lines, next piece, held piece, and the active scoring mode. Pause/game-over overlays are unmistakable. Keep blocks visually square after the CoCo image's display aspect correction; logical pixels need not be square. Use a readable bitmap font and clear focus indication. A board using about 160 of 192 lines leaves room for framing/status; final geometry is determined by the standard API prototype.
CoCo 3: begin with standard CMOC hscreen(2) / hset() and palette APIs for the
320 by 192, 16-color display. Redraw changed regions with those APIs; avoid
redrawing the entire screen unnecessarily. Measure before proposing a different
drawing method. Preserve BASIC graphics workspace and return to text cleanly.
Offer Plain (flat), Modern (dark outlines, default), and Clean (light edging) styles as low-cost approximations. Grid outlines default off. Avoid allocating separate full-screen bitmaps per theme.
Sound
Use standard CMOC sound APIs initially. Approximate the reference's event distinctions with short tones; waveform fidelity and background music are not requirements. The following synthesis descriptions are CoCo design targets, not measured transcriptions of the original audio:
| Event | Target |
|---|---|
| Successful sideways move | Quiet, very short tick |
| Successful rotation | Brief higher chirp distinct from movement |
| Lock with no clear | Short lower landing tone |
| One-row clear | Short bright confirmation |
| Two-row clear | Slightly longer rising confirmation |
| Three/four-row clear | Shared more celebratory sequence |
| Game over | Distinct descending phrase |
No sound for rejected moves. Sound defaults on and can be muted. Drop motion does not produce a tone per fallen row. Measure blocking behavior of standard sound calls and input responsiveness with sound enabled. If adequate feedback requires a custom driver or assembly, request the documented review before implementing it. A sound requirement does not waive that gate.
9. Preferences and high scores
Defaults: difficulty 0; Modern scoring; Modern style; counterclockwise preferred rotation; grid and landing shadow off; sound on; Difficult Pieces off; custom seed off with stored seed zero; joystick right port.
Settings must be accessible from the title and paused game. Theme/grid/shadow/ sound/controls can apply immediately. Difficulty, random seed, Difficult Pieces and scoring rule apply to the next game. Display that distinction clearly.
For a scoring-rule change, offer Keep Scores, Reset Scores, and Cancel. Explain that keeping scores may mix different scoring rules. Reset clears every category, and if a game is active it continues but its score cannot subsequently be saved. Cancel changes nothing. The current game always retains its initial scoring mode; no retroactive recalculation. Failure to save/reset must be reported without silently claiming success or erasing unrelated files.
Store a bounded top-ten table per difficulty and normal/difficult-pieces mode. Include three-character initials, score, and a Modern/Classic marker for clarity. Sort descending by score with stable ordering of ties. This bounded storage and explicit marker are CoCo adaptations. No wall-clock date, Mac scoreboard import, localization framework or Mac window preferences are required.
Use documented standard CMOC disk APIs. Keep settings/scores in named disk files with a version identifier, length/range validation and corruption detection. Use a recoverable two-slot or equivalent bounded save scheme and test interrupted writes; do not assume a modern filesystem's atomic rename. Missing files mean defaults/empty scores. Read-only media keeps play functional and reports that changes cannot be saved. Write on explicit changes/game completion, not each frame. Never reformat the user's disk as a recovery action.
10. Memory, speed, disk and launch
Start with measurements rather than a bespoke memory manager. The board itself needs only 200 bytes at one byte per cell; bitmask piece definitions need 56 bytes. A 320 by 192, 16-color framebuffer needs 30,720 bytes. These arithmetic facts make 128 KB a plausible target, but do not prove a valid address layout. Record code/data/stack, graphics workspace, BASIC/ROM/disk requirements and free headroom from the actual linked build. Avoid allocating a second full framebuffer by default. Standard CMOC's BASIC-backed graphics APIs must retain their workspace.
The installed public vcc/gime.h extension requires 512 KB and reserves physical
RAM beyond 128 KB. It is a separate helper, not the standard coco.h graphics API.
It is neither the baseline solution nor an approved exception.
Use stock-compatible CoCo speeds with the supported setHighSpeed() API only
where appropriate and validated. Record actual speed. Restore the required state
before disk operations and exit according to public API documentation. Do not
hide performance issues with emulator overclocking or require a 6309. Test the
6809 path first; 6309 compatibility is a separate useful check.
Use a standard 35-track, 18-sector, 256-byte-per-sector floppy image (161,280 raw bytes). Actual file capacity is lower after directory, allocation and boot space. Reserve documented DOS-launcher tracks and space for scores/settings. Report real used/free granules; an initial program/assets target below 128 KiB is a planning budget, not a claim of available capacity. No second disk is required to play.
Use the installed VCC Plus disk-project workflow and documented DOS-launch option. Baseline operation must be safe on 128 KB without probing expanded RAM. If boot glue would require writing custom assembly or raw hardware code, request review first; use the existing supported loader when sufficient.
The final README gives a short DOS loading recipe and a separately verified manual fallback, with the actual filenames/commands from the delivered disk. Do not publish placeholder loading commands as tested instructions.
11. Acceptance and evidence
- API prototype: actual 128 KB CoCo 3, seven-color screen, readable text, moving blocks, keyboard/joystick readings, sound, clean return and repeated disk access.
- Rules: all 28 rotation states; left/right boundaries; every kick candidate; rejected rotation unchanged; top spawn/block-out; gravity and hard/soft drop; simultaneous row compaction; hold queue preservation; shadow correctness.
- Scoring: every fixture in
scoring.json, including level transitions, Relaxed, bottom/non-bottom clears, both modes, and values above 32,767. - Randomness: deterministic CoCo seeds, weighted selection, difficult-piece metric fixtures, no simulation side effects, prefill never full.
- Input: repeat timings, conflicting keys, aliases, pause/release, menu guards, one-button-only start/play/hold/pause/settings/quit, both joystick ports and calibration. Capture a diagnostic showing actual sampled axes/buttons.
- Persistence: save/reload, read-only disk, absent/corrupt/partial data, reset/cancel, rule changes during play, all categories, and no writes outside designated files.
- Performance: measure input-to-visible-action and worst update times on ordinary 6809 settings. Target visible keyboard/joystick action within two video fields after the relevant edge (button rotation uses its release edge). Report p95 and worst values, separately for ordinary play, clears, sound and Difficult Pieces. A missed target prompts analysis/review, not unauthorized assembly.
- Configuration: separate evidence for CoCo 3 128 KB and 512 KB; physical hardware and emulator checks are distinct. Test PAL/NTSC timing if both claimed.
- Delivery: top-level built
Quadrapassel.DSK; source/build recipe; actual guest-only title and gameplay PNGs; concise run instructions, controls and credits; recorded revision/build/configuration, disk hash, memory budget, and test matrix.
No test is passed merely because the game compiled or the screenshot looks right. Keep pending external tests and unavailable MCP capabilities visible. The reference image and specification fixtures are not emulator validation evidence.