8.5 KiB
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
- 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.
- Use
search_helpandread_topicfor the installed manuals and API reference. Suggested first queries:hscreen hset palette,joystick,keyboard,CMOC graphics memory,sound,disk project DOSandMCP playtest. Search/read may need separate short queries; follow the returned schema. - 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.
- 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
for CoCo 2 validation and Chris Lomont's CoCo hardware reference
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:
get_capabilitiesand project input/file readers identify the shared project.- 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.
build_projecttakes the current project/revision, an advertisedbuildordiskaction and declared configuration. Pollget_build; inspect the build log. Do not invent target names or bypass recipe review.- Start an isolated playtest from the returned artifact. Poll its run status. Match source revision and artifact identity before accepting a result.
- 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.
- 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.