Prepare public CoCo 3 documentation and portable VCC Plus workflow

This commit is contained in:
Brian Holman committed 2026-11-11 16:43:19 -07:00
1 parent e9574b6f0d
commit 4aa739780c
16 files changed
+572 -913

No files matched your search

+97 -128
View File
@@ -1,152 +1,121 @@
# VCC Plus development workflow
# Build and test with VCC Plus
## Required installed app
Use the official [VCC Plus for Mac download](https://vccplus.brianholman.com/downloads/)
and the complete [Quadrapassel source repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel).
The public installed app supplies CMOC, Make, Perl, libraries and disk tools for
this project. Homebrew and a separate emulator/toolchain build are not required
for the installed C-workspace workflow.
Use `/Applications/VCC Plus.app`, **version 3.6.1, build 54**. Brian requested the final
Quadrapassel test after Core installed it on November 11, 2026. Earlier build53
checks remain historical. The installed
Info.plist was verified. Earlier build-48 evidence remains historical.
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.
## Open the existing project
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.
1. Obtain the complete repository in a writable local folder. Do not download
only `main.c`: the game also needs headers, platform/rules files, text assets,
generator scripts, the Makefile and `vccplus-project.json`.
2. Choose **Develop → C Development…** in VCC Plus and open that existing project.
Keep the supplied settings rather than creating a new Hello Disk project over it.
3. Select **Release**. The game uses its declared Make recipe and `disk` action.
4. Choose **Build Disk**. The configured Build target also produces the disk;
use the action displayed by your installed workspace.
5. Read the complete result, including diagnostics and the memory-bound check.
Use **Show Build Products** to find the build's `Quadrapassel.DSK` and `QUAD.bin`.
VCC Plus builds in a separate work area, so the latest result need not appear
beside the original source files.
## Reference access through MCP
Release uses the optimization needed by the bounded memory layout. Preserve
`--data=0E00`, `--limit=7B00` and the 1024-byte stack reserve. The additional link-map
check enforces code/constant addresses `$1400..$7AFF` and static-data addresses
`$0E00..$13FF`.
Do not weaken these guards to make Debug or a larger edit fit.
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.
A fresh anonymous checkout has rebuilt the exact build-05 binary and disk using
the public VCC Plus 3.6.1 bundled Release toolchain. The pristine disk hash is
`d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
See [BUILDS.md](BUILDS.md) for delivery identities and
[MEMORY_LAYOUT.md](MEMORY_LAYOUT.md) for the section contract.
**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.
## Launch without losing another program
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.
Save guest programs, source drafts and pending media changes before launching.
**Launch Disk** uses the built disk and the project's declared `DOS` command;
attend to the app's normal floppy-replacement and restart confirmations. Use a
writable test copy and preserve personal score disks.
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.
Mounting a different disk does not replace the program in RAM. For a new build,
start it from a clean Disk BASIC state and actually load it with `DOS`. Verify the
running artifact as well as the mounted filename. The manual loading alternative
is `PCLEAR1`, `LOADM"QUAD.BIN"`, then `EXEC`.
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`.
The game supports **CoCo 3 with 128 KB or more**. 128 KB emulation and physical
512 KB CoCo 3 play have been verified. Set up the intended machine and record its
actual RAM/CPU/video configuration when testing a change.
## Standard APIs before optimization
## Connect ChatGPT to this C project
Begin with the public CMOC `coco.h` interface:
Open **Assistant…** in the C workspace, review the shared files, and select
**Use Project Makefile**. Allow disposable playtests when isolated execution is
wanted. Save a new private connection using the supported export process and
connect it to your assistant. Do not post its token or connection file in source,
issues or chat messages.
| 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 |
Begin with live discovery and a real capabilities request. Confirm this project's
files, revision, approved recipe, declared configuration and disk action. Use only
the tool names and argument schemas returned by the installed connection. The
[MCP setup guide](MCP_SETUP.md) gives a portable checklist; it does not require
a machine-specific connection.
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.
For an owned disposable run:
`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.
1. Build the current revision's declared disk action in **Release** and inspect
its result. Bind later observations to its artifact identity.
2. Start a fresh owned playtest of that artifact and poll startup as documented.
A supported retained test disk can be selected only with its matching receipt.
3. Send ordinary guest input, including release intervals. Capture real guest
graphics/audio when those capabilities are advertised. Never change guest
memory/registers to manufacture a score or screen.
4. Test the affected controls, gameplay, saves and return paths. Use advertised
read-only inspection when appropriate; do not invent unavailable debug values.
5. Stop the owned run and retain its writable test-disk receipt. Do not stop
another person's game or delete its media.
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.
Disposable-worker choices depend on the installed app. If a worker advertises
512 KB, that describes the test configuration, not the game's minimum memory.
Do not describe a 512 KB run as an additional 128 KB check. Likewise, actual
joystick states and keyboard aliases are different test evidence. Use supported
native input or a user-controlled physical test when a capability is absent.
## Project, build and playtest sequence
Before pointer/keyboard automation, obtain a current idle, unlocked desktop window
unless the user has already granted one for that work. Keep personal machine
settings and media separate from disposable tests.
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.
## Documentation and references
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:
Use **Help → Manual Library…** and discover its search/read tools through the
project connection. For historical CoCo material, **Archive Library…** has its
own read-only sharing connection. Verify each access separately before falling
back to an unrelated source. Public installed CMOC headers/examples are also
valid API references; emulator internals are outside this game's workflow.
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.
Public manual chapters describing the interface and sequence:
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.
- [Build a disk from a folder](https://vccplus.brianholman.com/manuals/programming-in-c/disk-project/)
explains Build, Build Disk, Launch Disk and Show Build Products.
- [Make the first connection](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
explains private connection exports and verifying real access.
- [Build a quiz and give ChatGPT the keyboard](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
demonstrates opening an existing public C project and its Make/disposable loop.
## Memory and input qualification
Use standard documented CMOC APIs before new hardware-specific code. The existing
bounded C graphics renderer is a recorded exception; see [AGENTS.md](../AGENTS.md)
and [DECISIONS.md](DECISIONS.md) for its scope. Preserve component licenses.
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.
## Numbered delivery and save data
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.
The recipe's `Quadrapassel.DSK` is a clean staging image. Delivered builds use
`QUADPSLxx.DSK`, with a two-digit number; each changed delivery gets a new filename
and starts with empty high scores/default settings. Verify that neither QPSAVE
file is included before copying to a new numbered filename, compare hashes, and
record the result in [BUILDS.md](BUILDS.md).
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.
## Numbered game delivery
Brian's latest November 11 convention is `QUADPSLxx.DSK`, beginning with 01,
with empty high scores/default preferences for each new delivery. Keep the
official recipe and MCP artifact at its existing staging name, Quadrapassel.DSK.
Verify no QPSAVE data is present, copy to a new numbered filename without
overwriting, compare hashes, and record it in BUILDS.md. Old personal disks
remain untouched; automatic score migration is no longer part of delivery.
Never overwrite an existing numbered or personal disk to deliver a build. Preserve
mounted media, score disks and backups during cleanup. Score migration is a
separate requested action, not an automatic part of a game update.