Prepare public CoCo 3 documentation and portable VCC Plus workflow
This commit is contained in:
1 parent
e9574b6f0d
commit
4aa739780c
16 files changed
+572
-913
No files matched your search
+97
-128
@@ -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.
|
||||
Reference in new issue
Block a user