Files
Quadrapassel/docs/PROVENANCE.md
T

124 lines
6.9 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.
# Provenance and permitted use of reference material
## Behavioral reference
The specification was prepared from Brian Holman's
[Quadrapassel macOS fork](https://github.com/bkholman/quadrapassel-macos), revision
`be8769a403e506edb930372f963a9c4c83a0881e` ("Update references for
quadrapassel-macos repository"). Its upstream is
[GNOME Quadrapassel](https://gitlab.gnome.org/GNOME/quadrapassel).
Files reviewed for the specification include `src/game.vala`,
`src/game-view.vala`, `src/quadrapassel.vala`, `src/style.css`,
`data/org.gnome.Quadrapassel.gschema.xml`, `tests/test-scoring.vala`,
`tests/test-scoreboard.vala`, `README.md` and `COPYING`.
Their observed SHA-256 values are in [reference/source-manifest.json](reference/source-manifest.json).
The 28 piece states in [pieces.json](reference/pieces.json) were extracted from
`BLOCK_TABLE` in `src/game.vala` without changing positions or state order.
The numeric cases in [scoring.json](reference/scoring.json) express the reference
scoring rules and regression expectations, including new-level multiplication.
These files are data for the new implementation, not a bundled Vala application.
The CoCo game is an independently authored C implementation of this behavioral
specification. Linux/Mac application implementation is not incorporated. The
specification and derived reference data retain their GPL provenance; this
clean-room implementation does not erase their attribution or licensing.
## Credits and licensing
The reference application is **GPL-3.0-or-later**. `COPYING` preserves its GNU
GPL version 3 license text. `src/game.vala` credits **Robert Ancell (2010–2013)**
and **Lubomir Rintel (2009)**. The application's credits include **J. Marcin
Gorycki, Lubomir Rintel, Robert Ancell, John Ward, Will Warner**, and **Brian
Holman (macOS port)**. The difficult-piece selection describes its algorithm as
originating in **Federico Poloni's Bastet**. Retain these credits in the port.
The specification and derived piece/scoring reference data are distributed under
GPL-3.0-or-later. The game code preserves that license
and the relevant notices. The Mac fork's separate libgnome-games-support library
has its own LGPL-3.0-or-later terms; that library is not included here.
Pierre Sarrazin's CMOC/compiler and individual libraries/examples have their own
notices, including public-domain components. Check the exact files used; do not
label every example or bundled library GPL or public domain. Using a public API
does not require copying its implementation. No third-party sound recordings,
ROMs, Mac binaries or emulator source were imported into this repository.
## Supplied title image
[title-reference.png](reference/title-reference.png) is the image Brian supplied
for this project and explicitly authorized as its title reference. It is retained
unchanged and is **design reference only**, not a CoCo screenshot or runtime asset.
Its hash is recorded in the manifest. This permission is not a general grant to
relicense every visual element for unrelated reuse.
The CoCo screen should recreate the composition at native resolution with its
own game graphics: dark grid, colored tetrominoes and a readable title. Replace
the Mac platform wording with **for CoCo**. No other game's assets or implementation
are required for this reference treatment.
## Explicit adaptations
The specification identifies behavior adapted for the CoCo: conventional
persistent hold swapping, bounded score storage and rule markers, a compact
deterministic PRNG rather than GLib stream compatibility, one-button joystick
menus, approximate tone sequences, and safe handling
of pieces above the board. They must not be described as byte-for-byte Mac parity.
Current compatibility and reproducible build results are recorded in
[IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md). Earlier design estimates
and reference fixtures are distinct from guest execution evidence.
## CMOC example references consulted during implementation
Pierre Sarrazin's local CardGame 0.1.15 `beep-demo.c` (public domain) was consulted
for `initSound`, `getTicksForFrequency` and `beep` usage. CoCoLetters 0.1.0
`file.c`/`file.h` (Copyright 2026 Pierre Sarrazin, GPL-3.0-or-later) were consulted
for `decb_init`/`decb_registerDrive` initialization. The disk adapter follows
that initialization pattern, adds error handling, and uses the installed public
API contracts for writes, lengths and close/flush behavior. No standalone disk
driver, assembly sound routine or other game's rendering engine was copied.
The existing DOS loader is Pierre Sarrazin's public-domain autostart.c 0.1.2,
retained from the official disk-project template with the launch command adapted.
The audio correction also uses the documented bsound Player_disableSound API.
Only its standard mute helper is used; no Player IRQ or custom sound driver is
installed. The CardGame public-domain example implementation was consulted to
understand setup/teardown, without copying its assembly/register code.
## November 11 font update
The menu/HUD font is an unchanged subset of Pierre Sarrazin's public-domain
CardGame 0.1.15 font, also used by Color8. The original two font files, exact
SHA-256 values, source URL and public-domain notice are retained in
`third_party/cardgame-font/`. `src/platform/pierre_font.h` contains 26 letters,
ten digits and twelve punctuation glyphs. No drawing engine or assembly was
imported. Existing lowercase input maps to uppercase glyphs. The new C renderer
uses the original six visible columns/seven rows in each eight-pixel cell.
The scoring reference was checked on November 11 against revision
`be8769a403e506edb930372f963a9c4c83a0881e` confirms the existing Modern and
Classic (40.2) formulas. `scoring_through_drop` in tests/rules_test.c adapts the
GPL-3.0-or-later setup in its tests/test-scoring.vala to exercise actual piece
drops, bottom-row detection and level changes in the CoCo rules engine. No Mac
application code was changed or bundled.
For the build-02 joystick correction, Pierre Sarrazin's GPL-3.0-or-later
CoCoPlanes 0.1.0 coco-planes.c was consulted for its separate controller paths,
periodic sampling and active-low primary-button masks. Public coco.h keyboard
coordinates and Joystick.h contracts identify the shared input rows. No raw
register/interrupt/assembly code was copied. The new keyboard-row fixture is
authored for this repository; details are in JOYSTICK_FIX.md.
### CoCoMan joystick reference (November 11, 2026)
Brian explicitly authorized read-only access to his GPL CoCoMan checkout for
working joystick behavior. Relevant references: game/main.c controls and input
lifetime, game/keys.c shared button/keyboard rows, game/title.c stable button
scan. Observed base revision 439bd25ac46fbc7ecdfd67d98893a1cff90aef66 with local
main.c edits. No code/assets were imported and no CoCoMan files were changed.
Quadrapassel implements the learned safeguards in C using standard CMOC APIs;
it does not adopt CoCoMan's assembly or the VCC-specific input extension.