Add Quadrapassel CoCo specification and reviewed implementation workflow
This commit is contained in:
commit
8a4b44bc73
13 files changed
+2250
No files matched your search
@@ -0,0 +1,141 @@
|
||||
# VCC Plus development workflow
|
||||
|
||||
## Required installed app
|
||||
|
||||
Use `/Applications/VCC Plus.app`, **version 3.5.5, build 48**. These values were
|
||||
read from the installed app's `Info.plist` on November 10, 2026 after Brian
|
||||
confirmed installation of official build 48. Verify again at implementation start.
|
||||
If the app differs, report it and wait for Brian to approve a different version.
|
||||
Do not downgrade, overwrite, or build a replacement app.
|
||||
|
||||
Use the official app's supported MCP sharing/export flow for the Quadrapassel
|
||||
project. No custom VCC Plus executable, private helper protocol, substitute MCP
|
||||
server, injected code, private endpoints or emulator modifications are authorized.
|
||||
The fact that a binary or source checkout exists on the machine is not permission
|
||||
to use it. This game is a client of the installed product.
|
||||
|
||||
## Reference access through MCP
|
||||
|
||||
1. Discover the tools advertised by the intended connection. Query capabilities
|
||||
and confirm the selected project/root, files, revision, approved build recipe,
|
||||
available build configurations and runtime controls.
|
||||
2. Use `search_help` and `read_topic` for the installed manuals and API reference.
|
||||
Suggested first queries: `hscreen hset palette`, `joystick`, `keyboard`,
|
||||
`CMOC graphics memory`, `sound`, `disk project DOS` and `MCP playtest`.
|
||||
Search/read may need separate short queries; follow the returned schema.
|
||||
3. Use the advertised historical archive search and document-reading tools when
|
||||
present. Consult relevant CMOC, CoCo graphics, keyboard, joystick and disk
|
||||
references. Read cited sections rather than relying on search snippets.
|
||||
4. Record the actual tool names and document/topic identities in the implementation
|
||||
notes. Tool availability may differ from this planning-time inventory.
|
||||
|
||||
**Planning-time limitation:** the available older project-specific connection
|
||||
returned `host_unavailable`. Its advertised documentation tools were
|
||||
`search_help`/`read_topic`; a live build-48 archive search was not verified during
|
||||
specification preparation. This is not a claim that build 48 lacks archive support.
|
||||
The implementation chat must discover and use the correct official connection.
|
||||
Report unavailable access and ask for that connection to be enabled if necessary;
|
||||
do not request emulator features or create a replacement integration to fill a gap.
|
||||
|
||||
Allowed fallback references include the public manuals in
|
||||
`/Applications/VCC Plus.app/Contents/Resources/ManualLibrary`, public headers in
|
||||
`/Applications/VCC Plus.app/Contents/Resources/Toolchain/share/cmoc/include`,
|
||||
and public examples shipped in the official app. Read public API contracts, not
|
||||
private headers or library implementation files. The installed public manual's
|
||||
`programming-in-c/examples/beacon.c` demonstrates `hscreen`, `hset`, palette and
|
||||
standard BGraph use; it is a reference, not permission to copy raw register access
|
||||
from an example without the exception review.
|
||||
|
||||
Pierre's programs and other examples under
|
||||
`/Users/bholman/Development/Personal/VCC/CMOC/Repositories/` are also permitted
|
||||
read-only references. Inspect the selected example's license before reusing code.
|
||||
Search within that folder or an individual example, not the parent VCC directory.
|
||||
Do not read the Mac Quadrapassel implementation or private VCC Plus material.
|
||||
|
||||
Useful public references include the [XRoar author's manual](https://www.6809.org.uk/xroar/doc/xroar.shtml)
|
||||
for CoCo 2 validation and [Chris Lomont's CoCo hardware reference](https://www.lomont.org/software/misc/coco/Lomont_CoCoHardware.pdf)
|
||||
when a public hardware description is needed. Reading these is allowed; implementing
|
||||
raw hardware access still requires the approval process in `AGENTS.md`.
|
||||
|
||||
## Standard APIs before optimization
|
||||
|
||||
Begin with the public CMOC `coco.h` interface:
|
||||
|
||||
| Need | Initial public API candidates |
|
||||
| --- | --- |
|
||||
| CoCo 3 display | `hscreen`, `hset`, `palette`, `paletteRGB`, `rgb` / `cmp` |
|
||||
| CoCo 2 display | `pmode`, `pcls`, `screen`; documented standard graphics-library routines |
|
||||
| Keyboard | `isKeyPressed`, `inkey`, documented keyboard helpers |
|
||||
| Joystick | `readJoystickPositions`, `readJoystickButtons`, named port/button constants |
|
||||
| Timing/speed | `getTimer`, `setTimer`, `setHighSpeed` with their documented contracts |
|
||||
| Sound | `sound` or documented standard CMOC sound-library APIs |
|
||||
| Disk | Documented standard CMOC disk/file libraries selected through Project Settings |
|
||||
|
||||
Check actual header/manual contracts and return codes. Do not infer exact behavior
|
||||
from names. In particular, the public `coco.h` joystick button prose and its named
|
||||
bit constants have inconsistent ordering in the inspected header; confirm both
|
||||
physical ports in the API probe instead of hardcoding a guess.
|
||||
|
||||
`hscreen`/`hset` use BASIC's graphics workspace. They are distinct from the
|
||||
VCC-specific `vcc/gime.h` helper whose documented contract requires at least
|
||||
512 KB. The latter is not the baseline and would need exception review. Do not
|
||||
infer that 128 KB needs a custom renderer just because that helper needs more RAM.
|
||||
|
||||
Compose ordinary game rendering with standard APIs first, update changed cells,
|
||||
and measure. Direct framebuffer access, custom register code, assembly or a
|
||||
nonstandard extension remains gated even when an example contains it. Prefer a
|
||||
manual machine/target choice to an unapproved raw detection routine.
|
||||
|
||||
## Project, build and playtest sequence
|
||||
|
||||
Create the game project using the installed C Development workflow and its public
|
||||
project template. Keep source and settings in this repository. The official app
|
||||
can create a standard disk-project recipe; keep that recipe and its resource/DOS
|
||||
configuration reproducible. Do not add game code to the emulator repository.
|
||||
|
||||
The previously advertised MCP pattern is listed below as a discovery aid, not a
|
||||
promise that every build-48 connection has the identical tool set:
|
||||
|
||||
1. `get_capabilities` and project input/file readers identify the shared project.
|
||||
2. Make normal repository edits or use the advertised reviewed edit proposal flow.
|
||||
New files, assembly (only after approval), or Make changes must use a supported
|
||||
project update/review path. Refresh and inspect the resulting revision.
|
||||
3. `build_project` takes the current project/revision, an advertised `build` or
|
||||
`disk` action and declared configuration. Poll `get_build`; inspect the build
|
||||
log. Do not invent target names or bypass recipe review.
|
||||
4. Start an isolated playtest from the returned artifact. Poll its run status.
|
||||
Match source revision and artifact identity before accepting a result.
|
||||
5. Exercise keyboard input, capture the guest screen/graphics and capture bounded
|
||||
guest audio with the advertised tools. Use documented guest debugger inspection
|
||||
when useful. Do not reach into emulator implementation state.
|
||||
6. Stop the owned run through the supported tool. Preserve writable disk results
|
||||
and useful evidence. Do not operate another project's connector or live session.
|
||||
|
||||
A CLI invocation of the installed bundled toolchain can supplement diagnosis if
|
||||
documented, but it is not a substitute for building and running through the
|
||||
official VCC Plus workflow. Do not silently substitute Homebrew or another compiler.
|
||||
|
||||
## Memory and input qualification
|
||||
|
||||
The planning-time `start_playtest` contract described a fixed **512 KB** isolated
|
||||
machine with a 6809/6309 choice. Recheck build 48's actual advertised schema. If it
|
||||
still cannot select 128 KB, test that memory size through the official app's normal
|
||||
Machine Settings interface in an isolated user-approved session. Its installed
|
||||
user manual lists 128 KB as a supported memory selection. A 512 KB playtest alone
|
||||
does not establish 128 KB compatibility.
|
||||
|
||||
No joystick injection tool was present in the planning-time inventory. Check the
|
||||
actual build-48 connection. Use normal supported app input or Brian's joystick /
|
||||
XRoar testing where MCP cannot supply it. Keyboard events are not evidence that
|
||||
analog sampling, dead zones or both joystick ports work.
|
||||
|
||||
Before desktop pointer/keyboard automation, obtain Brian's current idle-desktop
|
||||
grant. Use only supported isolation and preserve active media/settings. Do not
|
||||
launch another ordinary instance that competes for the same saved state. If a
|
||||
safe isolation path is unavailable, continue independent work and request a
|
||||
specific manual check rather than changing the installed app.
|
||||
|
||||
For XRoar, give Brian a pristine DSK copy, exact machine/RAM/clock/ROM requirements,
|
||||
loading steps, controls, expected results and an evidence checklist. Do not
|
||||
redistribute private ROMs. Separate user-confirmed CoCo 2 results from VCC Plus
|
||||
CoCo 3 compatibility runs. Keep screenshots limited to the guest display.
|
||||
Reference in new issue
Block a user