Chapter 8 of 9
Keep a field guide at hand
Use this page when a conversation and the CoCo seem to disagree. Start with a question the machine can answer now.
Identify the VCC Plus draft or project this connection shares. Report the guest CPU and the first reason a local run might be blocked.
Find the next action
| What you see | What to try |
|---|---|
| ChatGPT describes a different listing. | Ask for the shared title and first numbered line through get_capabilities and read_source. Share the intended BASIC editor through its own Local Assistant Access…. C and assembly each use a separate project connection. |
| The saved connection appears in settings, but a new chat cannot read the source. | Keep VCC Plus and the shared workspace open. Use Check Setup in the connection panel, open a fresh Work chat, and check /mcp. If you replaced the grant file, restart the corresponding server so the helper reads the new grant. |
| ChatGPT can read BASIC but cannot propose an edit, or an older connection lacks newer tools. | Save a fresh connection from the current app with the permissions you intend to grant. BASIC review uses Allow proposed edits and controls for runs I start; C has separate Make and disposable-playtest choices. Restart the corresponding server and discover its actual tools. |
| A proposal seems to have gone missing. | Ask for get_proposal using the returned proposal ID. A pending change awaits local review. If the draft has changed since the proposal, read its new revision and ask for a new proposal. |
| The C project builds in the workbench but the assistant build fails. | Check whether this grant uses the restricted recipe or the approved Use Project Makefile mode. Read get_build.first_error and the retained get_build_log. Inspect approved inputs and refresh locally changed build controls before trying again. |
| Build succeeded, but there is no run ID. | Check the run blockers in get_machine_status. In VCC Plus start the matching reviewed listing or shared build. For an interactive C game, choose Play in CoCo. |
| A run is waiting for a key. | Read the guest prompt. For a shared single-key menu, send one permitted key, then read again. An owned disposable run can use bounded physical input or playtest_debug to continue a verified stop; identify which kind of run you have first. |
| The guest asks for a whole line, or displays only a picture. | An owned disposable playtest supports playtest_input with letters, space, period, backspace and enter, plus framebuffer captures. Ordinary shared send_keys retains its smaller key set; type a whole line locally through Input → Focus CoCo Display when that is the connection you are using. |
| A short compiled program has already returned to BASIC. | Ask for get_run and its optional final_screen_text. This is the text captured when the program returned. Live key and screen access have ended. A graphics-only run may have no final text. |
| A key, run or memory read is refused after a change. | Stop sending input. Check the project revision, the guest and its media. For a new launch get the new run ID. For a new debugger stop get a new snapshot and read within one of its reported ranges. |
| Startup took longer than a transport request. | Keep the reserved run and original request IDs. Poll get_run for phase and readiness. A ready receipt is separate from reaching a breakpoint. Use stop_playtest to cancel; do not create a second start request to guess whether the first worked. |
| A C function has no mapped stop. | Read get_build.source_debugging. A name in functions supports a C-line stop; a verified entry in function_entries can use function_entry without claiming a C statement. A source-only build may expose an executable symbol with unavailable variables. |
| The run has reached a request or audio limit. | Read the remaining budgets. Stop and retain the owned disk with stop_playtest, which is exempt from execution request limits. If saving is pending, retry the original stop request; keep the app open until retention succeeds. |
Keep the program you already have
An editor draft on the Mac and a listing in CoCo BASIC memory can contain two different programs. If the C workbench says BASIC is occupied, save the open editor draft first. At a supported BASIC prompt, use Read from CoCo in BASIC Development, then Save As… to preserve the guest listing in its own file. Read-back saves program text. The variables and the place where a program paused belong to that execution.
Only when you want to clear the guest listing and its variables, type NEW yourself at the CoCo's OK prompt. Ordinary C needs empty BASIC memory. The Hello Disk verification also needs an empty floppy drive 0 for the disk it creates. For a shared run, finish recordings, eject the cassette, and eject or write-protect writable floppy and hard disks. End an active Mac shell session, turn off DriveWire networking, and use a BASIC setup with only the floppy controller if the status report calls for it. Handle any save or export prompt before ejecting your media.
Applying a proposal updates an editor draft. Use the workspace's Save command when you want to keep that change on disk. A grouped project edit has a grouped Undo while the applied revision is current. If you have edited either file since, inspect both current drafts before deciding what to restore.
What to ask for
The table describes current tools. Each workspace and saved grant exposes its own subset; discover that subset before asking for an operation.
| Task | Tools and useful limits |
|---|---|
| Identify the workspace and machine | get_capabilities identifies the shared draft or project. get_machine_status reports the emulated processor, devices, build status and run blockers. |
| Look up a CoCo detail | search_help returns matching installed manual sections. Give read_topic a topic ID returned by the search. If the result is marked truncated, open that section in Help → Manual Library…. |
| Read source | read_source reads a BASIC draft. read_project_file reads a named shared C or assembly file. Open editor drafts can include unsaved changes. |
| Propose a change | BASIC has propose_edit for one existing numbered line and propose_listing for a complete numbered ASCII listing up to 12 KiB. C and assembly have propose_fix for a line and propose_project_edits for complete replacements of one to eight existing shared files, up to 16 KiB in total. A C line repair needs a matching compiler diagnostic. |
| Check the review or build | get_proposal retrieves the native review decision. In C and assembly, build_project requests a build of a revision and get_build reads its status and diagnostics. |
| Refresh a C project's inputs | read_project_inputs pages the approved manifest, up to 256 rows per page. refresh_project requests adoption or local review; get_project_refresh polls that decision. Neither executes the recipe. |
| Read the build failure | get_build reports diagnostics, first error, status and stage when known. get_build_log reads retained combined output in pages up to 32,768 UTF-8 bytes; follow next_offset and report truncation. |
| Deliver declared build files | On a separately approved export connection, get_build.exportable_outputs lists exact output identities. export_build_outputs selects the original build/artifact/revision and approved destination; poll get_build_export, then independently verify delivered lengths and hashes. It does not rebuild or export guest saves. |
| Play a text game | get_run identifies the run you started. read_screen_text observes the guest text. send_keys accepts one ASCII letter, digit or space per ordinary key request, up to 64 distinct accepted requests per run. Give each intended press a fresh request ID. Reuse the same ID and identical key to retry an uncertain delivery. |
| Inspect a stop | get_debug_snapshot describes a verified stop, available watches and readable ranges. read_debug_memory reads 1–256 bytes wholly within one advertised snapshot range. Device I/O is outside those ranges. |
| Inspect an owned call | When advertised by a fresh C playtest grant, get_call_context uses the same run/snapshot IDs for a fixed 64-byte view at actual S. Treat raw words as uninterpreted; accept caller/argument labels only with verified evidence. It does not grant arbitrary stack addresses or shared-run access. |
These tools require the C connection's Allow Disposable Playtests grant and the corresponding live capability. They operate on the assistant's separate test machine, rather than the personal CoCo used by the earlier lessons.
| Task | Owned-playtest tools and useful limits |
|---|---|
| Start or check preparation | start_playtest binds the current project, revision and artifact. get_run polls its reserved run. Fresh processor-aware grants accept MC6809 or HD6309; the default is MC6809. |
| Enter a line or hold a chord | playtest_input accepts up to 64 steps, eight distinct physical keys per chord, 1–600 fields per step and 3,600 fields per request. period is a physical key; backspace and left name the same physical key. Empty keys releases input. |
| Test a joystick | Fresh connections accept optional joysticks per input step: right/left port, integer X/Y 0–16383 (center 8191) and fire1/fire2. Omitted ports center and release. input_trace records delivery; inspect actual gameplay frames for the result. |
| Diagnose input | get_playtest_input reads owned input without advancing. Shared get_machine_status.input distinguishes host preview, last submission and actual core input, including connection/focus availability. |
| Capture a picture | capture_playtest returns the last published framebuffer without advancing. At a paused state, capture_playtest_graphics can compare the current register-selected display with a verified declared buffer ID, including a bounded GIME canvas. |
| Capture sound | capture_playtest_audio advances 1–120 fields and returns a PCM16 stereo WAV, then leaves the guest paused. It uses no microphone. Read actual timing and remaining audio allowance. |
| Record gameplay for a manual | On a video-enabled connection, start_playtest_video starts a bounded MP4 clip from an owned playtest. Ordinary input drives the recorded guest fields; waiting between calls adds no footage. stop_playtest_video completes the clip, and read_playtest_video returns bounded chunks for saving and verifying it. Choose CoCo audio per clip. Mac windows, microphone and host capture cues are excluded. Inspect completion/truncation, field counts, byte count and SHA-256 before including a clip in a manual. |
| Pause or inspect code | playtest_debug offers pause, continue, instruction step, and verified named stop_at. Match stop_kind to the build's C-line or function-entry evidence, then request a fresh debug snapshot. |
| Use Home and Data together | Fresh multi-drive grants expose drive 0–3 on exchange_playtest_media, defaulting to FD0. Pause with the shared controller idle; use listed private-copy IDs and current hashes, optional insert-time protection, and per-drive receipts. Never silently move one writable copy between drives. |
| Test Save and Load | restart_playtest cold-boots with the current mount map and writable copies. stop_playtest retains every copy; list_playtest_disks finds project-scoped records. Resume by retained ID and exact hash under compatible base-artifact bytes, then use the guest's Load command. |
Give each intended mutation a fresh request ID. Reuse the same ID and identical arguments to recover an uncertain delivery; changing its meaning is a conflict. An owned run has 216,000 field attempts, 16 boots and 1,024 mutation requests. Breakpoints can shorten plans, so use actual returned clocks. Keys and joystick buttons are released and axes centered when an input plan finishes. These are upper bounds, not a promise that a game will reach its intended checkpoint. Stop/retention remains available for cleanup.
BASIC also accepts one fixed probe, PRINT 7 followed by a newline, to verify that the interpreter returned to its prompt. Type your own direct-mode commands at the guest keyboard.
For a manual lookup, start with terms a CoCo book would use.
Search the installed manuals for INKEY$. Read a matching section and explain what the function returns when nobody has pressed a key.
Close or renew a connection
Use Revoke Access in BASIC or C, or Revoke Connection in assembly, when you finish sharing. Revocation disables the grant and removes its file. Text already returned to a conversation can remain there. If you want to work together again, open the intended workspace, save a fresh connection, and restart that server in ChatGPT. A different saved path can be registered through Add to ChatGPT. Keep the private connection file on your Mac.
Words you will meet
Guest means the emulated CoCo. Host means the Mac that runs VCC Plus. A host with Apple silicon can still be running an MC6809 guest.
Grant is the private connection file that authorizes access to a selected workspace. MCP stands for Model Context Protocol, the interface ChatGPT uses to call the tools offered by that connection.
Revision identifies a particular version of the editor draft or shared project. A build translates a compiled project revision. A run identifies one launch on the guest.
A breakpoint pauses execution at a chosen location. A watch is a named value you want to inspect there. A snapshot records the verified stop and the memory ranges the assistant can read from it. On the next debugging pass, ask which run and which stop supplied the value you are comparing.